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, interfejsu użytkownika dodatku wyświetla prośbę o rozpoczęcie procesu autoryzacji.

Podczas tego procesu prompt informuje użytkownika, czego chce używać aplikacja takich działań. Na przykład dodatek może potrzebować uprawnień do odczytu wiadomości e-mail użytkownika lub tworzyć wydarzenia 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.
  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 ramach dokumentu oauthScopes ale tylko wtedy, gdy ustawisz te zakresy bezpośrednio.

Ustawianie jawnych zakresów

Apps Script automatycznie określa zakresy, których potrzebuje skrypt, skanując je dla 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 przyznać projektowi skryptu dodatkowemu bardzo mało restrykcyjny zakres https://mail.google.com. Gdy użytkownik autoryzuje skrypt projekt o tym zakresie, otrzyma on pełny dostęp do Gmaila użytkownika koncie. W przypadku opublikowanych dodatków musisz zastąpić ten zakres bardziej w ograniczonym zakresie, który zaspokaja wszystkie potrzeby dodatków.

Zakresy używane przez projekt skryptu możesz bezpośrednio ustawić, edytując jej plik manifest. Pole pliku manifestu oauthScopes jest tablicą wszystkich zakresów używanych przez dodatek. Aby ustawić zakresy projektu, wykonaj :

  1. Wyświetl zakresy, których obecnie używa Twój dodatek. Określ niezbędne są zmiany – na przykład węższy zakres.
  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:

Zakresy z ograniczeniami

Niektóre zakresy są ograniczone i podlegają dodatkowym regułom, które pomagają ochrony danych 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 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 uzyskuje dostęp do metadanych wydarzeń w Kalendarzu. Dozwolone aby uzyskać dostęp do metadanych zdarzeń.

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

Wymagany, jeśli dodatek musi odczytywać dane zdarzenia wygenerowane przez użytkowników. Zezwala na dostęp dodatku do danych zdarzenia wygenerowanych przez użytkowników. Te dane są dostępna tylko wtedy, gdy addOns.calendar.eventAccess pole manifestu jest ustawiona na READ lub READ_WRITE.

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

Wymagany, jeśli dodatek musi zapisywać dane zdarzenia wygenerowane przez użytkowników. Zezwala dodatkiowi na edytowanie danych zdarzenia wygenerowanych przez użytkowników. Te dane są dostępna tylko wtedy, gdy addOns.calendar.eventAccess pole manifestu jest ustawiona na WRITE lub READ_WRITE.

Zakresy Dysku

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

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

Wymagane, jeśli dodatek implementuje interfejs kontekstowy aktywowany gdy użytkownik wybiera elementy na Dysku. Zezwala dodatek na odczytywanie ograniczony metadanych elementów posiadanych przez użytkownika zaznaczono na Dysku Google. Metadane są ograniczone do identyfikatora produktu, tytułu, typu MIME, adresu URL ikony oraz tego, czy dodatek ma uprawnienia do uzyskać dostęp do danego elementu.

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

Zalecane, jeśli dodatek musi mieć dostęp do indywidualnego Dysku . Przyznaje dostęp poszczególnych plików do plików utworzonych lub otwartych w aplikacji za pomocą Apps Script – zaawansowany Dysk Usługa. Nie pozwala na wykonywanie podobnych działań za pomocą podstawowej usługi Dysku, . Autoryzacja plików jest przyznawana na poziomie pliku i odwołana, gdy użytkownik cofnie autoryzację aplikacji.

Zobacz Przykład 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 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 dodatków do Google Workspace, które rozszerzają funkcje Gmaila. te z etykietą Wymagane należy dodać do Plik manifestu dodatku do Google Workspace, jeśli dodatek jest rozszerzony Gmail;

Pamiętaj też, aby zastąpić bardzo szeroki zakres https://mail.google.com w dodatek o węższym zestawie zakresów, które umożliwiają interakcje z dodatkiem do ich potrzeb.

Zakres
Utwórz nowe wersje robocze https://www.googleapis.com/auth/gmail.addons.current.action.compose

Wymagany, jeśli dodatek używa funkcji działania związane z tworzeniem wiadomości. Zezwala dodatek na tymczasowe tworzenie nowych wersji roboczych wiadomości oraz odpowiedzi. Zobacz Tworzenie wersji roboczych wiadomości więcej informacji; ten zakres jest również często używany z funkcją tworzenia wiadomości. 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 (takich jak temat lub odbiorców). Nie pozwala na czytanie treści wiadomości i wymaga tokena dostępu.

Wymagany, jeśli dodatek używa metadanych podczas tworzenia wiadomości reguły. Dla działania tworzenia wiadomości, ten zakres jest wymagany w przypadku aktywatora tworzenia wiadomości. potrzebuje dostępu do metadanych. W praktyce pozwala on wywoływanie list odbiorców z dostępem do odpowiedzi (do:, DW: i UDW:) wersji roboczej e-maila.

Odczytywanie treści otwartej 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; np. gdy w menu zostanie wybrany dodatek. Wymaga dostępu token.

Odczytaj treść 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 otwartej w wątku. Wymaga tokena dostępu.

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

Odczytaj metadane i treść e-maila, w tym otwartą wiadomość. Wymagany, jeśli chcesz odczytać inne wiadomości, takie jak podczas wyszukiwania lub czytania całego wątku.

Tokeny dostępu

Aby chronić dane użytkowników, zakresy Gmaila używane w Przyznane tylko dodatki do Google Workspace tymczasowy dostęp do danych użytkownika. Aby włączyć tymczasowy dostęp, 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 jedyny wymagany zakres 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 edytora

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

Zakres
Aktualny dostęp do plików Dokumentów https://www.googleapis.com/auth/documents.currentonly

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

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

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

Aktualny dostęp do plików Prezentacji https://www.googleapis.com/auth/presentations.currentonly

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

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

Wymagane, aby dodatek mógł korzystać z onFileScopeGrantedTrigger oraz dostęp do interfejsu API Dokumentów, Arkuszy, Prezentacji lub Dysku. Przyznaje dostęp poszczególnych plików do plików utworzonych lub otwartych w aplikacji za pomocą Apps Script – zaawansowany Dysk Usługa. Nie pozwala na wykonywanie podobnych działań za pomocą podstawowej usługi Dysku, . Autoryzacja plików jest przyznawana na poziomie pliku i odwołane, gdy użytkownik cofnie autoryzację aplikacji.

Inne zakresy

Twój dodatek może wymagać dodatkowych zakresów, jeśli używa innych usług Apps Script. 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 często używanych 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.

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

Pozwala projektowi tworzyć UrlFetch żądań. Jest to również wymagane, jeśli projekt korzysta z interfejsu OAuth2 na potrzeby biblioteki Apps Script.

Odczytywanie ustawień regionalnych i strefy czasowej użytkownika https://www.googleapis.com/auth/script.locale

Pozwala projektowi poznać język i strefę czasową bieżącego użytkownika. Zobacz Dostęp do ustawień regionalnych i strefy czasowej użytkownika, aby dowiedzieć się więcej.

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

Umożliwia projektowi tworzenie reguły.

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

Wymagany, jeśli dodatek wyświetla podgląd linków z usługi innej firmy. Zezwala projektowi na dostęp do linku w aplikacji Google Workspace, gdy użytkownik wchodzi z nią w interakcję. Więcej informacji można znaleźć w sekcji Wyświetl podgląd linków z elementami inteligentnymi.

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

Wymagany, jeśli dodatek tworzy zasoby w usłudze innej firmy. Umożliwia projektowi odczytywanie informacji przesyłanych przez użytkowników formularz tworzenia zasobów wstaw link do zasobu w aplikacji Google Workspace. Więcej informacji można znaleźć w sekcji Zasoby innych firm możesz tworzyć za pomocą menu @.