W większości przypadków musisz autoryzować dodatek, zanim będziesz mógł z niego korzystać. Autoryzacja wielu projektów Apps Script, takich jak aplikacje internetowe, jest prosta – projekt skryptu prosi o wszystkie brakujące uprawnienia, których chcesz użyć. Po autoryzacji możesz używać projektu skryptu bezpłatnie. Każdy użytkownik projektu skryptu autoryzuje go osobno.
Model autoryzacji dodatków do Edytora Google Ads jest bardziej złożony. Te dodatki działają na plikach pozostających na Dysku Google – czyli takich, które można udostępniać innym – dlatego musisz utworzyć dodatki do Edytora z uwzględnieniem różnych trybów autoryzacji. Edytory Dokumentów Google udostępniają w interfejsach użytkownika menu Dodatki, które jest uzupełniane przez zainstalowane dodatki, nawet jeśli nie zostały jeszcze autoryzowane. Zwiększa to 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 ze sklepu dodatek Edytor, zobaczysz go w menu dodatków dla każdego otwartego lub utworzonego przez Ciebie dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego. Współpracownicy nie zobaczą dodatku, z wyjątkiem dokumentów, formularzy, prezentacji lub arkuszy kalkulacyjnych, w których faktycznie go używasz.
- Gdy używasz dodatku Edytujący w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, Twoi współpracownicy zobaczą go również w menu dodatków, ale tylko w przypadku tego pliku (chyba że także zainstalowali ten dodatek).
Dla większości użytkowników ten model udostępniania jest naturalny. Dodatek do edycji automatycznie uruchamia w edytorze onOpen(e)
funkcję dodawania pozycji menu, gdy edytor Dokumentów Google otwiera się, dlatego ten proces dodatkowo zwiększa złożoność reguł autoryzacji Apps Script. W końcu użytkownicy nie czuliby się komfortowo, jeśli dostęp do danych osobowych otwiera dokument, formularz, prezentację lub arkusz kalkulacyjny. Z tego przewodnika dowiesz się, do czego i kiedy możesz wykorzystać kod.
Zainstalowane a włączone
Jeśli w menu widzisz dodatek Edytor, oznacza to, że został zainstalowany i włączony w 1 lub z 2 stanów. Dodatek do Edytora jest instalowany dla użytkownika po wybraniu tego dodatku w sklepie i upoważnieniu go do korzystania z danych Google. Dodatek jest natomiast włączony w danym dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, gdy ktoś go użyje. Jeśli 2 osoby współpracują, a jedna z nich korzysta z dodatku, jest on instalowany dla jednego użytkownika i włączony w pliku.
W tabeli poniżej podano oba te stany. Pamiętaj, że testując skrypt jako dodatek, możesz przeprowadzić test w jednym z tych stanów lub obu.
Zainstalowano | Włączono | |
---|---|---|
Dotyczy: | Użytkownik | Dokument, formularz, prezentacja lub arkusz kalkulacyjny |
Powód | Pobieranie dodatku ze sklepu | Pobieranie dodatku ze sklepu podczas używania danego dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego Używając wcześniej zainstalowanego dodatku w tym dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym |
Menu widoczne dla | Tylko ten użytkownik we wszystkich dokumentach, formularzach, prezentacjach i arkuszach kalkulacyjnych, które otwiera lub tworzy | Wszyscy współpracownicy nad tym dokumentem, formularzem, prezentacją lub arkuszem kalkulacyjnym |
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)
w celu dodawania pozycji menu po otwarciu dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego, ale w celu ochrony danych użytkowników usługa Apps Script ogranicza możliwości funkcji onOpen(e)
. Jeśli dodatek nie był używany w bieżącym dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, ograniczenia te będą poważne.
Konkretnie stany dostępności i zainstalowania określają, w którym trybie autoryzacji działa funkcja onOpen(e)
. Skrypt Apps Script przekazuje tryb autoryzacji jako właściwość authMode
parametru zdarzenia Apps Script e
, wartość e.authMode
odpowiada stałej wyliczeniu Apps Script ScriptApp.AuthMode
.
Jeśli dodatek do edytora jest włączony w bieżącym dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, onOpen(e)
działa w środowisku AuthMode.LIMITED
. Jeśli dodatek nie jest włączony i jest zainstalowany tylko, onOpen(e)
działa w przeglądarce AuthMode.NONE
.
Tryby autoryzacji mają zastosowanie do wszystkich wykonań Apps Script – np. uruchamiania z edytora skryptów, z menu lub wywołania App Script google.script.run
– chociaż właściwość e.authMode
można sprawdzić tylko wtedy, gdy skrypt jest uruchamiany w wyniku aktywacji takiej jak onOpen(e)
, onEdit(e)
lub onInstall(e)
. Funkcje niestandardowe w Arkuszach Google mają własny tryb autoryzacji, AuthMode.CUSTOM_FUNCTION
, który jest podobny do funkcji LIMITED
, ale ma nieco inne ograniczenia. Pozostała część skryptów jest uruchamiana w AuthMode.FULL
zgodnie z tabelą poniżej.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Występuje | onOpen(e) (jeśli użytkownik zainstalował dodatek, ale nie włączył go w dokumencie, formularzu, prezentacji ani arkuszu kalkulacyjnym) |
onOpen(e) (wszystkie inne godziny)onEdit(e) (tylko w Arkuszach) |
Funkcje niestandardowe | Wszystkie pozostałe okresy, w tym: instalacje możliwe do zainstalowania onInstall(e) google.script.run |
Dostęp do danych użytkowników | Tylko język | Tylko język | Tylko język | Tak |
Dostęp do dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego | Nie | Tak | Tak – tylko do odczytu | Tak |
Dostęp do interfejsu | Dodawanie elementów menu | Dodawanie elementów 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 |
Wszystkie usługi, które nie mają dostępu do danych użytkowników | Wszystkie usługi, które nie mają dostępu do danych użytkowników | Wszystkie usługi |
Pełny cykl życia
Jeśli dodatek jest zainstalowany dla bieżącego użytkownika lub włączony w bieżącym pliku, zostanie on wczytany do dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego, co spowoduje wyświetlenie go w menu dodatków i rozpoczęcie nasłuchiwania prostych aktywatorów onInstall(e)
, onOpen(e)
i onEdit(e)
. Jeśli użytkownik kliknie jedną z opcji menu dodatku, go uruchomi.
Instaluję
Gdy dodatek Edytor jest zainstalowany ze sklepu, jego funkcja onInstall(e)
działa w przeglądarce AuthMode.FULL
. Dzięki temu dodatek może przeprowadzać złożone procesy konfiguracji, ale ważne jest, aby używać onInstall(e)
do tworzenia pozycji menu, ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny są już otwarte i funkcja onOpen(e)
nie została uruchomiona. Dla wygody możesz zadzwonić do onOpen(e)
za pomocą onInstall(e)
, tak jak w tym przykładzie:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
Otwieranie
Gdy otwiera się dokument, formularz, prezentacja lub arkusz kalkulacyjny, wczytuje się każdy dodatek do Edytora zainstalowany przez obecnego użytkownika albo włączony w pliku przez dowolnego współpracownika 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 elementy menu na podstawie przechowywanych właściwości Apps Script, odczytywać zawartość bieżącego dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego albo wykonywać 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)
, która zmienia swoje 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();
}
Uruchomiono
Gdy ktoś kliknie jeden z elementów menu w dodatku, Apps Script najpierw sprawdza, czy użytkownik zainstalował ten dodatek, a jeśli nie. Jeśli użytkownik autoryzował dodatek, skrypt uruchamia funkcję odpowiadającą pozycji menu w pliku AuthMode.FULL
. Dodatek stanie się również włączony w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, jeśli jeszcze nie został włączony.