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 dodatku wyświetli się prośba o autoryzację, aby rozpocząć proces autoryzacji.

Podczas tego procesu pojawi się powiadomienie informujące użytkownika o tym, do czego aplikacja chce uzyskać uprawnienia. Dodatek może np. prosić o pozwolenie na odczytanie e-maila użytkownika lub utworzenie wydarzenia w jego kalendarzu. Projekt skryptu dodatku definiuje te indywidualne uprawnienia jako zakresy OAuth.

Zakresy możesz zadeklarować w pliku manifestu za pomocą ciągów URL. W trakcie procesu autoryzacji Apps Script wyświetla użytkownikowi czytelny dla użytkownika opis zakresu. Na przykład Twój dodatek do Google Workspace może korzystać z zakresu „Odczyt 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 prosi użytkownika o zezwolenie na jego wyświetlanie: Wyświetlanie e-maili w czasie, gdy dodatek jest uruchomiony.

Wyświetlanie zakresów

Zakresy, z których obecnie korzysta Twój projekt skryptu, możesz sprawdzić, wykonując te czynności:

  1. Otwórz projekt skryptu.
  2. Po lewej stronie kliknij Przegląd.
  3. Wyświetl 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 te zakresy są wyraźnie.

Ustawianie wyraźnych zakresów

Apps Script automatycznie określa zakresy, których potrzebuje skrypt. Skanuje on kod pod kątem wywołań funkcji, które tego wymagają. W przypadku większości skryptów jest to wystarczający i oszczędza czas, ale w przypadku opublikowanych dodatków należy mieć większą kontrolę nad zakresami.

Na przykład Apps Script może domyślnie przyznać projektowi skryptu dodatkowego uprawnienia bardzo mało restrykcyjne https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu z tym zakresem, uzyska on pełny dostęp do konta Gmail użytkownika. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który spełnia wymagania dodatku.

