Zakresy autoryzacji

Użytkownicy muszą autoryzować projekty skryptów, które mają dostęp do ich danych lub działają w ich imieniu. Ogólne omówienie tego procesu znajdziesz w artykule Autoryzacja usług Google. Gdy użytkownik po raz pierwszy uruchamia skrypt, który wymaga autoryzacji, w interfejsie wyświetla się prośba o rozpoczęcie procesu autoryzacji.

W trakcie tego procesu interfejs informuje użytkowników, o jakie uprawnienia prosi skrypt. Skrypt może na przykład poprosić o uprawnienia do odczytywania wiadomości e-mail lub tworzenia wydarzeń w kalendarzu. Projekt skryptu definiuje te poszczególne uprawnienia jako zakresy OAuth.

W przypadku większości skryptów Apps Script automatycznie wykrywa wymagane zakresy. W każdej chwili możesz wyświetlić zakresy używane przez skrypt. Możesz też ustawić zakresy jawnie w swoim manifeście za pomocą ciągów URL. Opublikowane aplikacje, takie jak dodatki, muszą używać jak najwęższych zakresów.

Podczas procesu autoryzacji Apps Script wyświetla zrozumiałe dla człowieka opisy wymaganych zakresów. Jeśli na przykład skrypt potrzebuje dostępu do arkuszy kalkulacyjnych tylko do odczytu, manifest może zawierać zakres https://www.googleapis.com/auth/spreadsheets.readonly. Prośba o autoryzację prosi użytkownika o „Wyświetlenie arkuszy kalkulacyjnych Google”.

Niektóre zakresy obejmują inne. Na przykład autoryzowany dostęp do https://www.googleapis.com/auth/spreadsheets umożliwia odczyt i zapis w arkuszach kalkulacyjnych.

W przypadku niektórych platform, takich jak IDE Apps Script, użytkownicy widzą szczegółowy ekran zgody OAuth. Ten ekran umożliwia użytkownikom wybieranie konkretnych uprawnień, które chcą przyznać, zamiast przyznawać wszystkie uprawnienia naraz. Zaprojektuj swój skrypt tak, aby obsługiwał szczegółowe uprawnienia OAuth.

Zakresy umożliwiające wyświetlanie

Aby zobaczyć zakresy wymagane przez projekt skryptu:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd .
3. Wyświetl zakresy w sekcji Zakresy OAuth projektu.

Ustawianie zakresów jawnych

Apps Script automatycznie określa wymagane zakresy, skanując kod pod kątem wywołań funkcji. W przypadku większości skryptów jest to wystarczające, ale w przypadku opublikowanych dodatków, aplikacji internetowych, aplikacji Google Chat i wywołań interfejsu Chat API musisz mieć większą kontrolę.

Apps Script czasami automatycznie przypisuje zakresy zezwalające. Może to oznaczać, że skrypt prosi użytkowników o większy dostęp, niż jest mu potrzebny. W przypadku opublikowanych skryptów zastąp szerokie zakresy ograniczonym zestawem, który obejmuje potrzeby skryptu.

Ostrzeżenie: zawsze używaj najmniej zezwalającego zestawu zakresów. Aby chronić informacje o użytkownikach, dodatki i inne opublikowane aplikacje nie mogą prosić o więcej uprawnień niż potrzebują.

Możesz jawnie ustawić zakresy używane przez projekt skryptu, edytując jego plik manifestu. Pole manifestu oauthScopes to tablica zakresów używanych przez projekt. Aby ustawić zakresy projektu:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Ustawienia projektu .
3. Zaznacz pole Wyświetlaj plik manifestu „appsscript.json” w edytorze.
4. Po lewej stronie kliknij Edytor .
5. Po lewej stronie kliknij plik appsscript.json.
6. Znajdź pole najwyższego poziomu o nazwie oauthScopes. Jeśli go nie ma, możesz je dodać.
7. Zastąp zawartość tablicy oauthScopes zakresami, których ma używać projekt. Na przykład:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. U góry kliknij Zapisz .

Obsługa szczegółowych uprawnień OAuth

Szczegółowy ekran zgody OAuth został po raz pierwszy uruchomiony w IDE Apps Script dla użytkowników, którzy bezpośrednio wykonują skrypt. Ekran akceptacji jest stopniowo udostępniany w innych miejscach, takich jak makra, reguły i dodatki. Więcej informacji znajdziesz w artykule Szczegółowa akceptacja OAuth w przypadku wykonywania skryptów w IDE Google Apps Script.

