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 uruchomi dodatek po raz pierwszy, w interfejsie dodatku pojawi się prośba o autoryzację.

Podczas tego procesu prompt informuje użytkownika, co aplikacja chce zrobić. Na przykład dodatek może poprosić o uprawnienie do odczytywania wiadomości e-mail użytkownika lub tworzenia wydarzeń w jego kalendarzu. Projekt skryptu dodatku określa te poszczególne uprawnienia jako zakresy OAuth.

Zakresy deklarujesz w pliku manifestu za pomocą ciągów adresów URL. W trakcie procesu autoryzacji Apps Script wyświetla użytkownikowi opis zakresu w postaci zrozumiałej dla człowieka. Na przykład dodatek do Google Workspace może używać zakresu „Read current message” (Odczytaj bieżącą wiadomość), który jest zapisany w pliku manifestu jako https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Podczas procesu autoryzacji dodatek o tym zakresie prosi użytkownika o zgodę na: Wyświetlanie e-maili, gdy dodatek jest uruchomiony.

Zakresy wyświetlania

Aby wyświetlić zakresy, których obecnie wymaga projekt skryptu, wykonaj 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 w polu oauthScopes, ale tylko wtedy, gdy ustawisz te zakresy wyraźnie.

Ustawianie zakresów jawnych

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ć bardziej bezpośrednią kontrolę nad zakresami.

Na przykład Apps Script może domyślnie nadać projektowi skryptu dodatkowego bardzo mało restrykcyjny zakres https://mail.google.com. Gdy użytkownik autoryzuje projekt skryptu o tym zakresie, otrzymuje pełny dostęp do konta Gmail użytkownika. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej ograniczonym zestawem, który zaspokoi potrzeby dodatków.

Zakresy używane w projekcie skryptu możesz bezpośrednio ustawić, edytując plik manifestu. Pole pliku manifestu oauthScopes zawiera wszystkie zakresy używane przez dodatek. Aby ustawić zakresy projektu, wykonaj te czynności:

  1. Wyświetl zakresy, których obecnie używa dodatek. Ustal, jakie zmiany należy wprowadzić, np. za pomocą węższego zakresu.
  2. Otwórz plik manifestu dodatku.
  3. Znajdź 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 używa 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ć:

    {
      ...
      "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 OAuth może wymagać przejścia weryfikacji klienta OAuth przed jego opublikowaniem. 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 korzystającego z co najmniej jednego z ograniczonych zakresów, przed jego opublikowaniem musi on spełniać wszystkie określone ograniczenia.

Zanim spróbujesz opublikować plik, przejrzyj pełną listę zakresów z ograniczeniami. Jeśli Twój dodatek korzysta z któregoś z nich, przed opublikowaniem musisz spełnić Dodatkowe wymagania dotyczące określonych zakresów interfejsów API.

Zakresy kalendarzy

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

Zakres
Dostęp do metadanych zdarzenia https://www.googleapis.com/auth/calendar.addons.execute

Wymagane, jeśli dodatek uzyskuje dostęp do metadanych wydarzeń w Kalendarzu. Umożliwia dodatekowi dostęp do metadanych zdarzenia.

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

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

Zapisywanie danych o zdarzeniach wygenerowanych przez użytkowników https://www.googleapis.com/auth/calendar.addons.current.event.write

Wymagany, jeśli dodatek musi zapisywać dane o zdarzeniach wygenerowanych przez użytkownika. Umożliwia dodatekowi edytowanie danych o zdarzeniach wygenerowanych przez użytkownika. Te dane są dostępne tylko wtedy, gdy pole manifestu addOns.calendar.eventAccess jest ustawione na WRITE lub READ_WRITE.

Zakresy Dysku

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

Zakres
Odczyt metadanych wybranego 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 ograniczonych metadanych elementów wybranych przez użytkownika na Dysku Google. Metadane są ograniczone do identyfikatora elementu, tytułu, typu MIME, adresu URL ikony oraz tego, czy dodatek ma uprawnienia dostępu do elementu.

Dostęp do poszczególnych plików https://www.googleapis.com/auth/drive.file

Zalecane, jeśli dodatek musi mieć dostęp do poszczególnych plików na Dysku. Przyznaje dostęp za każdy plik do plików utworzonych lub otwartych przez aplikację za pomocą zaawansowanej usługi Dysku Apps Script. Nie pozwala to jednak na wykonywanie podobnych działań za pomocą podstawowej usługi Dysk. Autoryzacja plików jest przyznawana dla poszczególnych plików i unieważniana, gdy użytkownik cofa autoryzację aplikacji.

Zobacz przykład wysyłania prośby o dostęp do wybranych plików.

Zakresy dodatków w Gmailu

Istnieje kilka zakresów, które zostały utworzone specjalnie dla dodatków do Google Workspace, aby ułatwić ochronę danych z Gmaila użytkowników. Musisz jawnie dodać te zakresy do pliku manifestu dodatku wraz z innymi zakresami wymaganymi przez kod dodatku.

Poniżej znajdziesz często używane zakresy dodatków do Google Workspace, które rozszerzają Gmaila. Jeśli dodatek obejmuje Gmaila, musisz dodać te z etykietą Wymagane.

Pamiętaj, aby zastąpić też bardzo szeroki zakres https://mail.google.com w dodatku węższym zbiorem zakresów, które pozwolą na interakcje z dodatkiem.

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

Wymagany, jeśli dodatek używa reguł tworzenia treści. Umożliwia dodatekowi tymczasowe tworzenie nowych wersji roboczych wiadomości i odpowiedzi. Więcej informacji znajdziesz w sekcji Tworzenie wersji roboczych wiadomości. Tego zakresu często używa się też do działań tworzenia. Wymaga tokena dostępu.

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

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

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

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

Przyznaje dostęp do treści otwartej wiadomości po interakcji użytkownika, na przykład po wybraniu pozycji w menu dodatku. Wymaga tokena dostępu.

Odczytywanie treści otwartego 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 treści innych wiadomości w otwartym wątku. Wymaga tokena dostępu.

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

odczytywanie metadanych i treści e-maili, w tym otwartej wiadomości; Atrybut wymagany, jeśli musisz odczytać informacje o innych wiadomościach, na przykład podczas wyszukiwania lub czytania całego wątku.

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żytkownika. 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 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();
}

Zakresy edytujących

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

Zakres
Bieżący dostęp do plików Dokumentów https://www.googleapis.com/auth/documents.currentonly

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

Obecny dostęp do plików Arkuszy https://www.googleapis.com/auth/spreadsheets.currentonly

Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Sheets API. Przyznaje tymczasowy dostęp do zawartości otwartego arkusza kalkulacyjnego.

Obecny dostęp do pliku w Prezentacjach https://www.googleapis.com/auth/presentations.currentonly

Wymagane, jeśli dodatek uzyskuje dostęp do interfejsu Apps Script Prezentacji API. Przyznaje tymczasowy dostęp do zawartości otwartej prezentacji.

Dostęp do poszczególnych plików https://www.googleapis.com/auth/drive.file

Wymagane do korzystania przez dodatek z interfejsu onFileScopeGrantedTrigger i dostępu do interfejsu API Dokumentów, Arkuszy, Prezentacji lub Dysku. Przyznaje dostęp za każdy plik do plików utworzonych lub otwartych przez aplikację za pomocą zaawansowanej usługi Dysku Apps Script. Nie pozwala to jednak na wykonywanie podobnych działań za pomocą podstawowej usługi Dysk. Autoryzacja plików jest przyznawana dla poszczególnych plików i unieważniana, gdy użytkownik cofa 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 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 odpowiednimi opcjami, na przykład z węższym zakresem.

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

Zezwala projektowi na odczyt adresu e-mail bieżącego użytkownika.

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

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

Odczytywanie języka i strefy czasowej użytkownika https://www.googleapis.com/auth/script.locale

Zezwala projektowi na naukę języka i strefy czasowej bieżącego użytkownika. Więcej informacji znajdziesz w sekcji Dostęp do języka i strefy czasowej użytkownika.

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

Umożliwia projektowi tworzenie aktywatorów.

Podgląd linków zewnętrznych https://www.googleapis.com/auth/workspace.linkpreview

Wymagany, jeśli dodatek wyświetla linki z usługi innej firmy. Umożliwia projektowi wyświetlanie linku w aplikacji Google Workspace, gdy użytkownik korzysta z niej. Więcej informacji znajdziesz w artykule o wyświetlaniu podglądu linków za pomocą elementów inteligentnych.

Tworzenie zasobów innych firm https://www.googleapis.com/auth/workspace.linkcreate

Wymagany, jeśli dodatek tworzy zasoby w usłudze zewnętrznej. Umożliwia projektowi odczytywanie informacji przesyłanych przez użytkowników w formularzu tworzenia zasobów i wstawianie linku do zasobu w aplikacji Google Workspace. Więcej informacji znajdziesz w artykule o tworzeniu zasobów innych firm za pomocą menu @.