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 wykonywania 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 jako https://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 wiadomości e-mail, gdy dodatek jest uruchomiony.

Zakresy, których Apps Script używa 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 tych samych zakresów co 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:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd info_outline.
3. 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 pliku manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu:

1. Wyświetl zakresy używane przez dodatek Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
2. Otwórz plik manifestu dodatku.
3. Znajdź pole najwyższego poziomu o nazwie oauthScopes. Jeśli nie ma go na liście, możesz go dodać.

4. 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"
      ],
      ...
    }
   

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

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania o weryfikację OAuth
• Usługi interfejsów API Google: zasady dotyczące danych użytkownika

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 Twój dodatek używa któregokolwiek z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.

Rozszerzenie Narzędzia dla programistów Google Workspace 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

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

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.

Zakresy Kalendarza Google

W tabeli poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają funkcje Kalendarza Google.

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:

Zakresy Dysku Google

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

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

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