Autoryzacja dodatku do edytora

Autoryzacja wielu aplikacji Google Apps Script jest prosta. Gdy ktoś spróbuje użyć projektu skryptu, poprosi on o wszystkie brakujące uprawnienia.

Model autoryzacji w przypadku dodatków do edytora jest bardziej złożony 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ą w przypadku plików na Dysku Google, które można udostępniać współpracownikom. Współpracownicy, którzy nie mają zainstalowanego dodatku Edytor, widzą go w dokumentach, w których użył go twórca pliku.

• Dodatki do edytora automatycznie uruchamiają swoje funkcje onOpen po otwarciu dokumentu.

Aby chronić dane użytkowników, stosujemy tryby autoryzacji, które sprawiają, że niektóre usługi są niedostępne dla onOpen. Z tego przewodnika dowiesz się, co i kiedy może robić Twój kod.

Model autoryzacji

Tryb autoryzacji dodatku Edytora zależy od jego stanu, który z kolei zależy od tego, kto go używa: użytkownik, który zainstalował dodatek, czy współpracownik.

Stany dodatku do edytora

Dodatki do edytora w menu Rozszerzenia są zainstalowane, włączone lub jedno i drugie:

• Dodatek jest instalowany dla konkretnego użytkownika po tym, jak on lub jego administrator pobierze go z Google Workspace Marketplace i autoryzuje dostęp do danych Google.
• Dodatek jest włączony w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, gdy ktoś go tam używa.
• Gdy użytkownicy współpracują nad plikiem i jeden z nich używa dodatku, jest on instalowany dla tego użytkownika i włączany w przypadku pliku.

W tabeli poniżej znajdziesz podsumowanie różnic między stanami „zainstalowano” i „włączono”. Gdy testujesz skrypt jako dodatek, możesz uruchomić test w jednym lub obu stanach.

Tryby autoryzacji

Funkcja onOpen dodatku do edytora jest uruchamiana 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, w jakim trybie autoryzacji działa funkcja onOpen.

Jeśli dodatek Edytora jest włączony w pliku, formularzu, prezentacji lub arkuszu kalkulacyjnym, onOpen działa w AuthMode.LIMITED. Jeśli dodatek nie jest włączony, a jedynie zainstalowany, funkcja 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 go lub uruchamiając funkcje niestandardowe. Jeśli dodatek próbuje używać tych usług w zakresie onOpen, onInstall lub globalnym, uprawnienia nie działają, a inne wywołania, np. wypełnianie menu, są przerywane. Pomoc to jedyna obsługiwana opcja.

Aby wykonywać wywołania usług z ograniczeniami, musisz używać trybu autoryzacji AuthMode.FULL. Funkcje interakcji użytkownika, takie jak kliknięcie opcji menu, działają tylko w tym trybie. Po uruchomieniu kodu w trybie AuthMode.FULL dodatek może korzystać ze wszystkich autoryzowanych zakresów.

Tylko opublikowane dodatki do edytora mogą być w AuthMode.NONE.Nieopublikowane dodatki do edytora działają onOpen w AuthMode.LIMITED. jednak w obu trybach autoryzacji. Aby to zrobić, przetestuj dodatek do edytora.

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

Tryby autoryzacji dotyczą wszystkich metod wykonywania skryptów Apps Script, w tym uruchamiania z edytora skryptów, z pozycji menu lub z wywołania Apps Scriptgoogle.script.run. Właściwość e.authMode można jednak sprawdzić tylko wtedy, gdy skrypt jest uruchamiany w wyniku 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 trybu LIMITED, ale ma nieco inne ograniczenia. We wszystkich pozostałych przypadkach skrypty są uruchamiane w AuthMode.FULL, co opisano w tabeli poniżej.

Cykl życia autoryzacji dodatku do edytora

