Autoryzacja dodatku Edytor

W większości przypadków musisz autoryzować dodatek, zanim będzie można go używać. W wielu projektach Apps Script, takich jak aplikacje internetowe, autoryzacja jest prosta – projekt skryptu prosi o wszystkie brakujące uprawnienia, których próbujesz użyć. Po uzyskaniu uprawnień możesz korzystać z projektu skryptu. Każdy, kto korzysta z projektu skryptu, autoryzuje go oddzielnie.

Model autoryzacji dodatków do edycji jest bardziej skomplikowany. Te dodatki działają w przypadku plików znajdujących się na Dysku Google, które można udostępniać innym osobom, dlatego musisz utworzyć dodatki do edytorów z uwzględnieniem różnych trybów autoryzacji. Aplikacje edytora Google Workspace udostępniają też w menu menu Dodatki, które są wypełniane przez zainstalowane dodatki, nawet jeśli nie zostały jeszcze przez Ciebie autoryzowane. To zwiększa złożoność modelu autoryzacji.

Model autoryzacji

Dwie właściwości dodatków do edycji upraszczają udostępnianie i używanie:

• Gdy pobierzesz ze sklepu dodatek do edytora, zobaczysz go w menu Dodatki dla każdego otwartego lub utworzonego dokumentu. Współpracownicy nad tymi dokumentami mogą go zobaczyć oprócz tych, których faktycznie używają.
• Gdy użyjesz dodatku edytora w dokumencie, Twoi współpracownicy zobaczą go również w menu Dodatki, ale tylko w tym dokumencie (chyba że mają go zainstalowany).

Dla większości użytkowników ten model udostępniania jest naturalny. Ponieważ jednak dodatek do edytora automatycznie uruchamia funkcję onOpen(e), aby dodać elementy menu po otwarciu dokumentu, opisane powyżej zachowanie zwiększa złożoność reguł autoryzacji Apps Script. Ostatecznie użytkownicy nie czują się komfortowo, gdy dodatek otwiera dane osobowe przy każdym otwarciu dokumentu. Ten przewodnik pomoże Ci zrozumieć, jak i kiedy kod może działać.

Zainstalowane a włączone

Jeśli w menu widzisz dodatek edytora, oznacza to, że jest on zainstalowany i włączony w jednym z tych stanów (lub obu). Dodatek do edytora jest zainstalowany dla konkretnego użytkownika po tym, jak wybierze go w sklepie i zezwoli na dostęp do jego danych Google. Dodatek jest włączony w danym dokumencie, gdy ktoś z niego korzysta. Jeśli nad dokumentem pracują 2 osoby, a jedna z nich korzysta z dodatku, jest on instalowany dla jednego użytkownika i włączony dla tego dokumentu.

Poniższa tabela zawiera podsumowanie obu stanów. Pamiętaj, że podczas testowania skryptu jako dodatku możesz uruchomić test w jednym lub w obu tych stanach.

	Zainstalowano	Włączona
Dotyczy:	Użytkownik	Dokument
Powód	Dodatek do sklepu	Instalowanie dodatku ze sklepu podczas korzystania z tego dokumentu lub używanie wcześniej zainstalowanego dodatku w tym dokumencie
Menu widoczne dla	Tylko ten użytkownik we wszystkich dokumentach, które otworzył	Wszyscy współpracownicy w tym dokumencie
onOpen(e) działa w	AuthMode.NONE (chyba że jest też włączony). W takim przypadku AuthMode.LIMITED)	AuthMode.LIMITED

Tryby autoryzacji

Dodatek do edytora automatycznie uruchamia funkcję onOpen(e), by dodać pozycje menu po otwarciu dokumentu, ale aby chronić użytkowników. Skrypt Apps Script ogranicza możliwości funkcji onOpen(e). Jeśli dodatek nie był używany w bieżącym dokumencie, te ograniczenia nasilają się.

Stany instalacji i włączenia określają, w którym trybie autoryzacji działa funkcja onOpen(e). Apps Script przekazuje tryb autoryzacji jako właściwość authMode parametru zdarzenia Apps Script (e). Wartość e.authMode odpowiada stałej wartości wyliczenia Apps Script ScriptApp.AuthMode.

