Zakresy

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 po raz pierwszy uruchomi dodatek, w interfejsie dodatku pojawi się prośba o rozpoczęcie procesu autoryzacji.

Podczas tego procesu użytkownik widzi pytanie o uprawnienia aplikacji. Na przykład dodatek może potrzebować uprawnień do odczytywania e-maili użytkownika lub tworzenia wydarzeń w kalendarzu. Projekt skryptu dodatku definiuje te indywidualne uprawnienia jako zakresy OAuth.

Zakresy zadeklarowane w pliku manifestu deklarujesz za pomocą ciągów URL. Podczas procesu autoryzacji Apps Script wyświetla użytkownikom czytelny dla użytkownika opis zakresu. Na przykład Twój dodatek do Google Workspace może korzystać z zakresu „Odczyt bieżącej wiadomości”, który jest zapisany w pliku manifestu jako https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Podczas procesu autoryzacji dodatek z tym zakresem prosi użytkownika o zezwolenie na wyświetlanie: Wyświetlanie e-maili, gdy dodatek jest uruchomiony.

Zakresy widoku

Aby wyświetlić zakresy wymagane przez projekt skryptu, wykonaj te czynności:

  1. Otwórz projekt skryptu.
  2. Po lewej stronie kliknij Przegląd .
  3. Wyświetl zakresy w sekcji „Projekty OAuth – zakresy”.

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 wyraźnych zakresów

Skrypt Apps Script automatycznie określa zakresy potrzebne skryptowi, skanując kod pod kątem wywołań funkcji, które tego wymagają. W przypadku większości skryptów jest to wystarczająca ilość i pozwala zaoszczędzić czas, ale w przypadku opublikowanych dodatków należy mieć większą kontrolę nad zakresami.

Na przykład Apps Script może domyślnie dodawać do projektu skryptu dodatkowego bardzo mało restrykcyjny zakres https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu z tym zakresem, projekt otrzyma pełny dostęp do konta Gmail użytkownika. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który zaspokaja potrzeby dodatków.

Zakresy możesz użyć w projekcie skryptu, edytując jego plik manifest. 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 Ustal, jakie zmiany należy wprowadzić, np. zawężając zakres.
  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 znaków. Aby ustawić zakresy używane przez projekt, zastąp zawartość tej tablicy zakresami, których chcesz używać. Na przykład w dodatku Google Workspace, który rozszerza Gmaila, możesz mieć:

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
    
  5. Zapisz zmiany w pliku manifestu.

Weryfikacja OAuth

Użycie niektórych wrażliwych zakresów OAuth może wymagać przejścia weryfikacji klienta OAuth przed jego opublikowaniem. 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 chcesz opublikować dodatek do Gmaila lub Edytora, który korzysta z co najmniej 1 zakresu z ograniczeniami, przed opublikowaniem dodatek musi być zgodny ze wszystkimi określonymi ograniczeniami.

Zanim spróbujesz opublikować zbiór treści, przejrzyj pełną listę zakresów z ograniczeniami. Jeśli Twój dodatek korzysta z któregoś z nich, przed jego opublikowaniem musisz spełnić Dodatkowe wymagania dla określonych zakresów interfejsu API.

Zakresy kalendarza

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają możliwości Kalendarza Google.

Zakres
Dostęp do metadanych zdarzenia https://www.googleapis.com/auth/calendar.addons.execute

Wymagany, jeśli dodatek ma dostęp do metadanych wydarzeń w Kalendarzu. Zezwala na dostęp do metadanych zdarzenia przez dodatek.

Odczytywanie danych zdarzeń wygenerowanych przez użytkowników https://www.googleapis.com/auth/calendar.addons.current.event.read

Wymagany, jeśli dodatek musi odczytywać dane zdarzeń użytkownika. Zezwala na dostęp dodatku do danych zdarzeń wygenerowanych przez użytkowników. Te dane są dostępne tylko wtedy, gdy pole pliku manifestu addOns.calendar.eventAccess ma wartość READ lub READ_WRITE.

Zapisywanie danych zdarzeń wygenerowanych przez użytkowników https://www.googleapis.com/auth/calendar.addons.current.event.write

Wymagany, jeśli dodatek ma zapisywać dane o zdarzeniach wygenerowane przez użytkownika. Pozwala na edytowanie danych zdarzeń generowanych przez użytkowników. Te dane są dostępne tylko wtedy, gdy pole pliku manifestu addOns.calendar.eventAccess ma wartość WRITE lub READ_WRITE.

Zakresy Dysku

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają możliwości Dysku Google.

Zakres
Odczyt metadanych wybranego elementu https://www.googleapis.com/auth/drive.addons.metadata.readonly

Wymagany, jeśli dodatek implementuje interfejs kontekstowy aktywowany, gdy użytkownik wybiera elementy na Dysku. Zezwala dodatku na odczytywanie ograniczonych metadanych elementów wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora, tytułu, typu MIME, adresu URL ikony i tego, czy dodatek ma uprawnienia dostępu do elementu.

Dostęp na poziomie pliku https://www.googleapis.com/auth/drive.file

Zalecany, jeśli dodatek ma dostęp do poszczególnych plików na Dysku. Przyznaje dostęp w trybie pliku do plików utworzonych lub otwartych przez aplikację przy użyciu zaawansowanej usługi Apps Script. Nie zezwala to jednak na użycie podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja plików jest przyznawana na poziomie pliku i jest unieważniana, gdy użytkownik autoryzuje aplikację.

Zobacz Przykład żądania dostępu do wybranych plików.

Zakresy dodatków do Gmaila

Istnieje kilka zakresów, które zostały utworzone specjalnie dla dodatków do Google Workspace, aby pomóc chronić dane użytkowników Gmaila. Musisz dodać te zakresy wprost do pliku manifestu dodatku wraz z innymi żądaniami wymaganymi w kodzie dodatku.

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają możliwości Gmaila. Te, które mają oznaczenie Required, trzeba dodać do pliku manifestu dodatku Google Workspace, jeśli dodatek rozszerza Gmaila.

Zastąp też bardzo szeroki zakres https://mail.google.com w dodatku węższym zakresem, który pozwala na interakcję.

Zakres
Tworzenie nowych wersji roboczych https://www.googleapis.com/auth/gmail.addons.current.action.compose

Wymagany, jeśli dodatek korzysta z aktywatorów tworzenia wiadomości. Pozwala dodatku na tymczasowe tworzenie nowych wersji roboczych wiadomości i odpowiedzi. Więcej informacji znajdziesz w sekcji Tworzenie wiadomości roboczych. Ten zakres jest też często używany przy tworzeniu działań. Wymaga tokena dostępu.

Odczytywanie otwartych metadanych wiadomości https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Przyznaje tymczasowy dostęp do metadanych otwartej wiadomości (na przykład tematu lub adresatów). Nie pozwala na czytanie treści wiadomości i wymaga tokena dostępu.

Wymagany, jeśli dodatek używa metadanych w aktywatorach tworzenia wiadomości. W przypadku działań tworzenia ten zakres jest wymagany, jeśli aktywator tworzenia wiadomości wymaga dostępu do metadanych. W tym zakresie utworzenie zakresu umożliwia utworzenie list odbiorców odbiorców (do:, DW: i UDW:) wersji roboczej e-maila z odpowiedzią.

Odczytywanie otwartej wiadomości https://www.googleapis.com/auth/gmail.addons.current.message.action

Przyznaje dostęp do zawartości otwartej wiadomości po interakcji użytkownika, np. w przypadku wybrania pozycji menu z dodatkami. Wymaga tokena dostępu.

Odczytywanie zawartości wątku https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Przyznaje tymczasowy dostęp do metadanych i zawartości otwartej wiadomości. Przyznaje też dostęp do treści innych wiadomości w otwartym wątku. Wymaga tokena dostępu.

odczytywanie treści wiadomości i metadanych, https://www.googleapis.com/auth/gmail.readonly

Odczytywanie wszystkich metadanych i treści e-maili, w tym otwartej wiadomości. Wymagane, jeśli chcesz odczytać informacje o innych wiadomościach, na przykład wykonać zapytanie lub cały wątek poczty.

