Autoryzacja dodatku edytora

Autoryzacja wielu aplikacji opartych na Apps Script jest prosta, ponieważ projekt skryptu prosi o brakujące uprawnienia, gdy ktoś próbuje aby z niej korzystać.

Model autoryzacji dla platformy Dodatki do edytora to są bardziej złożone z kilku powodów:

• Gdy użytkownik utworzy plik, wszystkie zainstalowane przez niego dodatki będą widoczne w menu Rozszerzenia, nawet jeśli użytkownik nie autoryzował jeszcze tych dodatków.

• Te dodatki działają z plikami w Dysk Google, który można udostępniać współpracownikom. Współpracownicy, którzy nie mają zainstalowanego dodatku Editor, widzą go w dokumentach, w których użył go twórca pliku.

• Dodatki do edytora automatycznie wykonują funkcje onOpen() po otwarciu dokumentu.

Aby chronić dane użytkownika, stosowane są tryby autoryzacji, dzięki którym niektóre usługi niedostępne w usłudze onOpen(). Z tego przewodnika dowiesz się, co i kiedy może zrobić Twój kod.

Model autoryzacji

Tryb autoryzacji dodatku do edytora zależy od jego stanu, który z kolei zależy od tego, kto z niego korzysta: użytkownik, który zainstalował dodatek, czy współpracownik.

Stany dodatku do edytora

Dodatki do edytora w menu Rozszerzenia są zainstalowane, włączone lub mają włączone oba te ustawienia.

• Dodatek jest instalowany dla konkretnego użytkownika, gdy on sam lub jego administrator pobiera go z Google Workspace Marketplace i autoryzuje do dostępu do swoich danych Google.
• Dodatek jest włączony w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, gdy ktoś go używa.
• Gdy użytkownicy współpracują nad plikiem, a jeden z nich używa dodatku, jest on zainstalowany dla tego użytkownika i włączony dla pliku.

W tabeli poniżej zebraliśmy różnice między zainstalowanymi a włączonymi. Pamiętaj, że podczas testowania skryptu jako dodatku możesz przeprowadzić test w jednym lub obu tych stanach.

	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 ten dokument, formularz, prezentację lub arkusz kalkulacyjny korzystanie z wcześniej zainstalowanego dodatku, dokument, formularz, prezentacja lub arkusz kalkulacyjny
Menu widoczne dla	Tylko ten użytkownik we wszystkich dokumentach, formularzach, prezentacjach lub arkuszach kalkulacyjnych, które otwiera lub tworzy.	Wszyscy współpracownicy dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego.
Tryb autoryzacji instancji onOpen()	(AuthMode.NONE) (chyba że jest również włączona. W takim przypadku AuthMode.LIMITED)	AuthMode.LIMITED

Tryby autoryzacji

Uruchomienie funkcji onOpen() w dodatku do edytora automatycznie, gdy użytkownik otworzy dokument, formularz, prezentację lub arkusz kalkulacyjny. Aby chronić dane użytkowników, Apps Script ogranicza możliwości funkcji onOpen(). Stan dodatku do edytora określa tryb autoryzacji, w którym działa funkcja onOpen().

Jeśli dodatek do Edytora jest włączony w pliku, formularz, prezentacja lub arkusz kalkulacyjny, onOpen() działa w AuthMode.LIMITED Jeśli dodatek nie jest włączony i jest Tylko zainstalowane, onOpen() działa w AuthMode.NONE.

W AuthMode.NONE dodatek nie może uruchamiać niektórych usług, dopóki użytkownik nie wejdzie z nim w interakcję, klikając lub uruchamiając funkcje niestandardowe. Jeśli wtyczka próbuje korzystać z tych usług w zakresie onOpen(), onInstall() lub globalnym, uprawnienia nie działają, a inne wywołania, takie jak wypełnianie menu, przestają działać. Jedyną obsługiwaną opcją jest Pomoc.

Aby wykonywać połączenia z usługami płatnymi, musisz użyć trybu autoryzacji AuthMode.FULL. funkcje interakcji użytkownika, takie jak kliknięcie opcji menu, które działają tylko w tym trybie. Po uruchomieniu kodu w trybie AuthMode.FULL parametr dodatek może używać wszystkich zakresów autoryzowanych przez użytkownika.

Uwaga: tylko opublikowane dodatki do edytora mogą być AuthMode.NONE; nieopublikowane dodatki do edytora są uruchamiane onOpen() w AuthMode.LIMITED. Możesz jednak przetestować dodatek dla edytora, aby sprawdzić, czy dodatek w trakcie tworzenia działa zgodnie z oczekiwaniami w dowolnym trybie autoryzacji.

Apps Script przechodzi przez tryb autoryzacji jako właściwość authMode skryptu Apps Script, parametr zdarzenia, e; wartość e.authMode odpowiada stałej w Apps Script. Wyliczenie ScriptApp.AuthMode.

Tryby autoryzacji dotyczą wszystkich metod wykonywania Apps Script, Może to być na przykład uruchomienie w edytorze skryptów, z menu lub z Apps Script google.script.run. Właściwości e.authMode można jednak używać tylko wtedy, gdy skrypt jest uruchamiany w ramach wyzwalacza, takiego jak onOpen(), onEdit() lub onInstall(). Funkcje niestandardowe w Arkuszach Google korzystają z własnego trybu autoryzacji AuthMode.CUSTOM_FUNCTION, który jest podobny do LIMITED, ale ma nieco inne ograniczenia. W wszystkich pozostałych przypadkach skrypty są wykonywane w kontekście AuthMode.FULL, jak opisano w tabeli poniżej.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Występuje przez	onOpen() (jeśli użytkownik zainstalował dodatek, ale nie włączył go w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym)	onOpen() (we wszystkich innych godzinach) onEdit() (tylko w Arkuszach)	Funkcje niestandardowe	W wszystkich pozostałych przypadkach, w tym: instalowanych aktywatorów onInstall() google.script.run
Dostęp do danych użytkownika	Tylko język	Tylko język	Tylko lokalizacja	Tak
Dostęp do dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego	Nie	Tak	Tak, tylko do odczytu	Tak
Dostęp do interfejsu	Dodawanie pozycji menu	Dodawanie pozycji menu	Nie	Tak
Dostęp do usługi Properties	Nie	Tak	Tak	Tak
Dostęp do usług Jdbc, UrlFetch	Nie	Nie	Tak	Tak
Inne usługi	Logger Utilities	wszelkie usługi, które nie mają dostępu do danych użytkownika;	Usługi, które nie mają dostępu do danych użytkowników	Wszystkie usługi

Cykl autoryzacji dodatku do edytora

Gdy dodatek jest zainstalowany dla bieżącego użytkownika lub włączony w bieżącym pliku, ładuje się w przypadku dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego, gdy otworzysz ten plik. Dodatek to w menu Rozszerzenia i rozpoczyna nasłuchiwanie proste reguły onInstall(), onOpen() i onEdit(). Jeśli użytkownik kliknie element menu Rozszerzenia, go uruchomi.

Dodatek Edytor jest zainstalowany

Gdy dodatek do edytora zostanie zainstalowany ze sklepu, jego funkcja onInstall() będzie działać w AuthMode.FULL. W tym trybie autoryzacji dodatek może uruchomić skomplikowaną procedurę konfiguracji. Do tworzenia elementów menu powinieneś też używać funkcji onInstall(), ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny są już otwarte, a funkcja onOpen() nie została jeszcze wykonana. Ten przykładowy kod pokazuje, jak wywołać funkcję onOpen() z funkcji onInstall():

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

Otwiera się dodatek do edytora.

Gdy otwierasz dokument, formularz, prezentację lub arkusz kalkulacyjny, wczytuje się każdy dodatek do edytora zainstalowany przez bieżącego użytkownika lub włączony przez dowolnego współtwórcę w pliku, a następnie wywołuje wszystkie ich funkcje onOpen(). Tryb autoryzacji onOpen() jest uruchamiane w zależności od tego, czy dodatek jest zainstalowana lub włączona.

Jeśli dodatek utworzy tylko menu podstawowe, tryb bez znaczenia. Poniższy przykład przedstawia podstawową funkcję onOpen():

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