Jeśli w bieżącym dokumencie włączony jest dodatek do edytora, onOpen(e) działa w przeglądarce AuthMode.LIMITED. Jeśli dodatek nie jest włączony, a jedynie zainstalowany, wtyczka onOpen(e) będzie działać w systemie AuthMode.NONE.

Tryby autoryzacji mają zastosowanie do wszystkich uruchomień Apps Script – np. uruchamiania w edytorze skryptów, w menu lub za pomocą wywołania Apps Script google.script.run. Właściwość e.authMode można sprawdzić tylko wtedy, gdy skrypt jest uruchamiany w wyniku działania reguły takiej jak onOpen(e), onEdit(e) lub onInstall(e). Funkcje niestandardowe w Arkuszach Google korzystają z własnych trybów autoryzacji, AuthMode.CUSTOM_FUNCTION, które jest podobne do LIMITED, ale różnią się od niego kilkoma ograniczeniami. Pozostałości skryptów w czasie AuthMode.FULL są zgodne z poniższą tabelą.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Występuje w	onOpen(e) (jeśli użytkownik zainstalował dodatek, ale nie włączył go w dokumencie)	onOpen(e) (wszystkie pozostałe) onEdit(e) (tylko w Arkuszach)	Funkcje niestandardowe	Wszystkie pozostałe okresy, w tym: reguły do zainstalowania onInstall(e) google.script.run
Dostęp do danych użytkownika	Tylko język	Tylko język	Tylko język	Tak
Dostęp do dokumentu	Nie	Tak	Tak – tylko do odczytu	Tak
Dostęp do interfejsu	Dodawanie pozycji menu	Dodawanie pozycji menu	Nie	Tak
Dostęp do funkcji Properties	Nie	Tak	Tak	Tak
Dostęp do funkcji Jdbc, UrlFetch	Nie	Nie	Tak	Tak
Inne usługi	Logger Utilities	Usługi, które nie mają dostępu do danych użytkownika	Usługi, które nie mają dostępu do danych użytkownika	Wszystkie usługi

Cały cykl życia.

Jeśli dodatek jest zainstalowany dla bieżącego użytkownika lub włączony w bieżącym dokumencie, zostanie on wczytany, co spowoduje, że pojawi się on w menu Dodatki i zacznie korzystać z prostych reguł onInstall(e), onOpen(e) i onEdit(e). Jeśli użytkownik kliknie jeden z elementów menu dodatku, zostanie on uruchomiony.

Instaluję

Gdy dodatek do edytora jest zainstalowany ze sklepu, jego funkcja onInstall(e) działa w systemie AuthMode.FULL. To działanie umożliwia przeprowadzenie złożonej rutyny konfiguracji, ale ważne jest również, aby używać właściwości onInstall(e) do tworzenia elementów menu, ponieważ dokument jest już otwarty i funkcja onOpen(e) nie została uruchomiona. Możesz też zadzwonić do usługi onOpen(e) z usługi onInstall(e), jak pokazano w tym przykładzie:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Otwieranie

Gdy dokument się otwiera, wczytuje się każdy dodatek do edytora, który ma zainstalowany bieżący użytkownik lub który współpracownik włączył w dokumencie. Wywołuje on wszystkie funkcje onOpen(e). Tryb autoryzacji, w którym działa onOpen(e), zależy od tego, czy dodatek jest zainstalowany czy włączony.

Jeśli dodatek tworzy tylko menu podstawowe, tryb nie ma znaczenia. Ten przykład pokazuje, jak może wyglądać prosty element onOpen(e):

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Jeśli jednak chcesz dodawać dynamiczne pozycje menu na podstawie zapisanych właściwości Apps Script, odczytać zawartość bieżącego dokumentu lub wykonać inne zaawansowane zadania, musisz wykryć tryb autoryzacji i odpowiednio go obsłużyć. Ten przykład pokazuje, jak może wyglądać zaawansowana funkcja onOpen(e), zmieniając jej działanie w zależności od trybu autoryzacji:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

W toku

Gdy ktoś kliknie jeden z elementów menu dodatku, Apps Script najpierw sprawdza, czy użytkownik zainstalował ten dodatek, i prosi o jego zainstalowanie. Jeśli użytkownik autoryzował dodatek, skrypt uruchomi funkcję odpowiadającą pozycji menu w elemencie AuthMode.FULL. Dodatek zostanie również włączony w dokumencie, jeśli jeszcze nie był włączony.