Gdy dodatek jest zainstalowany dla bieżącego użytkownika lub włączony w bieżącym pliku, jest on wczytywany w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym po otwarciu tego pliku. Dodatek pojawi się w menu Rozszerzenia i zacznie wyłapywać proste reguły:onInstall, onOpen i onEdit. Jeśli użytkownik kliknie element menu Rozszerzenia, zostanie on uruchomiony.

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. Używaj też onInstall do tworzenia elementów menu, ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny jest już otwarty, a funkcja onOpen nie została jeszcze uruchomiona. Poniższy przykład pokazuje, jak wywołać funkcję onOpen z funkcji onInstall:

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

Otworzy się dodatek do edytora.

Gdy otworzysz dokument, formularz, prezentację lub arkusz kalkulacyjny, wczytane zostaną wszystkie dodatki do edytora, które są zainstalowane przez bieżącego użytkownika lub które zostały włączone w pliku przez dowolnego współpracownika. Następnie wywoływane są funkcje onOpen każdego z tych dodatków. Tryb autoryzacji, w którym onOpendziała, zależy od tego, czy dodatek jest zainstalowany lub 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ć dynamiczne pozycje menu na podstawie zapisanych właściwości Apps Script, 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 przedstawia 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();
}

Gdy funkcja onOpen jest uruchamiana, cały skrypt jest wczytywany, a instrukcje globalne są wykonywane w tym samym trybie autoryzacji co onOpen. Jeśli tryb autoryzacji zabrania wykonywania instrukcji globalnych, zarówno instrukcje globalne, jak i onOpen nie zostaną uruchomione. Jeśli opublikowany dodatek nie doda elementów menu, sprawdź konsolę przeglądarki, aby zobaczyć, czy zwrócono błąd. Następnie sprawdź skrypt, aby zobaczyć, czy funkcja onOpen lub zmienne globalne wywołują usługi, które nie są dozwolone w AuthMode.NONE.

Dodatki nie mogą otwierać pasków bocznych ani okien dialogowych podczas wykonywania funkcji w AuthMode.LIMITED. Możesz używać elementów menu do otwierania pasków bocznych i okien, ponieważ działają one w AuthMode.FULL.

Użytkownik uruchamia dodatek do edytora

Gdy użytkownik kliknie element menu Rozszerzenia, Apps Script najpierw sprawdzi, czy użytkownik zainstalował dodatek, a jeśli nie, poprosi go o to. Jeśli użytkownik autoryzował dodatek, skrypt uruchamia funkcję odpowiadającą pozycji menu w AuthMode.FULL. Dodatek zostanie włączony w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym, jeśli nie był jeszcze włączony.

Rozwiązywanie problemów z niewyświetlaniem się menu dodatków

Menu dodatku może się nie wyświetlać, jeśli kod nie zarządza prawidłowo 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 wykonać wywołanie usługi, zanim użytkownik wejdzie z nim w interakcję.

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

1. Otwórz projekt Apps Script dla 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 czegoś innego niż tworzenie elementów interfejsu, usuń ją lub umieść w bloku komentarza. Pozostaw tylko te metody: .getUi, .createMenu, .addItem i .addToUi. Znajdź i usuń też wszystkie usługi, które nie są powiązane z funkcją.
4. Znajdź 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ług do funkcji, które ich potrzebują. Zmień układ lub przepisz kod, aby uwzględnić zmiany wprowadzone w poprzednich krokach.
5. Zapisz kod i utwórz testowe wdrożenie. Podczas tworzenia wdrożenia testowego upewnij się, że w polu Konfiguracja jest zaznaczona opcja Zainstalowano dla bieżącego użytkownika, a tekst pod polem Konfiguracja brzmi Testowanie w AuthMode.NONE.
6. Uruchom wdrożenie testowe i otwórz menu Rozszerzenia.
7. Jeśli wszystkie elementy menu są wyświetlane, problem został rozwiązany. Jeśli widzisz tylko menu Pomoc, wróć do kroku 1. Możesz mieć nieodebrane połączenie z serwisu.

Powiązane artykuły

• Aplikacje internetowe
• Typy dodatków
• Testowanie dodatku do edytora