Autoryzacja dodatku do edytora

Autoryzacja wielu aplikacji opartych na Apps Script jest prosta, ponieważ projekt skryptu prosi o 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ą na plikach na Dysku Google, które można udostępnić 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żytkowników, stosujemy tryby autoryzacji, które uniemożliwiają onOpen() dostęp do niektórych usług. 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 edytora w menu Rozszerzenia są zainstalowane, włączone lub jedno i drugie.

• 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 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 znajdziesz podsumowanie różnic między instalacją a włączeniem. Pamiętaj, że podczas testowania skryptu jako dodatku możesz przeprowadzić test w jednym lub obu tych stanach.

Tryby autoryzacji

Funkcja onOpen() wtyczki Editor 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 tryb autoryzacji, w którym działa funkcja onOpen().

Jeśli w pliku, formularzu, prezentacji lub arkuszu kalkulacyjnym włączone jest dodatki Editor, onOpen() działa w AuthMode.LIMITED. Jeśli dodatek nie jest włączony, a tylko zainstalowany, onOpen() działa w trybie 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ą i inne wywołania, takie jak wypełnianie menu, są blokowane. Pomoc to jedyna obsługiwana opcja.

Aby wykonywać połączenia z usługami płatnymi, musisz użyć trybu autoryzacji AuthMode.FULL. Funkcje interakcji z użytkownikiem, takie jak kliknięcie opcji menu, działają tylko w tym trybie. Gdy kod zostanie uruchomiony w trybie AuthMode.FULL, wtyczka może używać wszystkich zakresów autoryzowanych przez użytkownika.

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

Tryby autoryzacji mają zastosowanie do wszystkich metod wykonywania skryptów Apps Script, w tym do uruchamiania skryptu z edytora skryptu, z elementu menu lub z wywołania skryptu 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.

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 jest widoczny w menu Rozszerzenia i zaczyna reagować na proste reguły onInstall(), onOpen() i onEdit(). Jeśli użytkownik kliknie element menu Rozszerzenia, go uruchomi.

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 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, wczytywane są wszystkie dodatki do edytora zainstalowane przez bieżącego użytkownika lub włączone przez dowolnego współpracownika w pliku, a następnie wywoływane są wszystkie ich funkcje onOpen(). Tryb autoryzacji, w jakim 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. Ten przykład pokazuje podstawową funkcję onOpen():

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

Aby dodawać dynamiczne pozycje menu na podstawie zapisanych właściwości Apps Script, odczytywać zawartość bieżącego pliku lub wykonywać inne zaawansowane zadania, musisz określić tryb autoryzacji i odpowiednio go obsłużyć.

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

Pamiętaj, że w trakcie wykonywania w poziomie AuthMode.LIMITED dodatki nie mogą otwierać pasków bocznych ani okien dialogowych. Możesz używać elementów menu do otwierania pasków bocznych i dialogów, ponieważ te działają w ramach 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 wcześniej nie była włączona.

Rozwiązywanie problemów z wyświetlaniem 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ć usługę Apps Script, która nie jest obsługiwana przez bieżący tryb autoryzacji.

• Dodatek próbuje wywołać usługę, zanim użytkownik z nią wejdzie 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 swojego dodatku i znajdź funkcję onOpen().
2. W funkcji onOpen() wyszukaj 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 owiń ją blokiem komentarza. Pozostaw tylko te metody: .getUi(), .createMenu(), .addItem() i .addToUi(). Możesz też znaleźć i usunąć usługi, które nie są powiązane z żadną 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ą. Zmień kolejność lub przepisz kod źródłowy, aby 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 wszystkie elementy menu są widoczne, 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