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, 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 w przypadku dodatku może to być uprawnienie 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, używając ciągów adresów 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.

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

Uwaga: zakresy stosowane przez Google Apps Script w różnych usługach pokrywają się z zakresami używanymi przez powiązane interfejsy API. Na przykład usługa Kalendarza w Google Apps Script korzysta z wielu tych samych zakresów co interfejs Calendar API. Zakresy wymagane przez poszczególne metody usługi Apps Script znajdziesz w dokumentacji referencyjnej Apps Script.

Wyświetlanie zakresów

Aby sprawdzić zakresy, których obecnie wymaga 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 dostępu 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.

Ostrzeżenie: zawsze używaj jak najmniejszego możliwego zakresu. Aby chronić informacje użytkowników, dodatki i inne opublikowane aplikacje nigdy nie powinny prosić o większe uprawnienia niż te, których absolutnie potrzebują. Zakresy wymagane przez Twoje dodatki są sprawdzane podczas procesu sprawdzania dodatków. Jeśli dodatek używa zakresów, które są zbyt szerokie, nie przejdzie weryfikacji.

Możesz wyraźnie określić zakresy używane przez 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, których obecnie używa 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 używa Twój projekt, zastąp zawartość tego tablic 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

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:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania dotyczące weryfikacji OAuth
• Zasady usług interfejsów API Google dotyczące danych użytkownika

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym zasadom, które pomagają chronić dane użytkownika. Jeśli chcesz opublikować dodatek do Gmaila lub Edytora, który korzysta z co najmniej jednego ograniczonego zakresu, musisz się upewnić, że dodatek jest zgodny ze wszystkimi określonymi ograniczeniami.

Zanim spróbujesz opublikować, 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 konkretnych zakresów interfejsu API.

Uwaga: jeśli to możliwe, unikaj używania ograniczonych zakresów w dodatku. Jeśli nie używasz takich zakresów, łatwiej jest przejść weryfikację dodatku w celu opublikowania go publicznie. W przypadku dodatków niepublicznych możesz swobodnie używać ograniczonych zakresów.

Zakresy 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 wtyczka do Arkuszy Google może potrzebować uprawnień 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 usługi, których używasz. W przypadku dodatków do Edytora możesz często polegać na tej automatycznej metodzie określania zakresu zamiast samodzielnego określania zakresów i ustawiania ich w wyraźny sposób.

Jeśli nie ustawiasz zakresów wprost, a Twój dodatek Editor tylko odczytuje lub zapisze plik otwartego 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. Nie używaj tego komentarza, jeśli dodatek do Arkuszy musi odczytywać lub zapisywać dane w arkuszu, którego użytkownik nie otworzył.

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