Autoryzacja dodatku do edytora

Autoryzacja w wielu aplikacjach Google Apps Script jest prosta. Gdy ktoś próbuje użyć skryptu, projekt skryptu prosi o brakujące uprawnienia.

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

• Gdy użytkownik utworzy plik, wszystkie zainstalowane przez niego dodatki są wymienione 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ępniać współpracownikom. Współpracownicy, którzy nie mają zainstalowanego dodatku do edytora, widzą go w dokumentach, w których używał go twórca pliku.

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

Aby chronić dane użytkowników, stosowane są tryby autoryzacji, które uniemożliwiają korzystanie z niektórych usług w funkcji onOpen. Z tego przewodnika dowiesz się, co i kiedy może robić Twój kod.

Model autoryzacji

Tryb autoryzacji dodatku do 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 oba te stany:

• Dodatek jest zainstalowany dla danego 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 użytkownicy współpracują nad plikiem i jeden z nich używa dodatku, jest on zainstalowany dla tego użytkownika i włączony w pliku.

W tabeli poniżej podsumowano różnice między stanami zainstalowany i włączony. Gdy testujesz skrypt jako dodatek, możesz uruchomić test w jednym lub obu tych 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 do edytora jest włączony w pliku, formularzu, prezentacji lub arkuszu kalkulacyjnym, funkcja onOpen działa w trybie AuthMode.LIMITED. Jeśli dodatek nie jest włączony, a jedynie zainstalowany, onOpen działa w trybie AuthMode.NONE.

W trybie AuthMode.NONE dodatek nie może korzystać z niektórych usług, dopóki użytkownik nie wejdzie z nim w interakcję, klikając lub uruchamiając funkcje niestandardowe. Jeśli dodatek spróbuje użyć tych usług w trybie onOpen, onInstall lub w zakresie globalnym, uprawnienia zostaną odrzucone, a inne wywołania, np. wypełnianie menu, zostaną zatrzymane. Jedyną obsługiwaną opcją jest Pomoc.

Aby uruchamiać wywołania usług z ograniczeniami, musisz używać trybu autoryzacji AuthMode.FULL. Funkcje interakcji z użytkownikiem, 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 autoryzowanych zakresów.

Tylko opublikowane dodatki do edytora mogą być w trybie AuthMode.NONE; nieopublikowane dodatki do edytora uruchamiają funkcję onOpen w trybie 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 Apps Script, w tym uruchamiania z edytora skryptów, z elementu menu lub z wywołania Apps Script google.script.run. Właściwość e.authMode można jednak sprawdzić tylko wtedy, gdy skrypt jest uruchamiany w wyniku aktywatora, takiego jak onOpen, onEdit lub onInstall. Funkcje niestandardowe w Arkuszach Google używają własnego trybu autoryzacji, AuthMode.CUSTOM_FUNCTION, który jest podobny do trybu LIMITED, ale ma nieco inne ograniczenia. We wszystkich innych przypadkach skrypty działają w trybie 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, jest on ładowany w dokumencie, formularzu, prezentacji lub arkuszu kalkulacyjnym po otwarciu tego pliku. Dodatek jest wymieniony w menu Rozszerzenia i zaczyna nasłuchiwać prostych aktywatorów onInstall, onOpen, i onEdit. Jeśli użytkownik kliknie element menu Rozszerzenia, zostanie on uruchomiony.

Dodatek do edytora jest zainstalowany

Gdy dodatek do edytora jest instalowany ze sklepu, jego funkcja onInstall działa w trybie AuthMode.FULL. W tym trybie autoryzacji dodatek może uruchamiać złożoną procedurę konfiguracji. Funkcji onInstall należy też używać do tworzenia elementów menu, ponieważ dokument, formularz, prezentacja lub arkusz kalkulacyjny jest już otwarty, a funkcja onOpen nie została jeszcze uruchomiona. W przykładzie poniżej pokazujemy, jak wywołać funkcję onOpen z funkcji onInstall:

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

Dodatek do edytora jest otwarty

Gdy otwierany jest dokument, formularz, prezentacja lub arkusz kalkulacyjny, wczytuje się każdy dodatek do edytora, który jest zainstalowany przez bieżącego użytkownika lub włączony w pliku przez dowolnego współpracownika, i wywołuje każdą z jego funkcji onOpen. Tryb autoryzacji, w którym działa funkcja onOpen, zależy od tego, czy dodatek jest zainstalowany czy włączony.

Jeśli dodatek tworzy tylko podstawowe menu, tryb nie ma znaczenia. W przykładzie poniżej pokazujemy podstawową funkcję onOpen:

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

Aby dodawać dynamiczne elementy menu na podstawie przechowywanych 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ć.

W przykładzie poniżej pokazujemy 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, wczytuje się cały skrypt, a instrukcje globalne są wykonywane w tym samym trybie autoryzacji co funkcja onOpen. Jeśli tryb autoryzacji zabrania wykonywania instrukcji globalnych, nie zostaną one uruchomione ani funkcja onOpen. Jeśli opublikowany dodatek nie może dodać swoich elementów menu, sprawdź konsolę przeglądarki, aby zobaczyć, czy nie zwrócono błędu. Następnie sprawdź skrypt, aby zobaczyć, czy funkcja onOpen lub zmienne globalne wywołują usługi, które nie są dozwolone w trybie AuthMode.NONE.

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

Użytkownik uruchamia dodatek do edytora

Gdy użytkownik kliknie element menu Rozszerzenia , Apps Script najpierw sprawdzi, czy użytkownik zainstalował dodatek, i poprosi go o to, jeśli nie. Jeśli użytkownik autoryzował dodatek, skrypt uruchomi funkcję odpowiadającą elementowi menu w trybie 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 renderowaniem menu dodatku

Menu dodatku może się nie renderować, 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 uruchomić 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 trybie 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. Zostaw tylko te metody: .getUi, .createMenu, .addItem i .addToUi. Znajdź i usuń też każdą usługę, która znajduje się poza funkcją.
4. Zidentyfikuj funkcje, które mogą zawierać wiersze kodu skomentowane lub usunięte w poprzednim kroku, zwłaszcza te, które używają informacji, które generują, i przenieś wywołania usług do funkcji, które ich potrzebują. Zmień kolejność lub przepisz kod, aby uwzględnić zmiany wprowadzone w poprzednich krokach.
5. Zapisz kod i utwórz wdrożenie testowe. Podczas tworzenia wdrożenia testowego upewnij się, że pole Konfiguracja ma wartość Zainstalowane dla bieżącego użytkownika , a tekst pod polem Konfiguracja brzmi Testuj w AuthMode.NONE.
6. Uruchom wdrożenie testowe i otwórz menu Rozszerzenia.
7. Jeśli wyświetlają się wszystkie elementy menu, problem został rozwiązany. Jeśli widzisz tylko menu Pomoc, wróć do kroku 1. Być może pominięto wywołanie usługi.

Powiązane artykuły

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