Szczegółowy ekran zgody OAuth umożliwia użytkownikom określenie, które poszczególne zakresy OAuth mają być autoryzowane. Dzięki temu użytkownicy mają szczegółową kontrolę nad tym, jakie dane konta udostępniają poszczególnym skryptom. Jeśli na przykład skrypt prosi o zakresy e-maila i kalendarza, użytkownicy mogą przyznać uprawnienia do Kalendarza, ale nie do Gmaila.

W kolejnych sekcjach opisujemy, jak obsługiwać szczegółowe uprawnienia OAuth.

Automatyczne wymaganie uprawnień do niezbędnych zakresów

Jeśli proces wykonywania wymaga określonych zakresów, możesz wymagać od użytkowników przyznania tych uprawnień. Skrypt może sprawdzać uprawnienia i automatycznie o nie prosić, jeśli ich brakuje.

Te metody z klasy ScriptApp sprawdzają uprawnienia i wyświetlają prośbę o autoryzację:

• requireScopes(authMode, oAuthScopes): użyj tej metody w przypadku procesów, które opierają się na określonych zakresach.
• requireAllScopes(authMode): użyj tej metody, jeśli proces wykonywania opiera się na wszystkich zakresach projektu.

Przykład

Poniższy przykład pokazuje, jak wywołać funkcje requireScopes() i requireAllScopes(). Skrypt używa zakresów Gmaila, Arkuszy i Kalendarza. Funkcja sendEmail() wymaga tylko zakresów Gmaila i Arkuszy, a funkcja createEventSendEmail() wymaga wszystkich zakresów używanych przez skrypt.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("[e-mail]", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Tworzenie niestandardowego środowiska dla brakujących zakresów

Możesz pobrać stan uprawnień użytkowników i zaprojektować niestandardowe środowiska. Możesz na przykład wyłączyć funkcje, które wymagają brakujących uprawnień, lub wyświetlić okno z wyjaśnieniem tego wymagania. Te metody pobierają obiekt z informacjami o uprawnieniach użytkownika, który zawiera zakresy autoryzowane przez użytkownika oraz adres URL do żądania brakujących zakresów:

• getAuthorizationInfo(authMode, oAuthScopes): sprawdza stan uprawnień do określonych zakresów.
• getAuthorizationInfo(authMode): sprawdza stan uprawnień do wszystkich zakresów projektu.

Aby uzyskać szczegóły uprawnień z obiektu informacji o autoryzacji, takie jak lista autoryzowanych zakresów i adres URL do żądania brakujących uprawnień, użyj metod z AuthorizationInfo klasy.

Przykład

Poniższy przykład pokazuje, jak użyć funkcji getAuthorizationInfo() do pomijania funkcji, w których użytkownicy nie przyznali wymaganych zakresów. Dzięki temu reszta procesu wykonywania może być kontynuowana bez wyświetlania prośby o autoryzację brakujących zakresów.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("[e-mail]", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

Sprawdzanie, czy wykonania reguł mają uprawnienia

Funkcje powiązane z regułami są uruchamiane automatycznie, a użytkownicy mogą nie być obecni, aby przyznać uprawnienia. Przed zainstalowaniem reguły zalecamy użycie funkcji requireScopes(authMode, oAuthScopes). Spowoduje to wyświetlenie prośby o brakujące uprawnienia i uniemożliwi zainstalowanie reguły bez nich.

Przykład

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}

function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

Weryfikacja OAuth

Niektóre zakresy OAuth są wrażliwe, ponieważ umożliwiają dostęp do danych użytkowników Google. Jeśli projekt skryptu używa zakresów, które umożliwiają dostęp do danych użytkownika, przed opublikowaniem go publicznie jako aplikacji internetowej lub dodatku musi on przejść weryfikację klienta OAuth. Więcej informacji znajdziesz w tych przewodnikach:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania o weryfikację OAuth
• Usługi interfejsu API Google: zasady dotyczące danych użytkowników

Zakresy z ograniczeniami

Oprócz zakresów wrażliwych niektóre zakresy są klasyfikowane jako z ograniczeniami i podlegają dodatkowym regułom, które pomagają chronić dane użytkowników. Jeśli opublikujesz aplikację, która używa zakresów z ograniczeniami, musi ona być zgodna ze wszystkimi specyfikacjami.

Przed opublikowaniem zapoznaj się z pełną listą zakresów z ograniczeniami. Aplikacje zgodne z zasadami muszą spełniać dodatkowe wymagania dotyczące określonych zakresów interfejsu API.

Aby uprościć proces weryfikacji, unikaj używania zakresów z ograniczeniami. W przypadku aplikacji niepublicznych możesz swobodnie używać zakresów z ograniczeniami.