Aby dodać dynamiczne pozycje menu na podstawie zapisanych skryptów Apps Script właściwości, by odczytywać zawartość pakietów lub wykonać inne zaawansowane czynności, musi identyfikować tryb autoryzacji i właściwie go obsługiwać.

Ten przykład pokazuje zaawansowaną funkcję onOpen(), 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();
}

Ostrzeżenie: gdy funkcja onOpen() jest wykonywana, wczytuje się cały skrypt, a wszystkie instrukcje globalne są wykonywane w tym samym trybie autoryzacji co funkcja onOpen(). Jeśli tryb autoryzacji zabrania instrukcji globalnych, zarówno argument instrukcje globalne i onOpen() nie są uruchamiane. Jeśli wersja opublikowana dodatku nie dodaje swojego elementy menu, sprawdź w konsoli JavaScript przeglądarki, czy nie wystąpił błąd . Następnie sprawdź skrypt, aby zobaczyć, czy funkcja onOpen() lub zmienne globalne wywołują usługi niedozwolone w AuthMode.NONE.

Pamiętaj, że dodatki nie mogą otwierać pasków bocznych ani okien podczas uruchamiania w AuthMode.LIMITED Możesz użyć pozycji menu aby otwierać paski boczne i okna, ponieważ są one uruchamiane w aplikacji AuthMode.FULL.

Użytkownik uruchamia dodatek do edytora

Gdy użytkownik kliknie element menu Rozszerzenia, Apps Script najpierw sprawdza, czy użytkownik ma zainstalowany dodatek, a jeśli nie, prosi o jego zainstalowanie. Jeśli użytkownik autoryzował dodatek, skrypt uruchamia funkcję odpowiadającą pozycji menu w AuthMode.FULL. Wtyczka jest włączona w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, jeśli nie była wcześniej włączona.

Rozwiązywanie problemów z nierenderowaniem menu dodatków

Menu dodatku może się nie wyświetlać, jeśli kod nie obsługuje prawidłowo trybów autoryzacji. Na przykład:

• Dodatek próbuje uruchomić Apps Script usługa, która nie jest obsługiwana w bieżącym trybie autoryzacji.

• Dodatek próbuje wywołać usługę, zanim użytkownik z nią wejdzie w interakcję.

Aby usunąć lub zmienić kolejność wywołań usługi, które powodują błędy uprawnień w AuthMode.NONE, spróbuj wykonać te czynności:

1. Otwórz projekt Apps Script dla swojego dodatku i znajdź funkcję onOpen().
2. W funkcji onOpen() wyszukaj wzmianki o usługach Apps Script lub obiektach z nimi powiązanych, takich jak PropertiesService, SpreadsheetApp lub GmailApp.
3. Jeśli usługa jest używana do czegoś innego niż tworzenie elementów interfejsu, usuń ją lub owiń ją blokiem komentarza. Pozostaw tylko te metody: .getUi(), .createMenu(), .addItem() i .addToUi(). Znajdź i usuń wszelkie usługi, które są poza funkcją.
4. Zidentyfikuj funkcje, które mogą zawierać wiersze kodu skomentowane lub usunięte w poprzednim kroku, zwłaszcza te, które korzystają z wygenerowanych przez nie informacji. Następnie przenieś wywołania usług do funkcji, które ich potrzebują. Zmiana kolejności lub redagowania w bazie kodu, by uwzględnić zmiany wprowadzone w poprzednich krokach.

5. Zapisz kod i utwórz testowe wdrożenie.

   Podczas tworzenia testowego wdrożenia sprawdź, czy pole Konfiguracja ma wartość Zainstalowano dla bieżącego użytkownika, a tekst pod polem Konfiguracja to Testuj w AuthMode.None.

6. Uruchom testowe wdrożenie i otwórz menu Rozszerzenia.

7. Jeśli wyświetlają się wszystkie pozycje menu, problem został rozwiązany. Jeśli widzisz tylko menu Pomoc, wróć do kroku 1. Możesz nie odebrać połączenia z serwisu.

Powiązane artykuły

• Aplikacje internetowe
• Typy dodatków
• Testowanie dodatku do Edytora Google Ads