Autoryzacja dodatków do Edytora

Autoryzacja wielu aplikacji opartych na Apps Script jest prosta, ponieważ projekt skryptu prosi o wszelkie uprawnienia potrzebne, gdy ktoś spróbuje z niego skorzystać.

Model autoryzacji dodatków do edytora jest bardziej złożony z kilku powodów:

  • Gdy użytkownik utworzy plik, wszystkie dodatki zainstalowane przez użytkownika będą wymienione w menu Rozszerzenia, nawet jeśli użytkownik ich jeszcze ich nie autoryzował.

  • Działają one na plikach na Dysku Google, które możesz udostępniać współpracownikom. Współpracownicy, którzy nie mają zainstalowanego dodatku Edytor, widzą go w dokumentach, w których go użył twórca.

  • Dodatki do Edytora automatycznie uruchamiają swoje funkcje onOpen() po otwarciu dokumentu.

Aby chronić dane użytkownika, stosujemy tryby autoryzacji, które sprawiają, że onOpen() nie ma dostępu do niektórych usług. Ten przewodnik pomoże Ci zrozumieć, do czego może służyć Twój kod i kiedy.

Model autoryzacji

Tryb autoryzacji dodatku Edytor zależy od jego stanu, który zależy od tego, kto go używa: od użytkownika, który go zainstalował, czy od współpracownika.

Stany dodatku Edytor

Dodatki do Edytora w menu Rozszerzenia są zainstalowane, włączone lub zainstalowane.

  • Dodatek jest zainstalowany dla określonego użytkownika po tym, jak dany użytkownik lub jego administrator pobierze go z Google Workspace Marketplace i autoryzuje mu dostęp do jego danych Google.
  • Dodatek jest włączany w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, gdy ktoś z niego korzysta.
  • Gdy ktoś wspólnie pracuje nad plikiem, a jedna z nich korzysta z dodatku, jest on zainstalowany u jednego użytkownika i włączony dla pliku.

Tabela poniżej zawiera podsumowanie różnic między zainstalowanym a włączonym kontem. Pamiętaj, że jeśli testujesz skrypt jako dodatek, możesz przeprowadzić test w jednym z tych stanów lub w obu.

Zainstalowano Włączono
Dotyczy: Użytkownik Dokument, formularz, prezentacja lub arkusz kalkulacyjny
Powód Pobieranie dodatku ze sklepu pobranie dodatku ze sklepu podczas korzystania z dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego lub
korzystanie z wcześniej zainstalowanego dodatku w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym;
Menu widoczne dla Tylko ten użytkownik we wszystkich dokumentach, formularzach, prezentacjach lub arkuszach kalkulacyjnych, które otwiera lub tworzy Wszyscy współpracownicy korzystający z dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego
Tryb autoryzacji domeny onOpen() AuthMode.NONE
(chyba że jest też włączona – w takim przypadku AuthMode.LIMITED)
AuthMode.LIMITED

Tryby autoryzacji

Funkcja onOpen() dodatku Edytor uruchamia się 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 Edytor określa tryb autoryzacji, w którym działa funkcja onOpen().

Jeśli dodatek do Edytora jest włączony w pliku, formularzu, prezentacji lub arkuszu kalkulacyjnym, onOpen() zostanie uruchomiony w AuthMode.LIMITED. Jeśli dodatek nie jest włączony i jest tylko zainstalowany, onOpen() działa w AuthMode.NONE.

W AuthMode.NONE dodatek nie może uruchamiać określonych usług, dopóki użytkownik nie wejdzie z nim w interakcję przez kliknięcie lub uruchomienie funkcji niestandardowych. Jeśli dodatek próbuje użyć tych usług w zakresie onOpen(), onInstall() lub globalnym, brakuje uprawnień, a inne wywołania, takie jak wypełnianie menu, zatrzymaj. Jedyną obsługiwaną opcją jest pomoc.

Aby uruchamiać ograniczone wywołania usługi, musisz użyć trybu autoryzacji AuthMode.FULL. Funkcje interakcji z użytkownikiem, takie jak klikanie opcji menu, działają tylko w tym trybie. Po uruchomieniu kodu w trybie AuthMode.FULL dodatek może korzystać ze wszystkich zakresów autoryzowanych przez użytkownika.

Apps Script przekazuje tryb autoryzacji jako właściwość authMode parametru zdarzenia Apps Script e. Wartość e.authMode odpowiada stałej wartości w wyliczeniu ScriptApp.AuthMode.

Tryby autoryzacji mają zastosowanie do wszystkich metod wykonywania Apps Script, w tym do uruchamiania z poziomu edytora skryptów, z poziomu menu lub wywołania Apps Script google.script.run. Właściwość e.authMode można jednak sprawdzić tylko wtedy, gdy skrypt jest uruchomiony w wyniku działania reguły, np. onOpen(), onEdit() lub onInstall(). Funkcje niestandardowe w Arkuszach Google używają własnego trybu autoryzacji AuthMode.CUSTOM_FUNCTION. Jest on podobny do trybu autoryzacji LIMITED, ale ma nieco inne ograniczenia. W pozostałych przypadkach skrypty są uruchamiane w komponencie AuthMode.FULL zgodnie z opisem w tej tabeli.

