Zakresy autoryzacji

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 manifest za pomocą ciągów znaków adresu URL. W przypadku niektórych aplikacji, np. dodatków, konieczne jest czasami jawne ustawianie 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 się uprawnienia do odczytu i zapisu w arkuszach kalkulacyjnych.

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, przejdź do sekcji Zakresy protokołu OAuth projektu.

Ustawianie zakresów dokładnych

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ż potrzebuje, 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 jawnie ustawić zakresy, których używa projekt skryptu, edytując jego plik manifest. 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 dają 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 wykonania wymaga uprawnień do zakresów, możesz wymagać od użytkowników przyznania tych uprawnień, zanim będą mogli korzystać z przepływu. Skrypt może sprawdzić, czy użytkownik wyraził już zgodę, a jeśli nie, poprosić o nią automatycznie.

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 uruchamiającego skrypt i zaprojektować niestandardowe rozwiązanie 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 zostały przyznane wymagane zakresy. 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...
}

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 przesłać go do weryfikacji klienta OAuth, aby móc 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.