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 :
- Otwórz projekt skryptu.
- Po lewej stronie kliknij Przegląd.
- 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 zakresy te zostały ustawione 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
:
- Wyświetl zakresy, których obecnie używa Twój dodatek. Określ konieczne jest wprowadzenie zmian – na przykład zawężenie zakresu.
- Otwórz plik manifestu dodatku.
- Znajdź pole najwyższego poziomu o nazwie
oauthScopes
. Jeśli go nie ma, możesz ją dodać. 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" ], ... }
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 na potrzeby 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 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
|
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
|
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 z 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. |
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 zawartość 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 dla dodatku do |
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ć
|
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. Zezwala projektowi na odczytywanie informacji, które przesyłają użytkownicy 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 @. |