Zakresy, których Twój projekt skryptu może używać, możesz bezpośrednio zmodyfikować w pliku 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 Twój dodatek obecnie używa Określ, jakie zmiany należy wprowadzić, na przykład węższy zakres.
  2. Otwórz plik manifestu dodatku.
  3. Znajdź pole najwyższego poziomu oauthScopes. Jeśli go nie ma, możesz ją dodać.

  4. Pole oauthScopes określa tablicę ciągów znaków. Aby ustawić zakresy używane przez projekt, zastąp zawartość tej tablicy zakresami, których chcesz używać. Dodatek do Google Workspace, który rozszerza Gmaila, może mieć na przykład:

    {
  ...
  "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 określonych zakresów wrażliwych OAuth może wymagać, aby dodatek został zweryfikowany przez klienta OAuth OAuth, zanim będzie można go opublikować. Więcej informacji znajdziesz w tych przewodnikach:

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym regułom, które pomagają chronić dane użytkowników. Jeśli chcesz opublikować dodatek do Gmaila lub edytora, który korzysta z co najmniej 1 ograniczonego zakresu, przed opublikowaniem dodatku musi on spełnić wszystkie określone wymagania.

Zanim spróbujesz opublikować treści, przejrzyj pełną listę zakresów z ograniczeniami. Jeśli Twój dodatek korzysta z któregokolwiek z nich, przed jego opublikowaniem musisz przestrzegać dodatkowych wymagań dotyczących określonych zakresów interfejsu API.

Zakresy kalendarza

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają możliwości Kalendarza Google.

Zakres
Metadane zdarzenia dostępu https://www.googleapis.com/auth/calendar.addons.execute

Wymagany, jeśli dodatek ma dostęp do metadanych wydarzeń w Kalendarzu. Zezwala na dostęp dodatku do metadanych zdarzeń.

Odczytywanie danych zdarzeń wygenerowanych przez użytkownika https://www.googleapis.com/auth/calendar.addons.current.event.read

Wymagany, jeśli dodatek musi odczytywać dane zdarzeń wygenerowane przez użytkownika. Zezwala na dostęp do danych zdarzeń wygenerowanych przez użytkownika. Te dane są dostępne tylko wtedy, gdy pole manifestu addOns.calendar.eventAccess ma wartość READ lub READ_WRITE.

Zapisywanie danych zdarzeń użytkownika https://www.googleapis.com/auth/calendar.addons.current.event.write

Wymagany, jeśli dodatek musi zapisywać dane zdarzeń użytkownika. Zezwala dodatku na edytowanie danych zdarzeń wygenerowanych przez użytkownika. Te dane są dostępne tylko wtedy, gdy pole manifestu addOns.calendar.eventAccess ma wartość WRITE lub READ_WRITE.

Zakresy Dysku

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

Zakres
Odczytywanie wybranych metadanych elementu https://www.googleapis.com/auth/drive.addons.metadata.readonly

Wymagany, jeśli dodatek implementuje interfejs kontekstowy aktywowany, gdy użytkownik wybiera elementy na Dysku. Zezwala na odczyt dodatkowych 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 określenia, czy dodatek ma uprawnienia dostępu do elementu.

Dostęp na poziomie pliku https://www.googleapis.com/auth/drive.file

Zalecane, jeśli dodatek potrzebuje dostępu do poszczególnych plików na Dysku Przyznaje dostęp do poszczególnych plików utworzonych lub otwartych przez aplikację przy użyciu zaawansowanej usługi Dysku Apps Script. Nie pozwala to jednak używać podobnych działań w podstawowej usłudze Dysk. Autoryzacja plików jest przyznawana poszczególnym plikom i jest unieważniana, gdy użytkownik cofnie autoryzację aplikacji.

Zobacz przykład żądania dostępu do wybranych plików.

Zakresy dodatków w Gmailu

Istnieje kilka zakresów utworzonych specjalnie dla Dodatków do Google Workspace, które pomagają chronić dane Gmaila użytkowników. Musisz dodać te zakresy wprost do pliku manifestu dodatku wraz z innymi wymaganymi kodami dodatku.

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają możliwości Gmaila. Te oznaczone etykietą Wymagany trzeba dodać do pliku manifestu dodatku Google Workspace, jeśli dodatek rozszerza Gmaila.

Pamiętaj, aby zastąpić bardzo szeroki zakres https://mail.google.com w dodatku węższym zakresem, który określa interakcje, których nie potrzebujesz.

Zakres
Tworzenie nowych wersji roboczych https://www.googleapis.com/auth/gmail.addons.current.action.compose

Wymagany, jeśli dodatek korzysta z aktywatorów tworzenia wiadomości. Zezwala na tymczasowe tworzenie nowych wersji roboczych wiadomości i odpowiedzi. Więcej informacji znajdziesz w sekcji Tworzenie wersji roboczych wiadomości. Ten zakres jest też często używany w przypadku działań tworzenia. Wymaga tokena dostępu.

Odczyt metadanych otwartych wiadomości https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Przyznaje tymczasowy dostęp do metadanych otwartej wiadomości (na przykład tematu lub adresatów). Nie pozwala na odczytywanie treści wiadomości i wymaga tokena dostępu.

Wymagany, jeśli dodatek używa metadanych w aktywatorach tworzenia wiadomości. W przypadku działań tworzenia ten zakres jest wymagany, jeśli aktywator tworzenia wiadomości wymaga dostępu do metadanych. W praktyce ten zakres umożliwia utworzenie wiadomości z listą adresatów (do:, DW: i UDW:) wersji roboczej odpowiedzi.

Odczytywanie zawartości otwartej wiadomości https://www.googleapis.com/auth/gmail.addons.current.message.action

Przyznaje dostęp do zawartości otwartej wiadomości po interakcji użytkownika, np. po wybraniu elementu menu dodatku. Wymaga tokena dostępu.

Odczytywanie zawartości wątku https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Przyznaje tymczasowy dostęp do metadanych i treści otwartej wiadomości. Przyznaje też dostęp do zawartości innych wiadomości w otwartym wątku. Wymaga tokena dostępu.

odczytywanie dowolnych treści i metadanych, https://www.googleapis.com/auth/gmail.readonly

Przeczytaj metadane i treści e-maila, w tym wiadomość otwartą. Wymagane, jeśli chcesz odczytać informacje o innych wiadomościach, na przykład podczas wyszukiwania zapytania lub przeczytania całego wątku poczty.

Tokeny dostępu

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

Poniżej znajdziesz przykład ustawienia tokena dostępu umożliwiającego dostęp do metadanych wiadomości. Jedynym zakresem niezbędnym w tym przykładzie jest 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 edytora

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

Zakres
Dostęp do bieżącego pliku Dokumentów https://www.googleapis.com/auth/documents.currentonly

Wymagany, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Docs API. Przyznaje tymczasowy dostęp do zawartości otwartego dokumentu.

Dostęp do bieżących plików Arkuszy https://www.googleapis.com/auth/spreadsheets.currentonly

Wymagany, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Sheets API. 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 na poziomie pliku https://www.googleapis.com/auth/drive.file

Wymagany, aby dodatek mógł korzystać z onFileScopeGrantedTrigger oraz jeśli dodatek uzyskuje dostęp do interfejsów API REST Dokumentów, Arkuszy, Prezentacji lub Dysku Przyznaje dostęp do poszczególnych plików utworzonych lub otwartych przez aplikację przy użyciu zaawansowanej usługi Dysku Apps Script. Nie pozwala to jednak używać podobnych działań w podstawowej usłudze Dysk. Autoryzacja plików jest przyznawana poszczególnym plikom i jest unieważniana, gdy użytkownik cofnie autoryzację aplikacji.

Inne zakresy

Twój dodatek może wymagać dodatkowych zakresów, jeśli korzysta z innych usług Apps Script. W większości przypadków możesz użyć Apps Script, aby automatycznie wykrywać te zakresy i automatycznie aktualizować plik manifestu. Podczas edytowania listy zakresów w pliku manifestu nie usuwaj żadnych zakresów, chyba że zastąpisz je bardziej odpowiednią opcją, np. węższą.

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

Zakres
Odczytywanie adresu e-mail użytkownika https://www.googleapis.com/auth/userinfo.email

Umożliwia projektowi odczyt adresów e-mail bieżącego użytkownika.

Zezwalaj na połączenia z usługami zewnętrznymi https://www.googleapis.com/auth/script.external_request

Zezwala na wysyłanie przez projekt żądań do UrlFetch. Jest to też wymagane, jeśli projekt korzysta z biblioteki OAuth2 for Apps Script.

Odczytuj ustawienia regionalne i strefę czasową użytkownika https://www.googleapis.com/auth/script.locale

Umożliwia projektowi poznanie języka i strefy czasowej bieżącego użytkownika. Więcej informacji znajdziesz w sekcji Uzyskiwanie dostępu do ustawień regionalnych i strefy czasowej użytkownika.

Utworzenie reguł. https://www.googleapis.com/auth/script.scriptapp

Zezwala projektowi na tworzenie aktywatorów.