Zakresy autoryzacji

Użytkownicy muszą autoryzować projekty skryptów, które uzyskują dostęp do ich danych lub działają w ich imieniu. Gdy użytkownik po raz pierwszy uruchamia skrypt wymagający autoryzacji, interfejs wyświetla prośbę o rozpoczęcie procesu autoryzacji.

Podczas tego procesu interfejs informuje użytkownika, do czego skrypt chce uzyskać uprawnienia. Na przykład skrypt może chcieć uzyskać uprawnienia do odczytywania wiadomości e-mail użytkownika lub tworzenia wydarzeń w jego kalendarzu. Projekt skryptu definiuje te poszczególne uprawnienia jako zakresy OAuth.

W przypadku większości skryptów Apps Script automatycznie wykrywa zakresy, których potrzebujesz. W każdej chwili możesz wyświetlić zakresy używane przez skrypt. Możesz też jawnie ustawić zakresy w manifeście za pomocą ciągów URL. W przypadku niektórych aplikacji, np. dodatków, czasami wymagane jest jawne ustawienie zakresów, ponieważ opublikowane aplikacje powinny zawsze używać jak najwęższych zakresów.

Podczas procesu autoryzacji Apps Script wyświetla użytkownikowi zrozumiałe opisy wymaganych zakresów. Jeśli na przykład skrypt potrzebuje dostępu tylko do odczytu do arkuszy kalkulacyjnych, plik manifestu może zawierać zakres https://www.googleapis.com/auth/spreadsheets.readonly. Podczas procesu autoryzacji skrypt z tym zakresem prosi użytkownika o zezwolenie aplikacji na „Wyświetlanie arkuszy kalkulacyjnych Google”.

Niektóre zakresy obejmują inne. Na przykład po autoryzacji zakreshttps://www.googleapis.com/auth/spreadsheets umożliwia odczytywanie i zapisywanie arkuszy kalkulacyjnych.

W przypadku niektórych platform, na których działają skrypty, np. podczas uruchamiania skryptu bezpośrednio w IDE Apps Script, użytkownikom wyświetla się szczegółowy ekran akceptacji OAuth. Dzięki temu użytkownicy mogą wybierać konkretne uprawnienia do przyznania, zamiast przyznawać wszystkie naraz. Ważne jest, aby skrypt był zaprojektowany tak, aby obsługiwał szczegółowe uprawnienia OAuth.

Zakresy umożliwiające wyświetlanie

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

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd info_outline.
3. Zakresy znajdziesz w sekcji Zakresy OAuth projektu.

Ustawianie jawnych zakresów

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, aplikacji internetowych, aplikacji Google Chat i wywołań interfejsu Google Chat API musisz mieć większą kontrolę nad zakresami.

Apps Script czasami automatycznie przypisuje projektom bardzo liberalne zakresy. Może to oznaczać, że skrypt prosi użytkownika o więcej informacji, niż potrzebuje, co jest złą praktyką. W przypadku opublikowanych skryptów musisz zastąpić szerokie zakresy bardziej ograniczonym zestawem, który obejmuje potrzeby skryptu i nic więcej.

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

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Ustawienia projektu settings.
3. Zaznacz pole wyboru Wyświetlaj plik manifestu „appsscript.json” w edytorze.
4. Po lewej stronie kliknij Edytor code.
5. Po lewej stronie kliknij plik appsscript.json.
6. Znajdź pole najwyższego poziomu oznaczone etykietą oauthScopes. Jeśli go nie ma, możesz go dodać.
7. Pole oauthScopes określa tablicę ciągów znaków. Aby ustawić zakresy, których używa Twój projekt, zastąp zawartość tej tablicy zakresami, których chcesz używać. Na przykład:

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

8. U góry kliknij Zapisz save.

Obsługa szczegółowych uprawnień OAuth

Szczegółowy ekran akceptacji OAuth umożliwia użytkownikom określenie poszczególnych zakresów OAuth, które chcą autoryzować. Szczegółowe uprawnienia OAuth zapewniają użytkownikom większą kontrolę nad tym, jakie dane konta chcą udostępniać poszczególnym skryptom. Załóżmy na przykład, że tworzysz skrypt, który prosi o uprawnienia do zakresów e-maila i kalendarza. Użytkownicy mogą chcieć używać skryptu tylko do obsługi Kalendarza Google, ale nie Gmaila. Dzięki szczegółowym uprawnieniom OAuth użytkownicy mogą przyznać tylko uprawnienia do Kalendarza, ale nie do Gmaila.

