サービスアカウントを使用して Apps Script プロジェクトとして認証する

このガイドでは、Apps Script で API を呼び出すときにサービスアカウントで認証する方法について説明します。

サービスアカウントは、ユーザーではなく、アプリケーションで使用される特別な種類のアカウントです。サービスアカウントを使用すると、ロボットアカウントでデータにアクセスしたり、アクションを実行したり、Google Workspace または Cloud Identity ユーザーに代わってデータにアクセスしたりできます。詳細については、サービスアカウントについてをご覧ください。

Google Workspace API の認証の概要については、アクセス認証情報を作成するをご覧ください。

Apps Script でサービスアカウントを使用する場合

ScriptApp.getOAuthToken() などの他の認証方法ではなく、サービスアカウント認証の使用を検討する理由をいくつか紹介します。

Google Cloud APIs とサービスによるパフォーマンスの向上: 多くの Google Cloud APIs は、サービスアカウント認証用に設計されています。サービスアカウントは、ほとんどの API とのやり取りをより統合された信頼性の高い安全な方法で提供することもできます。
分離された権限: サービスアカウントには、ユーザーとは別の独自の権限があります。Apps Script プロジェクトを他のユーザーと共有すると、認証方法 ScriptApp.getOAuthToken() が失敗することがあります。サービスアカウントを使用すると、スクリプトを共有して Google Workspace アドオンとして公開できます。
自動化されたスクリプトと長時間実行タスク: サービスアカウントを使用すると、ユーザー入力なしで自動化されたスクリプト、バッチプロセス、バックグラウンドタスクを実行できます。
セキュリティの強化と最小権限の原則: サービスアカウントに特定の権限を付与し、必要なリソースにのみアクセスできるようにします。これは、セキュリティリスクを軽減する最小権限の原則に従っています。ScriptApp.getOAuthToken() を使用すると、スクリプトにすべてのユーザー権限が付与されることが多く、権限の範囲が広すぎる可能性があります。
一元化されたアクセス管理: サービスアカウントは、Google Cloud の Identity and Access Management（IAM）を使用して管理されます。IAM を使用すると、Google Workspace 組織は Apps Script プロジェクト内の認証済みサービスへのアクセスを管理できます。

前提条件

Google Cloud プロジェクト。
Cloud プロジェクトで、サービスアカウントの認証情報を使用して認証する API を有効にします。
サービスアカウントにロールを割り当てるには、特権管理者の権限が必要です。

サービスアカウントを作成する

Cloud プロジェクトで、サービスアカウントを作成します。

Google Cloud コンソール

Google Cloud コンソールで、メニュー > [IAM と管理] > [サービスアカウント] に移動します。
[サービスアカウント] に移動
[サービスアカウントを作成] をクリックします。
サービスアカウントの詳細を入力し、[作成して続行] をクリックします。
注: デフォルトでは、Google は一意のサービスアカウント ID を作成します。ID を変更する場合は、サービスアカウント ID フィールドで ID を変更します。
省略可: サービスアカウントにロールを割り当て、Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。
[続行] をクリックします。
省略可: このサービスアカウントを管理してアクションを実行できるユーザーまたはグループを入力します。詳細については、サービスアカウントの権限借用を管理するをご覧ください。
[完了] をクリックします。サービスアカウントのメールアドレスをメモします。

gcloud CLI

サービスアカウントを作成します。

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

省略可: サービスアカウントにロールを割り当て、Google Cloud プロジェクトのリソースへのアクセス権を付与します。詳細については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

サービスアカウントにロールを割り当てる

サービスアカウントには、特権管理者アカウントによって、規定のロールまたはカスタムロールを割り当てる必要があります。

Google 管理コンソールで、メニューアイコン > [アカウント] > [管理者ロール] に移動します。

管理者ロールに移動する
割り当てるロールにカーソルを合わせ、[管理者を割り当て] をクリックします。
[サービスアカウントへの割り当て] をクリックします。
サービスアカウントのメールアドレスを入力します。
[追加> ロールを割り当てる] をクリックします。

