Ta strona została przetłumaczona przez Cloud Translation API.

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, w interfejsie pojawi się prośba o autoryzację, która rozpocznie proces autoryzacji.

Podczas tego procesu użytkownik dowiaduje się, jakie uprawnienia chce uzyskać aplikacja. Na przykład dodatek może chcieć uzyskać uprawnienia 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 określasz w manifest za pomocą ciągów znaków adresu 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 Google Workspace może używać zakresu „Czytaj bieżącą wiadomość”, który w pliku manifestu jest zapisany jako https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Podczas procesu autoryzacji dodatek o takim zakresie uprawnień prosi użytkownika o zezwolenie na: wyświetlanie e-maili, gdy dodatek jest uruchomiony.

Wyświetlanie zakresów

Aby sprawdzić zakresy, których obecnie wymaga Twój projekt skryptu, wykonaj te czynności:

Otwórz projekt skryptu.
Po lewej stronie kliknij Przegląd.
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 https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu z takim zakresem, projektowi przyznawany jest pełny dostęp do jego konta Gmail. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który obejmuje potrzeby dodatków i nic więcej.

Możesz jawnie ustawić zakresy, których używa 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:

Wyświetl zakresy stosowane obecnie przez Twoje rozszerzenie Określ, jakie zmiany należy wprowadzić, np. zawężenie zakresu.
Otwórz plik manifestu dodatku.
Odszukaj pole najwyższego poziomu o nazwie oauthScopes. Jeśli go nie ma, 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ść tego tablic zakresami, których ma używać. Na przykład w przypadku 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"
  ],
  ...
}
```
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:

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym zasadom, które pomagają chronić dane użytkowników. Jeśli chcesz opublikować dodatek do Gmaila lub Edytora, który korzysta z co najmniej jednego ograniczonego zakresu, musi on być zgodny ze wszystkimi określonymi ograniczeniami, zanim będzie można go opublikować.

Zanim spróbujesz opublikować aplikację, 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 określonych zakresów interfejsu API.

Wybieranie zakresów uprawnień dla dodatków do Google Workspace

W kolejnych sekcjach opisaliśmy zakresy stosowane najczęściej w przypadku dodatków Google Workspace.

Zakresy edytującego

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

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.

Zakres
Dostęp do bieżących plików Dokumentów	`https://www.googleapis.com/auth/documents.currentonly` Wymagany, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Docs API. Przyznawanie tymczasowego dostępu do treści otwartego dokumentu.
Dostęp do bieżących plików Arkuszy	`https://www.googleapis.com/auth/spreadsheets.currentonly` Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Sheets API w Apps Script. 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 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, aby dodatek mógł korzystać z interfejsu `onFileScopeGrantedTrigger`i jeśli dodatek ma dostęp do interfejsu API Dokumentów, Arkuszy, Prezentacji lub Dysku. Przyznawanie dostępu do poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą usługi Dysku zaawansowanego skryptu Apps Script. Nie można jednak wykonywać podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja pliku jest przyznawana na poziomie pliku i zostaje cofnięta, gdy użytkownik anuluje autoryzację aplikacji.

Gmail

Kilka zakresów zostało utworzonych specjalnie dla Google Workspace Add-ons, aby chronić dane użytkowników Gmaila. Musisz wyraźnie dodać te zakresy do pliku manifestu dodatku wraz z innymi zakresami wymaganymi przez kod dodatku.

Poniżej znajdziesz często używane zakresy uprawnień dla dodatków Google Workspace, które rozszerzają Gmaila. Te oznaczone jako Wymagane musisz dodać do pliku manifestu dodatku Google Workspace, jeśli Twój dodatek rozszerza Gmaila.

Pamiętaj też, aby zastąpić bardzo szeroki zakres dostępu https://mail.google.com w rozszerzeniu wąskim zakresem dostępu, który umożliwia interakcje wymagane przez rozszerzenie i tylko te interakcje.

