Zakresy autoryzacji

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

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

Podczas tego procesu interfejs informuje użytkownika, czego skrypt chce dokonać. Może to na przykład być odczytanie wiadomości e-mail użytkownika lub utworzenie wydarzeń w jego kalendarzu. Projekt skryptu definiuje te indywidualne uprawnienia jako zakresy uprawnień OAuth.

W przypadku większości skryptów Apps Script automatycznie wykrywa, jakie zakresy są Ci potrzebne. Możesz je w każdej chwili wyświetlić. Możesz też jawnie określać zakresy w manifeście za pomocą ciągów znaków adresu URL. W przypadku niektórych aplikacji, np. dodatków, konieczne jest czasami jawne ustawienie zakresów, ponieważ opublikowane aplikacje powinny zawsze używać możliwie najwęższych zakresów.

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

Niektóre zakresy obejmują inne. Na przykład po autoryzacji zakresu https://www.googleapis.com/auth/spreadsheets uzyskuje dostęp do arkuszy kalkulacyjnych z możliwością odczytu i zapisu.

W przypadku niektórych platform, na których działają skrypty, np. w przypadku uruchamiania skryptu bezpośrednio z IDE Apps Script, użytkownicy widzą szczegółowy ekran akceptacji OAuth. Dzięki temu użytkownicy mogą wybrać konkretne uprawnienia, które chcą przyznać, zamiast przyznawać wszystkie uprawnienia naraz. Pamiętaj, aby skrypt obsługiwał szczegółowe uprawnienia OAuth.

Wyświetlanie zakresów

Aby sprawdzić zakresy, których obecnie wymaga Twój projekt skryptu, wykonaj te czynności:

1. Otwórz projekt skryptu.
2. Po lewej stronie kliknij Przegląd.info_outline
3. Aby wyświetlić zakresy, kliknij Zakresy protokołu OAuth projektu.

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 oszczędza 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.

Czasami Apps Script automatycznie przypisuje do projektów bardzo liberalne zakresy. Może to oznaczać, że skrypt prosi użytkownika o więcej, niż jest to konieczne, co jest złym rozwiązaniem. W przypadku opublikowanych skryptów musisz zastąpić zakresy ogólne bardziej ograniczonym zestawem, który spełnia potrzeby skryptu i nie zawiera niczego więcej.

Możesz wyraźnie określić zakresy, których używa projekt skryptu, 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. Odszukaj pole najwyższego poziomu o nazwie 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ść tego tablic odpowiednimi zakresami. 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 zgody OAuth pozwala użytkownikom określić, które poszczególne zakresy OAuth chcą autoryzować. Szczegółowe uprawnienia OAuth zapewniają użytkownikom większą kontrolę nad tym, jakie dane konta chcą udostępniać poszczególnym skryptom. Wyobraź sobie na przykład, że tworzysz skrypt, który prosi o uprawnienia dotyczące zakresów e-maila i kalendarza. Użytkownicy mogą chcieć używać skryptu tylko do obsługi Kalendarza Google, a nie Gmaila. Dzięki szczegółowym uprawnieniom OAuth użytkownicy mogą przyznać uprawnienia tylko do Kalendarza, a nie Gmaila.

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

Automatyczne wymaganie uprawnień do niezbędnych zakresów

Jeśli przepływ wykonywania wymaga uprawnień do zakresów, możesz wymagać od użytkowników przyznania tych uprawnień, zanim będą mogli z niego korzystać. Skrypt może sprawdzić, czy użytkownik już udzielił uprawnień, a jeśli nie, poprosić go automatycznie o ich przyznanie.

Te metody z klasy ScriptApp umożliwiają sprawdzanie uprawnień w wymaganych zakresach i automatyczne wyświetlanie prośby o autoryzację w celu uzyskania brakujących uprawnień:

• requireScopes(authMode, oAuthScopes): używaj tej metody w przypadku przepływów wykonywania, które opierają się na co najmniej 1 zakresie, ale nie na wszystkich zakresach używanych przez skrypt.
• requireAllScopes(authMode): użyj tej metody, jeśli przepływ wykonania opiera się na wszystkich zakresach używanych przez skrypt.

Przykład

Ten przykład pokazuje, jak wywołać metody requireScopes(authMode, oAuthScopes) i requireAllScopes(authMode). 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("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 brakujących zakresów

Możesz uzyskać szczegóły uprawnień użytkownika, który uruchamia skrypt, i zaprojektować niestandardowe działanie na podstawie stanu 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 dialogowe z wyjaśnieniem, dlaczego brakuje uprawnień. Te metody umożliwiają uzyskanie obiektu z informacjami o uprawnieniach użytkownika, w tym o tym, które zakresy zostały przez niego autoryzowane, oraz adresu URL, za pomocą którego można poprosić o brakujące zakresy:

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

Aby uzyskać szczegóły uprawnień z obiektu informacji o autoryzacji, np. listę zakresów, w których udzielono uprawnień, oraz adres URL do żądania brakujących uprawnień, użyj metod z klasy AuthorizationInfo.

Przykład

Ten przykład pokazuje, jak wywołać metodę getAuthorizationInfo(authMode, oAuthScopes), aby pominąć określone funkcje w ramach przepływu wykonywania, w którym nie przyznano wymaganych zakresów. Dzięki temu reszta procesu wykonania 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 uruchomienia mają uprawnienia

Funkcje powiązane z regułami mogą działać automatycznie w przypadku niektórych zdarzeń, a użytkownik może nie być obecny, aby przyznać więcej uprawnień. Przed zainstalowaniem reguły zalecamy użycie requireScopes(authMode, oAuthScopes). W tym przypadku użytkownik zostanie poproszony o przyznanie brakujących uprawnień i nie będzie mógł zainstalować 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żytkownika Google. Jeśli projekt skryptu używa zakresów, które umożliwiają dostęp do danych użytkownika, musisz najpierw przejść weryfikację klienta OAuth, zanim będzie można opublikować go publicznie jako aplikację internetową lub dodatek. Więcej informacji znajdziesz w tych przewodnikach:

• Weryfikacja klienta OAuth w Apps Script
• Niezweryfikowane aplikacje
• Najczęstsze pytania dotyczące weryfikacji OAuth
• Zasady usług interfejsów API Google dotyczące danych użytkownika

Zakresy z ograniczeniami

Oprócz zakresów poufnych niektóre zakresy są klasyfikowane jako ograniczone i podlegają dodatkowym regułom, które pomagają chronić dane użytkownika. Jeśli chcesz opublikować aplikację internetową lub dodatek, który korzysta z co najmniej jednego zakresu z ograniczeniami, aplikacja musi być zgodna ze wszystkimi określonymi ograniczeniami, zanim będzie można ją opublikować.

Zanim spróbujesz opublikować aplikację, zapoznaj się z pełną listą zakresów z ograniczeniami. Jeśli Twoja aplikacja korzysta z jakiegoś z nich, przed opublikowaniem musisz spełnić dodatkowe wymagania dotyczące zakresów interfejsu API.