Zakresy

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 deklaruje się w pliku manifestu 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 dodatek do Google Workspace może używać zakresu „Odczytywanie bieżącej wiadomości”, który w pliku manifestu jest zapisany 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 e-maili, gdy dodatek jest uruchomiony.

Zakresy wyświetlania

Zakresy, których obecnie wymaga projekt skryptu, możesz sprawdzić, wykonując te czynności:

Otwórz projekt skryptu.
Po lewej stronie kliknij Przegląd .
Zakresy możesz wyświetlić w sekcji „Zakresy OAuth projektu”.

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

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ą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.

Zakresy używane przez projekt skryptu możesz ustawić, edytując jego plik manifestu. Pole manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu:

Wyświetl zakresy, których obecnie używa dodatek. Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
Otwórz plik manifestu dodatku.
Znajdź pole najwyższego poziomu o nazwie oauthScopes. Jeśli nie ma go na liście, możesz go dodać.
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 Google Workspace, który rozszerza Gmaila, możesz mieć te elementy:
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
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:

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.

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.

Wybieranie zakresów dla dodatków do Google Workspace

W sekcjach poniżej znajdziesz zakresy, które są często używane w dodatkach do Google Workspace.

Zakresy edytora

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają funkcje Dokumentów, Arkuszy i Prezentacji.

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.

Zakres
Dostęp do bieżącego pliku Dokumentów	`https://www.googleapis.com/auth/documents.currentonly` Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Docs API. Przyznaje tymczasowy dostęp do treści otwartego dokumentu.
Dostęp do bieżącego pliku Arkuszy	`https://www.googleapis.com/auth/spreadsheets.currentonly` Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Sheets API. Przyznaje tymczasowy dostęp do treści otwartego arkusza kalkulacyjnego.
Bieżący dostęp do pliku Prezentacji	`https://www.googleapis.com/auth/presentations.currentonly` Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Slides API. przyznaje tymczasowy dostęp do treści otwartej prezentacji;
Dostęp do poszczególnych plików	`https://www.googleapis.com/auth/drive.file` Wymagane, jeśli dodatek korzysta z `onFileScopeGrantedTrigger` i ma dostęp do interfejsu API Dokumentów, Arkuszy, Prezentacji lub Dysku. Umożliwia dostęp do plików utworzonych lub otwartych przez aplikację, korzystając z usługi zaawansowanej Dysku w Apps Scripcie. Nie umożliwia to jednak wykonywania podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja plików jest przyznawana dla każdego pliku z osobna i jest cofana, gdy użytkownik wycofa autoryzację aplikacji.

Gmail

Istnieje kilka zakresów, które zostały utworzone specjalnie z myślą o dodatkach do Google Workspace, aby chronić dane użytkowników Gmaila. Musisz wyraźnie dodać te zakresy do manifestu dodatku wraz z innymi zakresami, których wymaga kod dodatku.

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają Gmaila. Zakresy oznaczone jako Wymagane muszą zostać dodane do pliku manifestu dodatku do Google Workspace, jeśli rozszerza on Gmaila.

Pamiętaj też, aby zastąpić bardzo szeroki https://mail.google.com zakres w dodatku węższym zestawem zakresów, które umożliwiają interakcje potrzebne dodatkowi i nic więcej.

Zakres
Utwórz nowe wersje robocze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Wymagany, jeśli dodatek używa wyzwalaczy działania tworzenia. Umożliwia dodatkowi tymczasowe tworzenie nowych wersji roboczych wiadomości i odpowiedzi. Szczegółowe informacje znajdziesz w artykule Tworzenie wersji roboczych wiadomości . Ten zakres jest też często używany z działaniami związanymi z tworzeniem. Wymaga tokena dostępu.
Odczytywanie metadanych otwartej wiadomości	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Umożliwia tymczasowy dostęp do metadanych otwartej wiadomości (takich jak temat czy odbiorcy). Nie zezwala na odczytywanie treści wiadomości i wymaga tokena dostępu. Wymagane, jeśli dodatek używa metadanych w wyzwalaczach działania tworzenia. W przypadku działań tworzenia ten zakres jest wymagany, jeśli wyzwalacz tworzenia potrzebuje dostępu do metadanych. W praktyce ten zakres umożliwia wyzwalaczowi compose dostęp do list odbiorców (do:, dw: i udw:) roboczego e-maila z odpowiedzią.
Odczytywanie treści otwartej wiadomości	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Umożliwia dostęp do treści otwartej wiadomości po interakcji użytkownika, np. po wybraniu elementu menu dodatku. Wymaga tokena dostępu.
Odczytywanie treści otwartego wątku	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Udziela tymczasowego dostępu do metadanych i treści otwartej wiadomości. Umożliwia też dostęp do treści innych wiadomości w otwartym wątku. Wymaga tokena dostępu.
odczytywać treści i metadane dowolnej wiadomości;	`https://www.googleapis.com/auth/gmail.readonly` odczytywać metadane i treści e-maili, w tym otwartych wiadomości; Wymagane, jeśli chcesz odczytywać informacje o innych wiadomościach, np. podczas wyszukiwania lub czytania całego wątku. Ostrzeżenie: jest to bardzo szeroki zakres z ograniczeniami. Używaj go tylko wtedy, gdy jest to bezwzględnie konieczne.