Zakres
Utwórz nowe wersje robocze	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` Wymagany, jeśli dodatek używa komponowania wyzwalaczy działań. Umożliwia dodatkowi tymczasowe tworzenie nowych wiadomości i odpowiedzi. Szczegółowe informacje znajdziesz w artykule Tworzenie wiadomości w postaci wersji roboczych. Ten zakres jest też często używany w akcjach tworzenia wiadomości. Wymaga tokena dostępu.
Odczytywanie metadanych otwartej wiadomości	`https://www.googleapis.com/auth/gmail.addons.current.message.metadata` Daje tymczasowy dostęp do metadanych otwartej wiadomości (takich jak temat lub adresaci). Nie zezwala na odczytywanie treści wiadomości i wymaga tokena dostępu. Wymagany, jeśli dodatek używa metadanych w działaniach tworzących wyzwalacze. W przypadku działań komponowania ten zakres jest wymagany, jeśli wyzwalacz komponowania potrzebuje dostępu do metadanych. W praktyce ten zakres uprawnień pozwala aplikacji tworzyć i dostępować do list odbiorców (do, cc i udw) w e-mailu w postaci szkicu.
Czytanie otwartych wiadomości	`https://www.googleapis.com/auth/gmail.addons.current.message.action` Przyznawanie dostępu do treści otwartej wiadomości po interakcji użytkownika, na przykład po wybraniu pozycji menu dodatku. Wymaga tokena dostępu.
Czytanie treści otwartego wątku	`https://www.googleapis.com/auth/gmail.addons.current.message.readonly` Daje tymczasowy dostęp do metadanych i treści otwartej wiadomości. Daje też dostęp do treści innych wiadomości w otwartym wątku. Wymaga tokena dostępu.
odczytywać treści i metadane wiadomości;	`https://www.googleapis.com/auth/gmail.readonly` czytać metadanych i treści e-maili, w tym otwartych wiadomości; Wymagane, jeśli chcesz odczytać informacje o innych wiadomościach, na przykład podczas wyszukiwania lub czytania całego wątku e-mail. Ostrzeżenie: jest to bardzo szeroki zakres z ograniczeniami. Używaj go tylko w razie konieczności.

Zakresy uprawnień Kalendarza Google

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

Zakres
Dostęp do metadanych zdarzeń	`https://www.googleapis.com/auth/calendar.addons.execute` Wymagane, jeśli dodatek ma dostęp do metadanych wydarzeń w Kalendarzu. Umożliwia dodatkowi dostęp do metadanych zdarzenia.
Odczytywanie danych zdarzeń generowanych przez użytkowników	`https://www.googleapis.com/auth/calendar.addons.current.event.read` Wymagany, 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` Wymagany, jeśli dodatek musi zapisywać dane zdarzeń generowanych 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 Dysku Google

Poniżej znajdziesz często używane zakresy uprawnień wtyczek Google Workspace, które rozszerzają Dysk Google.

Zakres

odczytywanie metadanych wybranego elementu;

Zakres
odczytywanie metadanych wybranego elementu;	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` Wymagany, jeśli dodatek implementuje interfejs kontekstowy uruchamiany, gdy użytkownik wybierze elementy w Drive. Umożliwia dodatkowi odczyt ograniczonych metadanych dotyczących elementów wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora, 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. Przyznawanie dostępu do poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą usługi Dysku zaawansowanego skryptu Apps Script. Nie można jednak wykonywać podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja pliku jest przyznawana dla każdego pliku z osobna i zostaje cofnięta, gdy użytkownik anuluje autoryzację aplikacji. Zobacz przykład prośby o dostęp do wybranych plików.

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

Wymagany, jeśli dodatek implementuje interfejs kontekstowy uruchamiany, gdy użytkownik wybierze elementy w Drive. Umożliwia dodatkowi odczyt ograniczonych metadanych dotyczących elementów wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora, 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. Przyznawanie dostępu do poszczególnych plików utworzonych lub otwartych przez aplikację za pomocą usługi Dysku zaawansowanego skryptu Apps Script. Nie można jednak wykonywać podobnych działań za pomocą podstawowej usługi Dysku. Autoryzacja pliku jest przyznawana dla każdego pliku z osobna i zostaje cofnięta, gdy użytkownik anuluje autoryzację aplikacji.

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

Tokeny dostępu

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

Poniżej znajdziesz przykład ustawienia tokena dostępu, aby umożliwić dostęp do metadanych wiadomości. W tym przykładzie wymagany jest tylko zakres 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 uprawnień 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 pozwolić Apps Script wykryć te zakresy i automatycznie zaktualizować plik manifestu. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastąpisz je bardziej odpowiednią opcją, na przykład węższym zakresem.

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

Zakres
Czytanie 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 też wymagane, jeśli projekt korzysta z biblioteki OAuth2 dla Apps Script.
Odczytywanie ustawień języka i strefy czasowej użytkownika	`https://www.googleapis.com/auth/script.locale` Umożliwia projektowi określenie lokalizacji i strefy czasowej bieżącego użytkownika. Więcej informacji znajdziesz w artykule Uzyskiwanie dostępu do ustawień języka i strefy czasowej użytkownika.
Utworzenie reguł.	`https://www.googleapis.com/auth/script.scriptapp` Umożliwia projektowi tworzenie wyzwalaczy.
Podgląd linków zewnętrznych	`https://www.googleapis.com/auth/workspace.linkpreview` Wymagane, jeśli w podglądzie widać linki do usługi zewnętrznej. Umożliwia projektowi wyświetlanie linku w aplikacji Google Workspace, gdy użytkownik z nią pracuje. Więcej informacji znajdziesz w artykule Wyświetlanie podglądów 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 zasobu oraz dodawanie linku do zasobu w aplikacji Google Workspace. Więcej informacji znajdziesz w artykule Tworzenie zasobów innych firm za pomocą menu @.