NONE LIMITED CUSTOM_FUNCTION FULL
Występuje dla onOpen() (jeśli użytkownik zainstalował dodatek, ale nie włączył go w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym) onOpen() (wszystkie inne godziny)
onEdit() (tylko w Arkuszach)
Funkcje niestandardowe Wszystkie inne okresy, w tym:
aktywatory do zainstalowania
onInstall()
google.script.run
Dostęp do danych użytkownika 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 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
Wszystkie usługi, które nie mają dostępu do danych użytkownika Wszystkie usługi, które nie mają dostępu do danych użytkownika Wszystkie usługi

Cykl życia autoryzacji dodatku do edytora

Jeśli dodatek zostanie zainstalowany dla bieżącego użytkownika lub włączony w bieżącym pliku, zostanie on wczytywany dla dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego w momencie otwarcia tego pliku. Dodatek pojawi się w menu Rozszerzenia i zacznie nasłuchiwać prostych reguł onInstall(), onOpen() i onEdit(). Jeśli użytkownik kliknie pozycję menu Rozszerzenia, zostanie ona uruchomiona.

Dodatek do edytora 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 uruchamiać złożoną procedurę konfiguracji. Do tworzenia elementów menu używaj też metody onInstall(), ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny są już otwarte, a funkcja onOpen() nie została uruchomiona. Z przykładu poniżej dowiesz się, jak wywołać funkcję onOpen() z poziomu funkcji onInstall():

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

Dodatek do edytora jest otwarty.

Po otwarciu dokumentu, formularza, prezentacji lub arkusza kalkulacyjnego wczytuje się każdy dodatek do edytora zainstalowany przez bieżącego użytkownika lub włączony przez dowolnego współpracownika w pliku oraz wywołuje wszystkie funkcje onOpen(). Tryb autoryzacji, w którym działa onOpen(), zależy od tego, czy dodatek jest zainstalowany czy włączony.

Jeśli dodatek tworzy tylko podstawowe menu, tryb nie ma znaczenia. Poniższy przykład pokazuje podstawową funkcję onOpen():

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

Aby dodać pozycje menu dynamicznego oparte na właściwościach zapisanego pliku Apps Script, aby odczytać zawartość bieżącego pliku lub wykonać inne zaawansowane zadania, musisz określić tryb autoryzacji i odpowiednio go obsłużyć.

Poniższy 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();
}

Pamiętaj, że podczas działania w AuthMode.LIMITED dodatki nie mogą otwierać pasków bocznych ani okien. Do otwierania pasków bocznych i okien możesz używać pozycji menu, ponieważ te działają w AuthMode.FULL.

Użytkownik uruchamia dodatek do edytora.

Gdy użytkownik kliknie pozycję menu Rozszerzenia, Apps Script najpierw sprawdza, czy użytkownik zainstalował dany dodatek, a w razie potrzeby informuje o tym. Jeśli użytkownik autoryzował dodatek, skrypt uruchamia funkcję odpowiadającą pozycji menu w AuthMode.FULL. Dodatek jest włączony w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, jeśli jeszcze nie był włączony.

Rozwiązywanie problemów z wyświetlaniem menu dodatków

Menu dodatków może się nie wyświetlić, jeśli Twój kod nie będzie poprawnie zarządzać trybami autoryzacji. Na przykład:

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

  • Dodatek próbuje uruchomić wywołanie usługi, zanim użytkownik wejdzie z nim w interakcję.

Aby usunąć wywołanie usługi, które powoduje błędy uprawnień w AuthMode.NONE, lub zmienić ich kolejność, wykonaj te czynności:

  1. Otwórz projekt Apps Script dotyczący dodatku i znajdź funkcję onOpen().
  2. Wyszukaj w funkcji onOpen() wzmianki o usługach Apps Script lub powiązanych z nimi obiektach, takich jak PropertiesService, SpreadsheetApp lub GmailApp.
  3. Jeśli usługa jest używana do innych celów niż tworzenie elementów interfejsu, usuń ją lub umieść w bloku komentarzy. Pozostaw tylko te metody: .getUi(), .createMenu(), .addItem() i .addToUi(). Znajdź i usuń wszystkie usługi, które są poza funkcją.
  4. Określ funkcje, które mogą zawierać wiersze kodu skomentowane lub usunięte w poprzednim kroku, zwłaszcza te, które korzystają z generowanych przez nie informacji, i przenieś wywołania usługi do funkcji, które ich potrzebują. Zmień kolejność lub bazę kodu tak, aby dostosować ją do zmian wprowadzonych w poprzednich krokach.
  5. Zapisz kod i utwórz wdrożenie testowe.

    Podczas tworzenia wdrożenia testowego sprawdź, czy w polu Konfiguracja jest wybrane ustawienie Zainstalowane dla bieżącego użytkownika, a tekst pod polem konfiguracji brzmi Przetestuj w: AuthMode.None.

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

  7. Jeśli wyświetlają się wszystkie pozycje menu, problem jest rozwiązany. Jeśli widzisz tylko menu Pomoc, wróć do kroku 1. Możliwe, że nie odebrano połączenia z usługą.