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ę, aby rozpocząć 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 deklarujesz w pliku manifestu 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:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd.info_outline
3. 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 konta Gmail użytkownika. 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 wyraźnie określić zakresy, których używa projekt skryptu, edytując jego plik manifestu. Pole manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu, wykonaj te czynności:

1. Wyświetl zakresy stosowane obecnie przez Twoje rozszerzenie Określ, jakie zmiany należy wprowadzić, np. zawężenie zakresu.
2. Otwórz plik manifestu dodatku.
3. Odszukaj 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, których ma używać projekt, zastąp zawartość tego tablic odpowiednimi zakresami. 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"
     ],
     ...
   }
   

5. 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:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania dotyczące weryfikacji OAuth
• Zasady usług interfejsów API Google dotyczące danych użytkownika

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, musisz się upewnić, że dodatek jest zgodny ze wszystkimi określonymi ograniczeniami.

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 konkretnych zakresów interfejsu API.

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

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

Zakresy edytującego

Poniżej znajdziesz często używane zakresy uprawnień dla dodatków Google Workspace, które rozszerzają Dokumenty, Arkusze i Prezentacje.

Gmail

Kilka zakresów zostało utworzonych specjalnie dla dodatków Google Workspace, 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 uprawnień https://mail.google.com w rozszerzeniu wąskim zakresem uprawnień, który umożliwia interakcje wymagane przez rozszerzenie, ale nie więcej.

Zakresy uprawnień Kalendarza Google

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

Zakresy Google Chat

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

Więcej informacji o zakresach uprawnień i typach uwierzytelniania w Google Chat znajdziesz w artykule Omówienie uwierzytelniania i autoryzacji w Google Chat API.

Poniższa tabela zawiera często używane metody i zakresy interfejsu Chat API na podstawie obsługiwanych typów uwierzytelniania:

Zakresy Dysku Google

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

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 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 Google Workspace: