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.