Tokeny dostępu

Aby chronić dane użytkowników, zakresy Gmaila używane w dodatkach do Google Workspace zapewniają tylko tymczasowy dostęp do danych użytkowników. Aby włączyć dostęp tymczasowy, musisz wywołać funkcję GmailApp.setCurrentMessageAccessToken(accessToken) za pomocą tokena dostępu jako argumentu. Token dostępu musisz uzyskać z obiektu zdarzenia działania.

Poniżej znajdziesz przykład ustawienia tokena dostępu, który zezwala na dostęp do metadanych wiadomości. Jedynym zakresem wymaganym w tym przykładzie jest https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Zakresy edytora

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które zwiększają możliwości Dokumentów, Arkuszy i Prezentacji.

Zakres
Bieżący dostęp do plików Dokumentów https://www.googleapis.com/auth/documents.currentonly

Wymagany, jeśli dodatek ma dostęp do interfejsu Apps Script Docs API. Przyznaje tymczasowy dostęp do zawartości otwartego dokumentu.

Dostęp do bieżącego pliku Arkuszy https://www.googleapis.com/auth/spreadsheets.currentonly

Wymagany, jeśli dodatek ma dostęp do interfejsu Apps Script Sheets API. Przyznaje tymczasowy dostęp do zawartości otwartego arkusza kalkulacyjnego.

Dostęp do bieżącego pliku Prezentacji https://www.googleapis.com/auth/presentations.currentonly

Wymagany, jeśli dodatek ma dostęp do interfejsu Apps Script Slides API. Przyznaje tymczasowy dostęp do treści otwartej prezentacji.

Dostęp na poziomie pliku https://www.googleapis.com/auth/drive.file

Wymagany, aby dodatek mógł korzystać z onFileScopeGrantedTrigger oraz jeśli ma on dostęp do interfejsu API Dokumentów, Arkuszy, Prezentacji lub Dysku. Przyznaje dostęp w trybie pliku do plików utworzonych lub otwartych przez aplikację przy użyciu zaawansowanej usługi Apps Script. Nie zezwala to jednak na użycie podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja plików jest przyznawana dla poszczególnych plików i jest unieważniana, gdy użytkownik cofnie autoryzację aplikacji.

Inne zakresy

Twój dodatek może wymagać dodatkowych zakresów, jeśli korzysta z innych usług Apps Script. W większości przypadków możesz pozwolić, aby Apps Script wykrywał te zakresy i automatycznie aktualizował plik manifestu. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastąpisz je bardziej odpowiednią (np. węższą).

Oto lista zakresów Apps Script, które są często używane w połączeniu z dodatkami do Google Workspace:

Zakres
Odczytywanie adresu e-mail użytkownika https://www.googleapis.com/auth/userinfo.email

Zezwala projektowi na odczytywanie adresu e-mail bieżącego użytkownika.

Zezwalaj na połączenia z usługami zewnętrznymi https://www.googleapis.com/auth/script.external_request

Umożliwia projektowi wysyłanie żądań UrlFetch. Jest to też wymagane, gdy projekt korzysta z biblioteki OAuth2 for Apps Script.

Odczytywanie ustawień regionalnych i strefy czasowej użytkownika https://www.googleapis.com/auth/script.locale

Umożliwia projektowi poznanie ustawień regionalnych i strefy czasowej bieżącego użytkownika. Więcej informacji znajdziesz w sekcji Uzyskiwanie dostępu do ustawień regionalnych i strefy czasowej użytkownika.

Utworzenie reguł. https://www.googleapis.com/auth/script.scriptapp

Umożliwia projektowi tworzenie aktywatorów.

Podgląd linków zewnętrznych https://www.googleapis.com/auth/workspace.linkpreview

Wymagany, jeśli dodatek wyświetla podgląd linków z usługi innej firmy. Umożliwia projektowi wyświetlanie linku w aplikacji Google Workspace, gdy użytkownik wchodzi z nią w interakcję. Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linków z elementami inteligentnymi.