Autoryzacja dodatku do edytora

Autoryzacja wielu aplikacji opartych na Apps Script jest prosta, ponieważ projekt skryptu prosi o wszystkie brakujące uprawnienia, gdy ktoś próbuje go użyć.

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 onOpen()funkcje 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(). Ten przewodnik pomoże Ci zrozumieć, 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 na koncie konkretnego użytkownika, gdy 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 kilka osób współpracuje nad plikiem i jedna z nich używa dodatku, jest on instalowany dla tego użytkownika i włączany w pliku.

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

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 którym 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 i jest tylko zainstalowany, 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 używać wszystkich zakresów, na które użytkownik wyraził zgodę.

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

Tryby autoryzacji dotyczą wszystkich metod wykonywania skryptów Apps Script, w tym uruchamiania z edytora skryptów, z elementu 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 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 jest widoczny w menu Rozszerzenia i zaczyna nasłuchiwać proste wyzwalacze 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ż znaku onInstall() do tworzenia elementów menu, ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny są już otwarte, 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 nich. Tryb autoryzacji, w którym działa onOpen(), 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 przedstawia podstawową funkcję onOpen():

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

Aby dodać dynamiczne elementy 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();
}

Pamiętaj, że dodatki nie mogą otwierać pasków bocznych ani okien dialogowych podczas wykonywania 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ą elementowi 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