Zakresy uprawnień dla dodatków do edytora

Użytkownicy muszą autoryzować dodatki i inne aplikacje, które mają dostęp do ich danych lub działają w ich imieniu. Gdy użytkownik uruchomi dodatek po raz pierwszy, interfejs dodatku wyświetli prośbę o autoryzację, aby rozpocząć proces autoryzacji.

Podczas tego procesu wyświetla się prośba o przyznanie aplikacji uprawnień do wykonywania określonych działań. Na przykład dodatek może prosić o uprawnienia do odczytywania wiadomości e-mail użytkownika lub tworzenia wydarzeń w jego kalendarzu. Projekt skryptu dodatku definiuje te poszczególne uprawnienia jako zakresy OAuth.

Zakresy deklaruje się w manifeście za pomocą ciągów znaków URL. Podczas procesu autoryzacji Apps Script wyświetla użytkownikowi opis zakresu w formie czytelnej dla człowieka. Na przykład dodatek może używać zakresu „Odczytywanie bieżącego dokumentu”, który w pliku manifestu jest zapisany jako https://www.googleapis.com/auth/documents.currentonly. Podczas procesu autoryzacji dodatek z tym zakresem prosi użytkownika o zezwolenie na: wyświetlanie dokumentów, w których zainstalowano tę aplikację, i zarządzanie nimi.

Zakresy, których Apps Script używa w przypadku różnych usług, pokrywają się z zakresami używanymi przez powiązany interfejs API. Na przykład usługa Kalendarz w Apps Script używa wielu tych samych zakresów co interfejs Calendar API. Zakresy wymagane przez poszczególne metody usługi Apps Script możesz sprawdzić w dokumentacji referencyjnej Apps Script.

Zakresy umożliwiające wyświetlanie

Zakresy, których obecnie wymaga projekt skryptu, możesz sprawdzić, wykonując te czynności:

  1. Otwórz projekt skryptu.
  2. Po lewej stronie kliknij Przegląd .
  3. Zakresy możesz wyświetlić w sekcji „Zakresy OAuth projektu”.

Bieżące zakresy projektu skryptu możesz też wyświetlić w pliku manifestu projektu w polu oauthScopes, ale tylko wtedy, gdy zostały one wyraźnie ustawione.

Ustawianie jawnych zakresów

Apps Script automatycznie określa zakresy, których skrypt potrzebuje, skanując jego kod pod kątem wywołań funkcji, które ich wymagają. W przypadku większości skryptów jest to wystarczające i pozwala zaoszczędzić czas, ale w przypadku opublikowanych dodatków warto mieć większą kontrolę nad zakresami.

Na przykład Apps Script może domyślnie przyznać projektowi skryptu dodatku bardzo szeroki zakres https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu z tym zakresem, projekt uzyskuje pełny dostęp do konta Gmail użytkownika. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który obejmuje tylko potrzeby dodatku.

Zakresy używane przez projekt skryptu możesz ustawić, edytując jego plik manifestu. Pole pliku manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu:

  1. Wyświetl zakresy używane przez dodatek Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
  2. Otwórz plik manifestu dodatku.
  3. Znajdź pole najwyższego poziomu o nazwie oauthScopes. Jeśli nie ma go na liście, możesz go dodać.

  4. Pole oauthScopes określa tablicę ciągów znaków. Aby ustawić zakresy, których używa Twój projekt, zastąp zawartość tej tablicy zakresami, których chcesz używać. Na przykład w przypadku dodatku do Edytora, który rozszerza Arkusze, możesz mieć następujące elementy:

     {
   ...
   "oauthScopes": [
     "https://www.googleapis.com/auth/script.container.ui",
     "https://www.googleapis.com/auth/spreadsheets"
   ],
   ...
 }

  5. Zapisz zmiany w pliku manifestu.

Weryfikacja OAuth

Używanie niektórych wrażliwych zakresów OAuth może wymagać przejścia przez weryfikację klienta OAuth przed opublikowaniem dodatku. Więcej informacji znajdziesz w tych przewodnikach:

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym regułom, które pomagają chronić dane użytkowników. Jeśli zamierzasz opublikować dodatek do Gmaila lub Edytora, który korzysta z co najmniej jednego zakresu o ograniczonym dostępie, przed opublikowaniem musi on spełniać wszystkie określone ograniczenia.

Przed opublikowaniem zapoznaj się z pełną listą zakresów z ograniczeniami. Jeśli Twój dodatek używa któregokolwiek z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.

Rozszerzenie Narzędzia dla programistów Google Workspace do Visual Studio Code zawiera informacje diagnostyczne dotyczące wszystkich zakresów, w tym opis zakresu oraz informację, czy jest on wrażliwy lub ograniczony.

Zakresy dodatku do edytora

Podczas tworzenia dodatku do Edytora wymagane zakresy są określane przez usługę i metody Google Apps Script, których używa kod dodatku. Na przykład dodatek do Arkuszy Google może potrzebować zakresu https://www.googleapis.com/auth/spreadsheets.readonly, aby odczytywać informacje z różnych arkuszy.

Apps Script automatycznie określa zakresy wymagane przez usługi, których używasz, gdy dodajesz kod do projektu skryptu. W przypadku dodatków do edytora często możesz polegać na automatycznym zbieraniu zakresów, zamiast samodzielnie określać zakresy i ustawiać je jawnie.

Jeśli nie ustawiasz zakresów w sposób jawny, a dodatek do edytora tylko odczytuje lub zapisuje otwarty plik edytora, dodaj do jednego z plików projektu skryptu ten komentarz:

/**
 * @OnlyCurrentDoc
 */

Ten komentarz informuje Apps Script, aby zawęzić zakresy plików edytora, które ustawia na currentonly. Jeśli na przykład dodasz ten komentarz do pliku projektu skryptu dodatku do Arkuszy, określisz, że dodatek potrzebuje uprawnień tylko do działania w otwartym arkuszu, a nie w żadnych innych arkuszach, które użytkownik może mieć na Dysku Google. Z kolei nie należy używać tego komentarza, jeśli dodatek do Arkuszy musi odczytywać lub zapisywać dane w arkuszu, który nie jest otwarty przez użytkownika.