Zakresy uprawnień dla dodatków do edytora

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

Podczas tego procesu wyświetla się prośba o udzielenie aplikacji uprawnień do 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 deklarujesz 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 Twój dodatek może używać zakresu „Odczytaj bieżący dokument”, który jest zapisany w manifeście jako https://www.googleapis.com/auth/documents.currentonly. Podczas procesu autoryzacji dodatek z tym zakresem uprawnień prosi użytkownika o zezwolenie na: wyświetlanie dokumentów, w których zainstalowano tę aplikację, i zarządzanie nimi.

Uwaga: zakres currentonly jest dostępny tylko w usługach Apps Script. Nie obejmuje to usług zaawansowanych Apps Script ani bezpośrednich wywołań interfejsów API Google Workspace.

Uwaga: 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 zakresów takich samych jak interfejs Calendar API. Zakresy wymagane przez poszczególne metody usługi Apps Script możesz sprawdzić w dokumentacji referencyjnej Apps Script.

Wyświetlanie zakresów

Zakresy, których obecnie wymaga Twój 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 manifeście projektu w polu oauthScopes, ale tylko wtedy, gdy zostały one wyraźnie ustawione.

Ustawianie jednoznacznych zakresów

Apps Script automatycznie określa, jakich zakresów potrzebuje skrypt, 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.

Ostrzeżenie: zawsze używaj najmniej restrykcyjnego możliwego zakresu. Aby chronić informacje o użytkownikach, dodatki i inne opublikowane aplikacje nigdy nie powinny prosić o więcej uprawnień zakresu, niż jest to absolutnie konieczne. Zakresy wymagane przez dodatek są sprawdzane podczas procesu publikacji weryfikacji dodatku. Jeśli dodatek używa zbyt szerokich zakresów, nie może przejść weryfikacji.

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, wykonaj te czynności:

1. Wyświetl zakresy, których obecnie używa dodatek. Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
2. Otwórz plik manifestu dodatku.
3. Znajdź pole najwyższego poziomu oznaczone etykietą 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ć:

   {
     ...
     "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:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania o weryfikację OAuth
• Usługi interfejsów API Google: zasady dotyczące danych użytkownika

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 dodatek korzysta z któregoś z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.

Uwaga: jeśli to możliwe, unikaj używania w dodatku zakresów o ograniczonym dostępie. Jeśli ich nie używasz, łatwiej przejdziesz weryfikację dodatku przed jego publicznym opublikowaniem. W przypadku dodatków niepublicznych możesz swobodnie korzystać z zakresów objętych ograniczeniami.

Rozszerzenie Google Workspace Developer Tools 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 dodatków do edytora

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

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 możesz często polegać na automatycznym zbieraniu zakresów zamiast samodzielnie określać zakresy i ustawiać je w sposób jawny.

Jeśli nie ustawiasz zakresów w sposób jawny, a dodatek 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 do currentonly. Jeśli na przykład dodasz ten komentarz do pliku projektu skryptu dodatku do Arkuszy Google, określisz, że dodatek potrzebuje uprawnień tylko do działania w obecnie otwartym arkuszu, a nie w 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 obecnie otwarty przez użytkownika.

Uwaga: zakres currentonly jest dostępny tylko w usługach Apps Script. Nie obejmuje to usług zaawansowanych Apps Script ani bezpośrednich wywołań interfejsów API Google Workspace.