Zakresy

Użytkownicy muszą autoryzować dodatki i inne aplikacje, które mają dostęp do ich danych ani działać w jego 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. Skrypt dodatku projekt definiuje te uprawnienia jako zakresy protokołu OAuth.

Zakresy deklarujesz w pliku manifestu za pomocą ciągów adresów URL. W trakcie procesu autoryzacji Apps Script wyświetla zrozumiały dla użytkownika opis zakresu. Na przykład dodatek do Google Workspace może użyć polecenia „Przeczytaj bieżącą wiadomość” zakresu zapisany w pliku manifestu jako https://www.googleapis.com/auth/gmail.addons.current.message.readonly W trakcie podczas procesu autoryzacji, dodatek z tym zakresem prosi użytkownika dodatek do: Wyświetlanie e-maili po uruchomieniu dodatku.

Zakresy wyświetlania

Zakresy wymagane obecnie przez projekt skryptu możesz sprawdzić, wykonując :

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd. info_outline
3. Sprawdź zakresy w sekcji „Zakresy uprawnień 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 jawnych 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 jest wystarczające i oszczędza czas, ale w przypadku opublikowanych dodatków warto i daje większą kontrolę nad zakresami.

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 w ograniczonym zakresie, który zaspokaja wszystkie potrzeby dodatków.

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 :

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. Znajdź pole najwyższego poziomu o nazwie oauthScopes. Jeśli go nie ma, możesz ją dodać.

4. oauthScopes określa tablicę ciągów znaków. Aby ustawić zakresy przez co Twój projekt zastąpi zawartość tej tablicy zakresami, których ma używać. Na przykład dodatek do Google Workspace, który rozszerza możliwości Gmaila, może zawierać:

   {
     ...
     "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 niektórych wrażliwych zakresów protokołu OAuth może wymagać podania dodatku Weryfikacja klienta OAuth przed opublikowaniem. Więcej informacji znajdziesz w tych przewodnikach:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania dotyczące weryfikacji OAuth
• Usługa interfejsów API Google: zasady 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 co najmniej jednego zakresu z ograniczeniami, dodatek musi być zgodny ze wszystkimi ograniczeń przed opublikowaniem.

Zobacz pełną listę zakresów z ograniczeniami przed podjęciem próby publikacji. Jeśli Twój dodatek korzysta z któregokolwiek z nich, musisz przestrzegać z Dodatkowe wymagania dotyczące określonych zakresów interfejsu API przed publikacją.

Zakresy kalendarza

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

Zakresy Dysku

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

Zakresy dodatków w Gmailu

Istnieje kilka zakresów, które zostały utworzone specjalnie dla Dodatki do Google Workspace ułatwiające ochronę Gmaila użytkowników i skalowalnych danych. Musisz dodaj te zakresy wprost w pliku manifestu dodatku, a także inne wymagany 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 i nie więcej.

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 włączyć dostęp tymczasowy, musisz wywołać metodę funkcja GmailApp.setCurrentMessageAccessToken(accessToken) za pomocą tokena dostępu jako argumentu. Należy uzyskać token dostępu z action event obiekt.

Poniżej znajdziesz przykład ustawienia tokena dostępu, który zezwala na dostęp 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();
}

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.

Inne zakresy

Jeśli dodatek korzysta z innych usług 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 aktualizowanie plik manifestu automatycznie. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastąpisz je bardziej odpowiednią alternatywą, np. do węższego zakresu.

Oto lista zakresów Apps Script, które są często używane w połączeniu z dodatkami do Google Workspace: