REST を使用して認証する

このページでは、Google API に REST リクエストを送信するときの認証方法について説明します。

Google クライアント ライブラリを使用する際の認証方法については、クライアント ライブラリを使用した認証をご覧ください。

準備

このページのサンプルを実行するには、次の手順を完了させます。

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

gcloud CLI を使用しない場合は、この手順をスキップして、メタデータ サーバーを使用してトークンを返すことができます。

認証情報の種類

REST 呼び出しの認証に使用できる認証情報は次のとおりです。

• gcloud CLI 認証情報

  これは、ローカル開発環境で REST メソッドに認証情報を渡すための最も簡単で安全な方法です。呼び出すメソッドに対して必要な Identity and Access Management（IAM）権限がユーザー アカウントに付与されている場合は、この方法をおすすめします。

  gcloud 認証情報は、gcloud CLI を使用して ADC に指定する認証情報とは異なります。詳細については、gcloud CLI 認証構成と ADC 構成をご覧ください。

• アプリケーションのデフォルト認証情報（ADC）に指定する認証情報。

  ADC は、コードが実行されているリソース（Compute Engine 仮想マシンなど）から認証情報を検索します。このため、本番環境での REST 呼び出しの認証方法としては、これを推奨します。ローカル開発環境での認証に ADC を使用することも可能です。その場合は、gcloud CLI を使用して、認証情報を含むファイルをローカル ファイル システム内に作成します。

• サービス アカウントの権限を借用して指定する認証情報。

  この方法では追加の設定が必要です。別のサービス アカウント用の有効期間が短い認証情報を取得するために既存の認証情報を使用する場合（例: サービス アカウントを使ってローカルでテストを行う場合や、一時的な権限昇格をリクエストする場合）は、この方法を使用します。

• メタデータ サーバーから返される認証情報。

  この方法は、メタデータ サーバーにアクセスできる環境でのみ機能します。メタデータ サーバーから返される認証情報は、関連付けられているサービス アカウントを使用してアプリケーションのデフォルト認証情報により検出される認証情報と同じですが、メタデータ サーバーにアクセス トークンを明示的にリクエストすると、REST リクエストで指定できます。メタデータ サーバーに認証情報をクエリするには、HTTP GET リクエストが必要です。この方法では、Google Cloud CLI を使用しません。

gcloud CLI 認証情報

以下の例を実行するには、プロジェクトに対する resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

1. ユーザーの認証情報から生成されたアクセス トークンを挿入するには、gcloud auth print-access-token コマンドを使用します。

   次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

   リクエストのデータを使用する前に、次のように置き換えます。

   • PROJECT_ID: Google Cloud プロジェクトの ID または名前。

   リクエストを送信するには、次のいずれかのオプションを選択します。

   curl

   次のコマンドを実行します。

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   次のコマンドを実行します。

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   プロジェクトの詳細が返されます。

割り当てプロジェクトが必要な API の場合は、リクエストのために明示的に設定する必要があります。詳細については、このページの REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。

アプリケーションのデフォルト認証情報

以下の例を実行するには、ADC に指定する認証情報に関連付けられているプリンシパルに、プロジェクトに対する resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

1. ADC に認証情報を指定します。

   Google Cloud コンピューティング リソースで実行する場合は、ADC にユーザー認証情報を指定しないでください。代わりに、関連付けられているサービス アカウントを使用して認証情報を指定します。詳細については、サービス アカウントの関連付けをサポートする Google Cloud サービスをご覧ください。

2. gcloud auth application-default print-access-tokenコマンドを使用して、ADC から返されたアクセス トークンを REST リクエストに挿入します。

   次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

   リクエストのデータを使用する前に、次のように置き換えます。

   • PROJECT_ID: Google Cloud プロジェクトの ID または名前。

   リクエストを送信するには、次のいずれかのオプションを選択します。

   curl

   次のコマンドを実行します。

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   次のコマンドを実行します。

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   プロジェクトの詳細が返されます。

   この API が対応していないエンドユーザー認証情報に関するエラー メッセージがリクエストから返された場合は、このページの REST リクエストを使用して割り当てプロジェクトを設定するをご覧ください。

権限の借用元であるサービス アカウント