サービスアカウントの認証情報を作成する

公開鍵/秘密鍵のペアの形式で認証情報を取得する必要があります。これらの認証情報は、アプリ内のサービスアカウントのアクションを承認するためにコードで使用されます。

サービスアカウントの認証情報を取得するには:

Google Cloud コンソールで、メニュー > [IAM と管理] > [サービスアカウント] に移動します。
[サービスアカウント] に移動
サービスアカウントを選択します。
[鍵] > [鍵を追加] > [新しい鍵を作成] をクリックします。
[JSON] を選択し、[作成] をクリックします。
新しい公開鍵と秘密鍵のペアが生成され、新しいファイルとしてパソコンにダウンロードされます。ダウンロードした JSON ファイルを作業ディレクトリに credentials.json として保存します。このファイルはこの鍵の唯一のコピーです。キーを安全に保存する方法については、サービスアカウントキーの管理をご覧ください。
[閉じる] をクリックします。

Cloud プロジェクト番号をコピーする

Google Cloud コンソールで、メニューアイコン > [IAM と管理] > [設定] に移動します。
[IAM と管理] の [設定] に移動
[プロジェクト番号] フィールドで、値をコピーします。

Apps Script プロジェクトでサービスアカウント認証を設定する

このセクションでは、Cloud プロジェクトのサービスアカウント認証情報を Apps Script プロジェクトに追加する方法について説明します。

Apps Script で Cloud プロジェクトを設定する

Apps Script に移動して、プロジェクトを開くか作成します。

Apps Script を開く
Apps Script プロジェクトで、[プロジェクトの設定] をクリックします。
[Google Cloud Platform（GCP）プロジェクト] で、[プロジェクトを変更] をクリックします。
[GCP プロジェクト番号] に、Google Cloud プロジェクト番号を貼り付けます。
[プロジェクトを設定] をクリックします。

認証情報をスクリプトプロパティとして保存する

サービスアカウントの認証情報を Apps Script プロジェクトの設定のスクリプトプロパティとして保存して、安全に保管します。

前のセクションで作成したサービスアカウントの JSON ファイル（credentials.json）の内容をコピーします。
Apps Script プロジェクトで、[プロジェクトの設定] に移動します。
[プロジェクト設定] ページで、[スクリプトプロパティ] に移動し、[スクリプトプロパティを追加] をクリックして、次のように入力します。
- [プロパティ] フィールドに「SERVICE_ACCOUNT_KEY」と入力します。
- [値] フィールドに、JSON キーファイルの内容を貼り付けます。
[スクリプトプロパティを保存] をクリックします。

OAuth2 ライブラリを追加する

OAuth2 認証フローを処理するには、Apps Script ライブラリ apps-script-oauth2 を使用します。

Apps Script プロジェクトにライブラリを追加するには:

Apps Script エディタの左側にある [ライブラリ] の横にある [ライブラリを追加] をクリックします。
[スクリプト ID] フィールドに「1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF」と入力します。
[Look up] をクリックします。
最新バージョンを選択し、[追加] をクリックします。

サービスアカウントの認証情報を使用して API を呼び出す

Apps Script プロジェクトのサービスアカウントの認証情報を使用するには、次の関数 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);
}

SCOPE は、API の呼び出しに必要な認可スコープに置き換えます。スクリプトは、前のステップで SERVICE_ACCOUNT_KEY スクリプトプロパティとして保存したサービスアカウントの認証情報を使用します。

これらの認証情報を使用して API を呼び出すことができます。次の例は、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;
}

API_URL は、呼び出す HTTP エンドポイントに置き換えます。

サービス アカウントを使用して Apps Script プロジェクトとして認証する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Apps Script でサービス アカウントを使用する場合

前提条件

サービス アカウントを作成する

Google Cloud コンソール

gcloud CLI

サービス アカウントにロールを割り当てる

サービス アカウントの認証情報を作成する