Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

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 uruchomi dodatek po raz pierwszy, interfejs dodatku wyświetli prośbę o autoryzację, aby rozpocząć proces autoryzacji.

Podczas tego procesu wyświetla się prośba o przyznanie 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 manifeście 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 jest zapisany w pliku manifestu jakohttps://www.googleapis.com/auth/gmail.addons.current.message.readonly. Podczas procesu autoryzacji dodatek z tym zakresem uprawnień prosi użytkownika o zezwolenie na wyświetlanie e-maili, gdy dodatek jest uruchomiony.

Zakresy używane przez Apps Script w przypadku różnych usług pokrywają się z zakresami używanymi przez powiązany interfejs API. Na przykład usługa Kalendarz w Apps Script używa wielu zakresów takich samych jak interfejs Calendar API. Zakresy wymagane przez poszczególne metody usługi Apps Script możesz sprawdzić w dokumentacji referencyjnej Apps Script.

Zakresy umożliwiające wyświetlanie

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 jawnych zakresów

Apps Script automatycznie określa zakresy, których skrypt potrzebuje, 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 używane przez dodatek Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
Otwórz plik manifestu dodatku.
Znajdź pole najwyższego poziomu oznaczone 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ć następujące 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, 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 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 sprawdź pełną listę zakresów z ograniczeniami. Jeśli dodatek używa któregokolwiek z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.

Rozszerzenie Narzędzia deweloperskie Google Workspace do Visual Studio Code zawiera informacje diagnostyczne dotyczące wszystkich zakresów, w tym opis zakresu oraz informację o tym, czy jest on poufny 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 przypadku dodatków do Google Workspace.

Zakresy edytora

Te często używane zakresy dodatków do Google Workspace rozszerzają funkcje Dokumentów, Arkuszy i Prezentacji Google.

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
Obecny dostęp do plików Dokumentów	`https://www.googleapis.com/auth/documents.currentonly` Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Google 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 ma 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` Wymagany, jeśli dodatek ma 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 poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą zaawansowanej usługi Dysku Google w Apps Script. Nie umożliwia to podobnych działań przy użyciu podstawowej usługi Drive. Autoryzacja plików jest przyznawana dla każdego pliku z osobna i jest cofana, gdy użytkownik wycofa autoryzację aplikacji.

Gmail

Istnieją zakresy utworzone specjalnie dla dodatków do Google Workspace, które pomagają chronić dane użytkowników Gmaila. Dodaj te zakresy do pliku manifestu dodatku wraz z innymi wymaganymi zakresami.

W tabeli poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają Gmaila. Jeśli dodatek rozszerza Gmaila, musisz dodać do manifestu dodatku Google Workspace wszystkie zakresy oznaczone jako Wymagane.

Zastąp szeroki zakres https://mail.google.com węższym zestawem zakresów, które umożliwiają interakcje potrzebne dodatkowi.

Zakres
Utwórz nowe wersje robocze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Wymagane, 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 często używany z [działaniami związanymi z tworzeniem wiadomości] (/workspace/add-ons/gmail/extending-compose-ui). Wymaga tokena dostępu.
Odczytywanie metadanych otwartej wiadomości	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Udziela tymczasowego dostępu do metadanych otwartej wiadomości (takich jak temat czy odbiorcy). Nie umożliwia odczytywania 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ń związanych z tworzeniem ten zakres jest wymagany, jeśli aktywator tworzenia potrzebuje dostępu do metadanych. W praktyce ten zakres umożliwia wyzwalaczowi tworzenia dostępu do list odbiorców (Do, DW i UDW) wersji roboczej 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.
Odczytywanie treści i metadanych wiadomości	`https://www.googleapis.com/auth/gmail.readonly` odczytywać metadane i treść dowolnego e-maila, w tym otwartej wiadomości; Wymagane, jeśli chcesz odczytywać informacje o innych wiadomościach, np. podczas wysyłania zapytania lub odczytywania całego wątku. Ostrzeżenie: jest to bardzo szeroki zakres z ograniczeniami. Używaj go tylko w razie konieczności.

Zakresy Kalendarza Google

W tabeli poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają funkcje Kalendarza 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ń generowanych przez użytkowników	`https://www.googleapis.com/auth/calendar.addons.current.event.write` Wymagane, jeśli dodatek musi zapisywać dane zdarzeń wygenerowane przez użytkownika. 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 Google Chat API, uwierzytelnij się jako użytkownik Google Chat lub aplikacja Google Chat. 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.

W tabeli poniżej znajdziesz najczęściej używane metody interfejsu Chat API i zakresy na podstawie 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` W przypadku uwierzytelniania aplikacji i zatwierdzania przez administratora (dostępne w ramach wersji przedpremierowej dla programistó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` W przypadku uwierzytelniania aplikacji i zatwierdzania przez administratora (dostępne w ramach wersji przedpremierowej dla programistó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

W tabeli 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. przyznaje dostęp do poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą usługi zaawansowanej Dysku w Apps Scripcie . Nie umożliwia to podobnych działań przy użyciu podstawowej usługi Drive. 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. przyznaje dostęp do poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą usługi zaawansowanej Dysku w Apps Scripcie . Nie umożliwia to podobnych działań przy użyciu podstawowej usługi Drive. 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ą tymczasowy dostęp do danych użytkowników. Aby włączyć tymczasowy dostęp, wywołaj GmailApp.setCurrentMessageAccessToken za pomocą tokena dostępu z obiektu zdarzenia działania.

Token dostępu, który umożliwia zakresy Gmaila, nie jest taki sam jak token dostępu zwracany przez ScriptApp.getOAuthToken. Użyj tokena podanego w obiekcie 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 Twój dodatek korzysta z innych usług Google Workspace lub Apps Script, może wymagać dodatkowych zakresów. W większości przypadków Apps Script wykrywa te zakresy i automatycznie aktualizuje plik manifestu. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastępujesz je węższymi alternatywami.

W tabeli poniżej znajdziesz zakresy, 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 linku 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 @.