Zakresy Kalendarza Google

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają Kalendarz Google.

Zakres
Dostęp do metadanych zdarzenia	`https://www.googleapis.com/auth/calendar.addons.execute` Wymagane, jeśli dodatek uzyskuje dostęp do metadanych wydarzeń w Kalendarzu. Umożliwia dodatkowi dostęp do metadanych wydarzenia.
Odczytywanie danych zdarzeń generowanych przez użytkowników	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Wymagane, jeśli dodatek musi odczytywać dane zdarzeń generowane przez użytkowników. Umożliwia dodatkowi dostęp do danych zdarzeń generowanych przez użytkowników. Te dane są dostępne tylko wtedy, gdy pole 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` Wymagane, jeśli dodatek musi zapisywać dane zdarzeń generowane przez użytkowników. Umożliwia dodatkowi edytowanie danych zdarzeń generowanych przez użytkowników. Te dane są dostępne tylko wtedy, gdy pole manifestu `addOns.calendar.eventAccess` ma wartość `WRITE` lub `READ_WRITE`.

Zakresy Google Chat

Aby wywołać interfejs Chat API, musisz uwierzytelnić się jako użytkownik Google Chat lub aplikacja do obsługi czatu. Każdy rodzaj uwierzytelniania wymaga innych zakresów, a nie wszystkie metody interfejsu Chat API obsługują uwierzytelnianie aplikacji.

Więcej informacji o zakresach i typach uwierzytelniania w Google Chat znajdziesz w omówieniu uwierzytelniania i autoryzacji w interfejsie Chat API.

Poniższa tabela zawiera najczęściej używane metody i zakresy interfejsu Chat API w zależności od obsługiwanych typów uwierzytelniania:

Metoda	Uwierzytelnianie aplikacji jest obsługiwane.	Obsługiwane zakresy autoryzacji
Wyślij wiadomość		W przypadku uwierzytelniania użytkownika: `chat.messages.create` `chat.messages` `chat.import` W przypadku uwierzytelniania aplikacji: `chat.bot`
Tworzenie pokoju		W przypadku uwierzytelniania użytkownika: `chat.spaces.create` `chat.spaces` `chat.import` Dzięki uwierzytelnianiu aplikacji i zatwierdzaniu przez administratora (dostępne w ramach wersji przedpremierowej dla deweloperów): `chat.app.spaces.create` `chat.app.spaces`
Tworzenie pokoju i dodawanie do niego użytkowników	–	W przypadku uwierzytelniania użytkownika: `chat.spaces.create` `chat.spaces`
Dodawanie użytkownika do pokoju		W przypadku uwierzytelniania użytkownika: `chat.memberships` `chat.memberships.app` `chat.import` Dzięki uwierzytelnianiu aplikacji i zatwierdzaniu przez administratora (dostępne w ramach wersji przedpremierowej dla deweloperów): `chat.app.memberships`
Wyświetlanie listy aktywności lub wydarzeń z pokoju czatu	–	W przypadku uwierzytelniania użytkownika musisz użyć zakresu dla każdego typu zdarzenia uwzględnionego w żądaniu: W przypadku zdarzeń dotyczących wiadomości: `chat.messages` `chat.messages.readonly` W przypadku zdarzeń dotyczących reakcji: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` W przypadku wydarzeń dotyczących wspierania: `chat.memberships` `chat.memberships.readonly` W przypadku wydarzeń dotyczących pokoju: `chat.spaces` `chat.spaces.readonly`

