Autoryzacja dodatku Edytor

W większości przypadków musisz najpierw autoryzować dodatek. Autoryzacja w przypadku wielu projektów Apps Script, takich jak aplikacje internetowe, jest prosta – prosi o wszystkie brakujące uprawnienia potrzebne do korzystania z projektu. Po autoryzacji możesz używać projektu skryptu bezpłatnie. Każdy użytkownik projektu skryptu osobno ją autoryzuje.

Model autoryzacji dodatków do edycji jest bardziej złożony. Te dodatki działają w przypadku plików pozostających na Dysku Google, czyli plików, które można udostępniać innym, dlatego należy utworzyć dodatki do edytorów uwzględniające różne tryby autoryzacji. Aplikacje edytora Google Workspace udostępniają w interfejsie użytkownika menu Dodatki, które jest zainstalowane przez zainstalowane dodatki, nawet jeśli nie zostały one jeszcze autoryzowane. Spowoduje to dodatkowe złożoność modelu autoryzacji.

Model autoryzacji

2 właściwości dodatków do edycji ułatwiają udostępnianie i korzystanie z nich:

• Gdy pobierzesz dodatek ze sklepu, pojawi się on w menu Dodatki dla każdego otwartego lub utworzonego przez Ciebie dokumentu. Współpracownicy nad tymi dokumentami nie zobaczą dodatku, z wyjątkiem dokumentów, w których faktycznie korzystasz z tego dodatku.
• Gdy skorzystasz z dodatku do edytora w dokumencie, współpracownicy zobaczą go również w menu Dodatki, ale tylko w tym dokumencie (chyba że zainstalowali go również).

Dla większości użytkowników ten model udostępniania wygląda naturalnie. Ponieważ jednak dodatek do edytora automatycznie uruchamia funkcję onOpen(e) w celu dodania elementów menu po otwarciu dokumentu, opisane powyżej działanie komplikuje reguły autoryzacji Apps Script. W końcu użytkownicy nie czuliby się w komforcie dzięki dostępowi do danych osobowych za każdym razem, gdy otwierają dokument. Z tego przewodnika dowiesz się, do czego służy Twój kod i kiedy.

Zainstalowane a włączone

Jeśli widzisz w menu dodatek do edytora, może on być zainstalowany lub włączony w jednym z tych stanów (lub w obu). Dodatek do edytora jest instalowany dla określonego użytkownika po wybraniu go w sklepie i autoryzowaniu dostępu do jego danych Google. W dodatku dodatek jest włączony w danym dokumencie, gdy ktoś używa go w tym miejscu. Jeśli 2 osoby współpracują nad dokumentem, a jedna z nich korzysta z dodatku, jest on instalowany na tym samym koncie użytkownika i włączony w tym dokumencie.

Tabela poniżej zawiera podsumowanie 2 stanów. Pamiętaj, że testując skrypt jako dodatek, możesz uruchomić test w którymś z tych stanów.

	Zainstalowano	Włączona
Dotyczy:	Użytkownik	Dokument
Powód	Pobieranie dodatku ze sklepu	Uzyskiwanie dodatku ze sklepu podczas korzystania z tego dokumentu lub Użycie dodatku zainstalowanego wcześniej w tym dokumencie
Menu widoczne dla:	Tylko ten użytkownik we wszystkich dokumentach, które otworzył lub utworzył	Wszyscy współpracownicy w tym dokumencie
onOpen(e) działa w	AuthMode.NONE (chyba że włączono również AuthMode.LIMITED))	AuthMode.LIMITED

Tryby autoryzacji

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

W szczególności informacje o tym, w jakim trybie autoryzacji działa funkcja onOpen(e), określają stan instalacji i włączenia. 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 dodatek do edytora jest włączony w bieżącym dokumencie, onOpen(e) działa w AuthMode.LIMITED. Jeśli dodatek jest wyłączony i jest zainstalowany tylko w przeglądarce, onOpen(e) działa w AuthMode.NONE.

Tryby autoryzacji działają w przypadku wszystkich uruchomień Apps Script – np. uruchamiania z edytora skryptów, z poziomu menu lub wywołania google.script.run Apps Script. Właściwość e.authMode można sprawdzać tylko wtedy, gdy skrypt jest uruchamiany w wyniku reguły, takiej jak onOpen(e), onEdit(e) lub onInstall(e). Funkcje niestandardowe w Arkuszach Google korzystają z własnego trybu autoryzacji AuthMode.CUSTOM_FUNCTION, który jest podobny do funkcji LIMITED, ale ma nieco inne ograniczenia. Pozostałe godziny są uruchamiane w AuthMode.FULL, jak opisano w poniższej tabeli.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Występuje	onOpen(e) (jeśli użytkownik zainstalował dodatek, ale nie włączył go w dokumencie)	onOpen(e) (pozostałe przypadki) onEdit(e) (tylko w Arkuszach)	Funkcje niestandardowe	W pozostałych przypadkach, w tym: możliwością zainstalowania aplikacji 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 Properties	Nie	Tak	Tak	Tak
Dostęp do 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

Pełny cykl życia

Jeśli dodatek jest zainstalowany dla bieżącego użytkownika lub włączony w bieżącym dokumencie, jest on wczytywany w dokumencie, co pojawia się w menu Dodatki i zaczyna nasłuchiwać prostych reguł onInstall(e), onOpen(e) i onEdit(e). Jeśli użytkownik kliknie jeden z elementów menu dodatku, go uruchomi.

Instaluję

Gdy dodatek do edytora jest zainstalowany ze sklepu, jego funkcja onInstall(e) działa w AuthMode.FULL. Dzięki temu dodatek może przeprowadzać złożone procesy konfiguracji, ale ważne jest też, aby używać onInstall(e) do tworzenia pozycji menu, bo dokument jest już otwarty, przez co funkcja onOpen(e) nie została uruchomiona. Dla wygody wystarczy zadzwonić do onOpen(e) z onInstall(e), tak jak w tym przykładzie:

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

Otwieranie

Gdy dokument się otwiera, wczytuje wszystkie dodatki do edytora zainstalowane przez obecnego użytkownika lub włączonych w dokumencie i wywołuje każdą z funkcji 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, czytać zawartość bieżącego dokumentu lub wykonywać inne zaawansowane czynności, 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ł dodatek, a jeśli nie, robi to. Jeśli użytkownik autoryzował dodatek, skrypt uruchomi funkcję odpowiadającą pozycji menu w AuthMode.FULL. Dodatek stanie się też włączony w dokumencie, jeśli nie był włączony.