サービス アカウントの権限の借用について詳しくは、サービス アカウントの権限借用を使用するをご覧ください。

1. 必要な権限を確認します。

   • ユーザー アカウントには、権限の借用元であるサービス アカウント（権限を保持するサービス アカウント）に対する iam.serviceAccounts.getAccessToken 権限が必要です。iam.serviceAccounts.getAccessToken 権限は、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）に含まれています。プロジェクトに対するオーナーロール（roles/owner）がある場合でも、この権限が必要になります。詳細については、必要な権限の設定をご覧ください。

   • 次の例では、権限の借用元であるサービス アカウントに、プロジェクトに対する resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

2. 権限を保持するサービス アカウント（権限の借用元であるサービス アカウント）を特定または作成します。

   権限を保持するサービス アカウントには、API メソッドの呼び出しに必要な権限が付与されている必要があります。

3. --impersonate-service-account フラグを指定して gcloud auth print-access-token コマンドを使用し、権限を保持するサービス アカウントのアクセス トークンを REST リクエストに挿入します。

   次の例では、指定したプロジェクトの詳細を取得します。どの REST リクエストに対しても、同じパターンを使用できます。

   この例を実行するには、権限の借用元であるサービス アカウントに resourcemanager.projects.get 権限が必要です。resourcemanager.projects.get 権限は、閲覧者のロール（roles/browser）など、さまざまなロールに含まれています。

   次の項目を置き換えます。

   • PRIV_SA: 権限を保持するサービス アカウントのメールアドレス。例: [email protected]

   • PROJECT_ID: Google Cloud プロジェクトの ID または名前。

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

メタデータ サーバー

メタデータ サーバーからアクセス トークンを取得するには、メタデータ サーバーにアクセスできるサービスのいずれかを使用して REST 呼び出しを行う必要があります。

• Compute Engine
• App Engine スタンダード環境
• App Engine フレキシブル環境
• Cloud Run functions
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

curl などのコマンドライン ツールを使用してアクセス トークンを取得し、REST リクエストに挿入します。

1. メタデータ サーバーに対してクエリを行い、アクセス トークンを取得します。

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   このリクエストにより、次の例に似たレスポンスが返されます。

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. アクセス トークンを REST リクエストに挿入して、次の項目を置き換えます。

   • ACCESS_TOKEN: 前の手順で返されたアクセス トークン。
   • PROJECT_ID: Google Cloud プロジェクトの ID または名前。

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

REST リクエストで割り当てプロジェクトを設定する

ユーザー認証情報を使用して API を呼び出す場合、使用量に応じて課金され、割り当ての追跡に使用されるプロジェクを設定する必要があります。API 呼び出しでユーザー認証情報に対応していないことや、割り当てプロジェクトが設定されていないことを通知するエラー メッセージが返された場合は、リクエストのために割り当てプロジェクトを明示的に設定する必要があります。割り当てプロジェクトを設定するには、リクエストに x-goog-user-project ヘッダーを含めます。

この問題が発生した場合は、ユーザー認証情報が機能しないをご覧ください。

プロジェクトを請求先プロジェクトとして指定するには、serviceusage.services.use IAM 権限が必要です。serviceusage.services.use 権限は、Service Usage ユーザーの IAM ロールに含まれています。プロジェクトに対する serviceusage.services.use 権限がない場合は、セキュリティ管理者か、プロジェクトの Service Usage ユーザーのロールを付与できるプロジェクト オーナーに連絡します。

次の例では、Cloud Translation API を使用して「hello」という単語をスペイン語に翻訳します。Cloud Translation API は、割り当てプロジェクトの指定が必要な API です。サンプルを実行するには、リクエスト本文を含む request.json という名前のファイルを作成します。

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: 課金プロジェクトとして使用する Google Cloud プロジェクトの ID または名前。

リクエストの本文（JSON）:

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

翻訳リクエストは成功します。x-goog-user-project ヘッダーのないコマンドを使用してみると、課金プロジェクトを指定しないとどうなるか確認できます。

次のステップ

• 認証の概要を確認する。
• クライアント ライブラリで認証する方法を学習する。
• gcloud CLI 認証構成と ADC 構成について理解する。