Zakresy Dysku Google

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

Zakres

Odczytywanie metadanych wybranego elementu

Zakres
Odczytywanie metadanych wybranego elementu	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Wymagane, jeśli dodatek implementuje interfejs kontekstowy wywoływany, gdy użytkownik wybiera elementy na Dysku. Umożliwia dodatkowi odczytywanie ograniczonych metadanych o elementach wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora elementu, tytułu, typu MIME, adresu URL ikony i informacji o tym, czy dodatek ma uprawnienia dostępu do elementu.
Dostęp do poszczególnych plików	`https://www.googleapis.com/auth/drive.file` Zalecane, jeśli dodatek musi mieć dostęp do poszczególnych plików na Dysku. Umożliwia dostęp do plików utworzonych lub otwartych przez aplikację, korzystając z usługi zaawansowanej Dysku w Apps Scripcie. Nie umożliwia to jednak wykonywania podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja plików jest przyznawana dla każdego pliku z osobna i jest cofana, gdy użytkownik wycofa autoryzację aplikacji. Zobacz przykład prośby o dostęp do wybranych plików.

https://www.googleapis.com/auth/drive.addons.metadata.readonly

Wymagane, jeśli dodatek implementuje interfejs kontekstowy wywoływany, gdy użytkownik wybiera elementy na Dysku. Umożliwia dodatkowi odczytywanie ograniczonych metadanych o elementach wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora elementu, tytułu, typu MIME, adresu URL ikony i informacji o tym, czy dodatek ma uprawnienia dostępu do elementu.

Dostęp do poszczególnych plików

https://www.googleapis.com/auth/drive.file

Zalecane, jeśli dodatek musi mieć dostęp do poszczególnych plików na Dysku. Umożliwia dostęp do plików utworzonych lub otwartych przez aplikację, korzystając z usługi zaawansowanej Dysku w Apps Scripcie. Nie umożliwia to jednak wykonywania podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja plików jest przyznawana dla każdego pliku z osobna i jest cofana, gdy użytkownik wycofa autoryzację aplikacji.

Zobacz przykład prośby o dostęp do wybranych plików.

Tokeny dostępu

Aby chronić dane użytkowników, zakresy Gmaila używane w dodatkach do Google Workspace przyznają tylko tymczasowy dostęp do danych użytkowników. Aby włączyć tymczasowy dostęp, musisz wywołać funkcję GmailApp.setCurrentMessageAccessToken(accessToken), podając token dostępu jako argument. Musisz uzyskać token dostępu z obiektu zdarzenia działania.

Poniżej znajdziesz przykład ustawiania tokena dostępu, który umożliwia dostęp do metadanych wiadomości. Jedyny zakres wymagany w tym przykładzie to 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();
}

Inne zakresy Google Workspace

Jeśli dodatek korzysta z innych usług Google Workspace lub Apps Script, może wymagać dodatkowych zakresów. W większości przypadków możesz zezwolić Apps Script na wykrywanie tych zakresów i automatyczne aktualizowanie pliku manifestu. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastępujesz je bardziej odpowiednią alternatywą, np. węższym zakresem.

W tabeli poniżej znajdziesz listę zakresów, których dodatki do Google Workspace często używają:

Zakres
Odczytywanie adresu e-mail użytkownika	`https://www.googleapis.com/auth/userinfo.email` Umożliwia projektowi odczytywanie adresu e-mail bieżącego użytkownika.
Zezwalanie 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 również wymagane, jeśli 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 bieżącego ustawienia regionalnego i strefy czasowej użytkownika. Więcej informacji znajdziesz w artykule 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` Wymagane, jeśli dodatek wyświetla podgląd linków z usługi innej firmy. Umożliwia projektowi wyświetlanie linku w aplikacji Google Workspace podczas interakcji użytkownika z tym linkiem. Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linków za pomocą elementów inteligentnych.
Tworzenie zasobów zewnętrznych	`https://www.googleapis.com/auth/workspace.linkcreate` Wymagane, jeśli dodatek tworzy zasoby w usłudze innej firmy. Umożliwia projektowi odczytywanie informacji przesyłanych przez użytkowników w formularzu tworzenia zasobów i wstawianie linku do zasobu w aplikacji Google Workspace. Więcej informacji znajdziesz w artykule Tworzenie zasobów innych firm za pomocą menu @.