Zakresy autoryzacji 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, w interfejsie pojawi się prośba o autoryzację, aby rozpocząć proces autoryzacji.

Podczas tego procesu użytkownik dowiaduje się, jakie uprawnienia chce uzyskać aplikacja. Na przykład dodatek może chcieć uzyskać uprawnienia do odczytania wiadomości e-mail użytkownika lub tworzenia wydarzeń w jego kalendarzu. Projekt skryptu dodatku definiuje te indywidualne uprawnienia jako zakresy uprawnień OAuth.

Zakresy deklarujesz w manifest za pomocą ciągów znaków adresu URL. Podczas procesu autoryzacji Apps Script wyświetla użytkownikowi opis zakresu w formie zrozumiałej dla człowieka. Na przykład Twój dodatek może używać zakresu „Czytaj bieżący dokument”, który w pliku manifestu jest zapisany jako https://www.googleapis.com/auth/documents.currentonly. Podczas procesu autoryzacji dodatek o tym zakresie uprawnień prosi użytkownika o zezwolenie na: wyświetlanie dokumentów, w których zainstalowano tę aplikację, i zarządzanie nimi.

Wyświetlanie zakresów

Aby sprawdzić zakresy, których obecnie wymaga Twój projekt skryptu, wykonaj te czynności:

  1. Otwórz projekt skryptu.
  2. Po lewej stronie kliknij Przegląd.
  3. Sprawdź zakresy w sekcji „Zakresy protokołu OAuth projektu”.

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

Ustawianie zakresów jednoznacznych

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 oszczędza czas, ale w przypadku opublikowanych dodatków należy bardziej bezpośrednio kontrolować zakresy.

Na przykład Apps Script może domyślnie nadać projektowi skryptu dodatku bardzo liberalny zakres https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu z takim zakresem, projektowi przyznawany jest 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 potrzeby dodatków i nic więcej.

Możesz wyraźnie określić zakresy, których używa projekt skryptu, edytując jego plik manifest. Pole manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu, wykonaj te czynności:

  1. Wyświetl zakresy stosowane obecnie przez Twoje rozszerzenie Określ, jakie zmiany należy wprowadzić, np. zawężenie zakresu.
  2. Otwórz plik manifestu dodatku.
  3. Odszukaj pole najwyższego poziomu o nazwie oauthScopes. Jeśli go nie ma, możesz go dodać.

  4. Pole oauthScopes określa tablicę ciągów znaków. Aby ustawić zakresy, których ma używać projekt, zastąp zawartość tego tablic zakresami, których ma 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

Korzystanie z pewnych wrażliwych zakresów OAuth może wymagać weryfikacji klienta OAuth, zanim będzie można opublikować dodatek. Więcej informacji znajdziesz w tych przewodnikach:

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym zasadom, które pomagają chronić dane użytkowników. Jeśli chcesz opublikować dodatek do Gmaila lub Edytora, który korzysta z co najmniej jednego ograniczonego zakresu, musi on być zgodny ze wszystkimi określonymi ograniczeniami, zanim będzie można go opublikować.

Zanim spróbujesz opublikować aplikację, zapoznaj się z pełną listą zakresów z ograniczeniami. Jeśli Twój dodatek korzysta z jednego z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące określonych zakresów interfejsu API.

Zakresy działania dodatku 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 w przypadku dodatku do Arkuszy Google może być wymagany zakres https://www.googleapis.com/auth/spreadsheets.readonly, aby odczytać informacje z różnych Arkuszy Google.

Podczas dodawania kodu do projektu skryptu Apps Script automatycznie określa zakresy wymagane przez używane usługi. W przypadku dodatków do edytora możesz polegać na automatycznym zbieraniu zakresów zamiast określać je samodzielnie i ustawiać je wprost.

Jeśli nie ustawiasz zakresów w prosty sposób, a Twój dodatek do edytora tylko odczytuje lub zapisze 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 wartości currentonly. Jeśli na przykład dodasz ten komentarz do pliku projektu skryptu w dodatku do Arkuszy Google, określisz, że dodatek potrzebuje uprawnień tylko do obecnie otwartego Arkusza, a nie do innych Arkuszy, które użytkownik może mieć na Dysku Google. Z drugiej strony, nie używaj tego komentarza, jeśli dodatek do Arkuszy musi odczytywać lub zapisywać dane w arkuszu, którego użytkownik nie otworzył.