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.

W tym procesie interfejs informuje użytkowników, o jakie uprawnienia prosi skrypt. Na przykład skrypt może poprosić o uprawnienia do odczytywania e-maili 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ż jawnie ustawić zakresy w 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 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. Prośba o autoryzację wyświetla użytkownikowi komunikat „Wyświetlanie arkuszy kalkulacyjnych Google”.

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

W przypadku niektórych platform, takich jak środowisko IDE Apps Script, użytkownicy widzą ekran szczegółowej zgody OAuth. Na tym ekranie użytkownicy mogą wybrać konkretne uprawnienia do przyznania, zamiast przyznawać wszystkie uprawnienia naraz. Zaprojektuj skrypt tak, aby obsługiwał szczegółowe uprawnienia OAuth.

Zakresy umożliwiające wyświetlanie

Aby sprawdzić, jakich zakresów wymaga projekt skryptu:

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 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 do obsługi czatu i wywołań interfejsu Chat API musisz mieć większą kontrolę.

Apps Script czasami automatycznie przypisuje zakresy o szerokich uprawnieniach. Może to oznaczać, że skrypt prosi użytkowników o dostęp do większej liczby danych, niż jest to konieczne. W przypadku opublikowanych skryptów zastąp szerokie zakresy ograniczonym zestawem, który obejmuje potrzeby skryptu.

Zakresy używane przez projekt skryptu możesz ustawić w sposób jawny, edytując jego plik manifestu. Pole oauthScopes manifest to tablica 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 jako oauthScopes. Jeśli go nie ma, możesz go 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 save.

Obsługa szczegółowych uprawnień OAuth

Szczegółowy ekran zgody OAuth został po raz pierwszy wprowadzony w IDE Apps Script dla użytkowników, którzy uruchamiają skrypt bezpośrednio. Ekran zgody będzie stopniowo udostępniany w innych usługach, takich jak makra, wyzwalacze i dodatki. Więcej informacji znajdziesz w artykule Szczegółowa zgoda OAuth w przypadku wykonywania kodu w środowisku IDE Google Apps Script.

Ekran szczegółowej 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 wymaga zakresów dostępu do poczty e-mail i kalendarza, użytkownicy mogą przyznać uprawnienia do Kalendarza, ale nie do Gmaila.

W sekcjach poniżej znajdziesz informacje o tym, jak zarządzać szczegółowymi uprawnieniami OAuth.

Automatyczne wymaganie uprawnień do niezbędnych zakresów

Jeśli przepływ wykonania 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 przepływów, które zależą od konkretnych zakresów.
• requireAllScopes(authMode): użyj tej metody, jeśli przepływ wykonania zależy od wszystkich zakresów projektu.

Przykład

Poniższy przykład pokazuje, jak wywołać requireScopes() i requireAllScopes(). Skrypt używa 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 pobierać stan uprawnień użytkowników i projektować niestandardowe funkcje. Możesz na przykład wyłączyć funkcje, które wymagają brakujących uprawnień, lub wyświetlić okno z wyjaśnieniem tego wymagania. Poniższe metody pobierają obiekt z informacjami o uprawnieniach użytkownika, który zawiera zakresy, na które użytkownik wyraził zgodę, oraz adres URL umożliwiający wysłanie prośby o brakujące zakresy:

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

Aby uzyskać szczegółowe informacje o uprawnieniach z obiektu informacji o autoryzacji, takie jak lista autoryzowanych zakresów i adres URL do wysyłania próśb o brakujące uprawnienia, użyj metod z AuthorizationInfoklasy.

Przykład

Poniższy przykład pokazuje, jak używać symbolu getAuthorizationInfo(), aby pomijać funkcje, w przypadku których użytkownicy nie przyznali wymaganych zakresów. Dzięki temu pozostała część przepływu wykonania 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("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 działają automatycznie, a użytkownicy mogą nie być obecni, aby przyznać uprawnienia. Zalecamy użycie requireScopes(authMode, oAuthScopes) przed zainstalowaniem wyzwalacza. Wyświetla użytkownikowi prośbę o przyznanie brakujących uprawnień i nie pozwala na 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, musi przejść weryfikację klienta OAuth, zanim będzie można go publicznie opublikować jako aplikację internetową lub dodatek. 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 zasadom, które pomagają chronić dane użytkownika. Jeśli publikujesz aplikację, która korzysta z zakresów z ograniczeniami, musi ona spełniać wszystkie wymagania.

Przed publikacją 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, w miarę możliwości unikaj używania zakresów z ograniczeniami. W przypadku aplikacji niepublicznych możesz swobodnie używać ograniczonych zakresów.