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

Wyświetlanie zakresów

Zakresy, których obecnie wymaga Twój 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 manifeście projektu w polu oauthScopes, ale tylko wtedy, gdy zostały one wyraźnie ustawione.

Ustawianie jednoznacznych zakresów

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 pliku manifestu oauthScopes to tablica wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu, wykonaj te czynności:

1. Wyświetl zakresy, których obecnie używa dodatek. Określ, jakie zmiany należy wprowadzić, np. zawęzić zakres.
2. Otwórz plik manifestu dodatku.
3. Znajdź pole najwyższego poziomu oznaczone etykietą 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ć te 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 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 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.

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 musisz dodać 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.

Zakresy Kalendarza Google

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

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:

Zakresy Dysku Google

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ą 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. Token dostępu musisz uzyskać z obiektu zdarzenia działania.

Poniżej znajdziesz przykład ustawienia 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ą: