Uwierzytelnianie jako projekt Google Apps Script za pomocą kont usługi

Z tego przewodnika dowiesz się, jak uwierzytelniać się za pomocą konta usługi podczas wywoływania interfejsów API w Apps Script.

Konto usługi to specjalny rodzaj konta używanego przez aplikację, a nie przez osobę. Konta usługi możesz używać do uzyskiwania dostępu do danych lub wykonywania działań przez konto robota albo do uzyskiwania dostępu do danych w imieniu użytkowników Google Workspace lub Cloud Identity. Więcej informacji znajdziesz w artykule Konta usługi.

Omówienie uwierzytelniania w interfejsach Google Workspace API znajdziesz w artykule Tworzenie danych logowania.

Kiedy używać kont usługi w Apps Script

Domyślnie Apps Script używa danych logowania użytkownika skryptu do wywoływania interfejsów API. Jeśli wywołujesz interfejsy API Google za pomocą UrlFetchApp, możesz uzyskać token dostępu dla użytkownika skryptu, wywołując ScriptApp.getOAuthToken.

Jednak w niektórych przypadkach korzystanie z kont usługi ma kilka zalet w porównaniu z ScriptApp.getOAuthToken. Używaj uwierzytelniania za pomocą konta usługi z tych powodów:

• Lepsza wydajność dzięki interfejsom API i usługom Google Cloud: wiele interfejsów API Google Cloud jest przeznaczonych do uwierzytelniania kont usługi. Konta usługi mogą też zapewniać bardziej zintegrowany, niezawodny i bezpieczny sposób interakcji z większością interfejsów API.
• Oddzielne uprawnienia: konta usługi mają własne uprawnienia, niezależne od uprawnień użytkowników. Metoda uwierzytelnianiaScriptApp.getOAuthToken może zawieść, gdy udostępnisz projekt innym użytkownikom. Używając kont usług, udostępniaj skrypty i publikuj je jako dodatki do Google Workspace.
• Automatyczne skrypty i długotrwałe zadania: konta usługi umożliwiają uruchamianie automatycznych skryptów, przetwarzania wsadowego lub zadań w tle bez danych wejściowych użytkownika.
• Zwiększone bezpieczeństwo i zasada jak najmniejszych uprawnień: przyznawaj kontom usług określone uprawnienia, zapewniając dostęp tylko do potrzebnych im zasobów. Jest to zgodne z zasadą jak najmniejszych uprawnień, która zmniejsza ryzyko związane z bezpieczeństwem. Użycie ScriptApp.getOAuthToken często przyznaje skryptowi wszystkie uprawnienia użytkownika, co może być zbyt szerokie.
• Scentralizowane zarządzanie dostępem: konta usługi są zarządzane za pomocą usługi Identity and Access Management (IAM) w Google Cloud. IAM pomaga organizacjom korzystającym z Google Workspace zarządzać dostępem do uwierzytelnionych usług w projektach Apps Script.

Wymagania wstępne

• Projekt Google Cloud.
• W projekcie w chmurze włącz interfejsy API, w których chcesz uwierzytelniać się za pomocą danych logowania konta usługi.
• Aby przypisywać role do kont usługi, musisz mieć uprawnienia superadministratora.

Tworzenie konta usługi

W projekcie w chmurze utwórz konto usługi:

Konsola Google Cloud

1. W konsoli Google Cloud otwórz Menu  > Uprawnienia i administracja > Konta usługi.

   Otwórz stronę Konta usługi

2. Kliknij Utwórz konto usługi.
3. Wpisz szczegóły konta usługi, a następnie kliknij Utwórz i kontynuuj.
   Uwaga: domyślnie Google tworzy unikalny identyfikator konta usługi. Jeśli chcesz zmienić identyfikator, zmodyfikuj go w polu identyfikatora konta usługi.
4. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.
5. Kliknij Dalej.
6. Opcjonalnie: wpisz użytkowników lub grupy, które mogą zarządzać tym kontem usługi i wykonywać na nim działania. Więcej informacji znajdziesz w artykule Zarządzanie przyjmowaniem tożsamości konta usługi.
7. Kliknij Gotowe. Zanotuj adres e-mail konta usługi.

interfejs wiersza poleceń gcloud

1. Utwórz konto usługi:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Opcjonalnie: przypisz role do konta usługi, aby przyznać dostęp do zasobów projektu Google Cloud. Więcej informacji znajdziesz w artykule Przyznawanie, zmienianie i odbieranie uprawnień dostępu do zasobów.

Przypisywanie roli do konta usługi

Do konta usługi musisz przypisać gotową lub niestandardową rolę za pomocą konta superadministratora.

1. W konsoli administracyjnej Google otwórz Menu> Konto > Role administratora.

   Otwórz Role administratora

2. Wskaż rolę, którą chcesz przypisać, a następnie kliknij Przypisz administratora.

3. Kliknij Przypisz konta usługi.

4. Wpisz adres e-mail konta usługi.

5. Kliknij Dodaj> Przypisz rolę.

Tworzenie danych logowania do konta usługi

Musisz uzyskać dane logowania w postaci pary kluczy publiczny/prywatny. Te dane logowania są używane przez kod do autoryzowania działań konta usługi w aplikacji.

Aby uzyskać dane logowania do konta usługi:

1. W konsoli Google Cloud otwórz Menu  > Uprawnienia i administracja > Konta usługi.

   Otwórz stronę Konta usługi

2. Wybierz konto usługi.
3. Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
4. Wybierz JSON, a następnie kliknij Utwórz.

   Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza. Informacje o tym, jak bezpiecznie przechowywać klucz, znajdziesz w artykule Zarządzanie kluczami konta usługi.

5. Kliknij Zamknij.

Skopiuj numer projektu w chmurze

1. W konsoli Google Cloud kliknij Menu  > Administracja > Ustawienia.

   Otwórz Ustawienia w obszarze Administracja

2. Skopiuj wartość w polu Numer projektu.

Konfigurowanie uwierzytelniania konta usługi w projekcie Apps Script

W tej sekcji wyjaśniono, jak dodać dane logowania konta usługi z projektu w chmurze do projektu Apps Script.

Ustawianie projektu w chmurze w Apps Script

1. Aby otworzyć lub utworzyć projekt, otwórz Apps Script:

   
   Otwórz Apps Script

2. W projekcie Apps Script kliknij Ustawienia projektu .

3. W sekcji Projekt Google Cloud kliknij Zmień projekt.

4. W sekcji Numer projektu Google Cloud wklej numer projektu w chmurze.

5. Kliknij Ustaw projekt.

Zapisywanie danych logowania jako właściwości skryptu

Bezpiecznie przechowuj dane logowania konta usługi, zapisując je jako właściwość skryptu w ustawieniach projektu Apps Script:

1. Skopiuj zawartość pliku JSON konta usługi (credentials.json) utworzonego w poprzedniej sekcji.
2. W projekcie Apps Script otwórz Ustawienia projektu .
3. Na stronie Ustawienia projektu otwórz Właściwości skryptu i kliknij Dodaj właściwość skryptu, a następnie wpisz te wartości:
   • W polu Property (Usługa) wpisz SERVICE_ACCOUNT_KEY.
   • W polu Wartość wklej zawartość pliku klucza JSON.
4. Kliknij Zapisz właściwości skryptu.

Dodawanie biblioteki OAuth2

Aby obsługiwać proces uwierzytelniania OAuth2, użyj biblioteki Apps Script apps-script-oauth2.

Aby dodać bibliotekę do projektu Apps Script:

1. W edytorze skryptów Apps Script po lewej stronie obok Biblioteki kliknij Dodaj bibliotekę .
2. W polu Identyfikator skryptu wpisz 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. Kliknij Wyszukaj.
4. Wybierz najnowszą wersję, a potem kliknij Dodaj.

Wywoływanie interfejsu API za pomocą danych logowania konta usługi

Aby użyć danych logowania konta usługi z projektu Apps Script, możesz użyć tej funkcji: getServiceAccountService()

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

Zastąp SCOPE zakresem autoryzacji, który jest potrzebny do wywołania interfejsu API. Skrypt używa danych logowania konta usługi zapisanych jako właściwość skryptu SERVICE_ACCOUNT_KEY w poprzednim kroku.

Możesz następnie użyć tych danych logowania do wywołania interfejsu API, jak pokazano w poniższym przykładzie z usługą UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

Zastąp API_URL punktem końcowym HTTP, do którego wysyłasz wywołanie.

Powiązane artykuły

• Tworzenie danych logowania
• Uwierzytelnianie jako komunikator Google Chat