W sekcjach poniżej opisujemy główne sposoby obsługi szczegółowych uprawnień OAuth.

Automatyczne wymaganie uprawnień w przypadku niezbędnych zakresów

Jeśli przepływ wykonania wymaga uprawnień do zakresów, aby działać, możesz wymagać od użytkowników przyznania tych uprawnień, zanim będą mogli go używać. Skrypt może sprawdzić, czy użytkownik przyznał już uprawnienia, a jeśli nie, automatycznie poprosić go o to.

Te metody z ScriptAppklasy umożliwiają weryfikację uprawnień w przypadku wymaganych zakresów i automatyczne wyświetlanie prośby o autoryzację w celu uzyskania brakujących uprawnień:

• requireScopes(authMode, oAuthScopes): użyj tej metody w przypadku przepływów wykonywania, które zależą od co najmniej jednego zakresu, ale nie od wszystkich zakresów używanych przez skrypt.
• requireAllScopes(authMode): użyj tej metody, jeśli przepływ wykonania zależy od wszystkich zakresów używanych przez skrypt.

Przykład

Poniższy przykład pokazuje, jak wywołać metody requireScopes(authMode, oAuthScopes) i requireAllScopes(authMode). Skrypt korzysta z zakresów dla Gmaila, Arkuszy i Kalendarza. Funkcja sendEmail() wymaga tylko zakresów dla 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("dana@example.com", "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("dana@example.com", "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 w przypadku braku zakresów

Możesz uzyskać szczegółowe informacje o uprawnieniach użytkownika, który uruchamia skrypt, i dostosować działanie skryptu do jego uprawnień. Możesz na przykład wyłączyć określone funkcje skryptu, które wymagają uprawnień, których użytkownik nie przyznał, lub wyświetlić niestandardowe okno z wyjaśnieniem, dlaczego brakuje uprawnień. Poniższe metody zwracają obiekt z informacjami o uprawnieniach użytkownika, w tym o zakresach, które użytkownik autoryzował, oraz adres URL umożliwiający wysyłanie próśb o brakujące zakresy:

• getAuthorizationInfo(authMode, oAuthScopes): użyj tej metody, aby sprawdzić stan uprawnień w przypadku konkretnych zakresów.
• getAuthorizationInfo(authMode): Użyj tej metody, aby sprawdzić stan uprawnień dla wszystkich zakresów używanych przez skrypt.

Aby uzyskać szczegółowe informacje o uprawnieniach z obiektu informacji o autoryzacji, np. listę zakresów, które zostały autoryzowane, i adres URL do żądania brakujących uprawnień, użyj metod z klasy AuthorizationInfo.

Przykład

Poniższy przykład pokazuje, jak wywołać metodę getAuthorizationInfo(authMode, oAuthScopes), aby pominąć określone funkcje w przepływie wykonania, w którym nie przyznano wymaganych zakresów. Dzięki temu pozostała część przepływu wykonywania może być kontynuowana bez konieczności 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("dana@example.com", "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 wyzwalaczy mają uprawnienia

Funkcje powiązane z regułami mogą być uruchamiane automatycznie w przypadku określonych zdarzeń, a użytkownik może nie być obecny, aby przyznać więcej uprawnień. Zalecamy użycie requireScopes(authMode, oAuthScopes) przed zainstalowaniem wyzwalacza. Wyświetla to użytkownikowi prośbę o przyznanie brakujących uprawnień i uniemożliwia zainstalowanie wyzwalacza 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 protokołu OAuth są wrażliwe, ponieważ umożliwiają dostęp do danych użytkowników Google. Jeśli projekt skryptu korzysta z zakresów, które umożliwiają dostęp do danych użytkownika, przed opublikowaniem go publicznie jako aplikacji internetowej lub dodatku musi 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 interfejsów API Google: zasady dotyczące danych użytkownika

Zakresy z ograniczeniami

Oprócz zakresów wrażliwych niektóre zakresy są klasyfikowane jako zakresy z ograniczeniami i podlegają dodatkowym regułom, które pomagają chronić dane użytkownika. Jeśli zamierzasz opublikować aplikację internetową lub dodatek, które korzystają z co najmniej jednego zakresu z ograniczeniami, przed opublikowaniem aplikacja musi spełniać wszystkie określone ograniczenia.

Przed opublikowaniem zapoznaj się z pełną listą zakresów z ograniczeniami. Jeśli Twoja aplikacja korzysta z któregoś z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.