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, jego interfejs wyświetli prośbę o autoryzację rozpoczynającą proces autoryzacji.

W trakcie tego procesu wyświetlane są informacje o tym, jakie uprawnienia aplikacja chce wykonać. Dodatek może na przykład poprosić o uprawnienia do odczytywania e-maili użytkownika lub tworzenia wydarzeń w jego kalendarzu. Projekt skryptu dodatku określa te uprawnienia jako zakresy OAuth.

Zakresy zadeklarujesz w pliku manifestu za pomocą ciągów adresów URL. W trakcie procesu autoryzacji Apps Script wyświetla użytkownikowi opis zakresu w postaci zrozumiały dla człowieka. Na przykład dodatek może używać zakresu „Odczytaj bieżący dokument”, który jest zapisany w pliku manifestu jako https://www.googleapis.com/auth/documents.currentonly. Podczas procesu autoryzacji dodatek o tym zakresie prosi użytkownika o pozwolenie na: Wyświetlanie dokumentów, w których zainstalowano tę aplikację, i zarządzanie nimi.

Uwaga: zakresy używane przez Apps Script w różnych usługach 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, których wymagają poszczególne metody usługi Apps Script, znajdziesz w dokumentacji referencyjnej Apps Script.

Wyświetlane zakresy

Aby sprawdzić, jakie zakresy jest obecnie wymagane w projekcie skryptu, wykonaj te czynności:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd .
3. Wyświetl 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 ustawisz te zakresy wyraźnie.

Ustawianie zakresów jawnych

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ąca ilość czasu i oszczędza Ci czas, ale w przypadku opublikowanych dodatków zalecamy bardziej bezpośrednią kontrolę nad zakresami.

Na przykład Apps Script może domyślnie przyznać projektowi ze skryptem dodatku bardzo mało restrykcyjny zakres https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu o tym zakresie, otrzymuje pełny dostęp do konta Gmail użytkownika. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który będzie spełniał wymagania dodatków.

Ostrzeżenie: zawsze używaj zakresu o najniższym możliwym zakresie. Aby chronić dane użytkownika, dodatki i inne opublikowane aplikacje nigdy nie powinny prosić o uprawnienia o większym zakresie niż są absolutnie potrzebne. Zakresy, których wymaga Twój dodatek, są sprawdzane podczas sprawdzania dodatków. Jeśli dodatek używa zbyt szerokich zakresów, nie może przejść weryfikacji.

Zakresy, których używa projekt skryptu, możesz bezpośrednio ustawić, 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 dodatek. Określ, jakie zmiany należy wprowadzić, np. za pomocą węższego zakresu.
2. Otwórz plik manifestu dodatku.
3. Znajdź 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 tekstowych. Aby ustawić zakresy, których używa projekt, zastąp zawartość tej tablicy zakresami, których chcesz używać. Na przykład dodatek do Edytora, który rozszerza Arkusze, może zawierać:

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

5. Zapisz zmiany w pliku manifestu.

Weryfikacja OAuth

Korzystanie z niektórych poufnych zakresów OAuth może wymagać weryfikacji klienta OAuth przed opublikowaniem dodatku. Więcej informacji znajdziesz w tych przewodnikach:

• Weryfikacja klienta OAuth na potrzeby Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania na temat weryfikacji OAuth
• Usługa 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 chcesz opublikować dodatek do Gmaila lub edytora, który używa co najmniej jednego zakresu z ograniczeniami, przed opublikowaniem dodatek musi spełniać wszystkie określone ograniczenia.

Zanim przystąpisz do publikacji, przejrzyj 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 określonych zakresów interfejsów API.

Uwaga: w miarę możliwości nie używaj w dodatku zakresów z ograniczeniami – jeśli nie używasz tych zakresów, łatwiej jest przekazać je do weryfikacji publicznej. Z zakresów z ograniczeniami możesz korzystać bez ograniczeń w przypadku niepublicznych dodatków.

Zakresy dodatków do edytora

Gdy tworzysz dodatek 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 używane usługi podczas dodawania kodu do projektu skryptu. W przypadku dodatków do edytora często można polegać na automatycznym zbiorze zakresów, zamiast samodzielnie określać zakresy i ustawiać je bezpośrednio.

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

  /**
   * @OnlyCurrentDoc
   */

Ten komentarz informuje Apps Script, aby zawężać zakresy plików edytora do wartości currentonly. Jeśli na przykład dodasz ten komentarz do pliku projektu skryptu dodatku do Arkuszy Google, będzie to oznaczać, że dodatek potrzebuje uprawnień do działania tylko w aktualnie otwartym arkuszu, a nie na innych Arkuszach, które użytkownik ma na Dysku Google. I na odwrót: nie używaj tego komentarza, jeśli dodatek do Arkuszy musi odczytywać lub zapisywać dane w arkuszu, którego użytkownik aktualnie nie otworzył.