Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

本番環境にデプロイする

このガイドでは、Data Manager API の本番環境デプロイに適した認証方法を選択して構成する方法について説明します。

デプロイシナリオを選択する

アプリケーションアーキテクチャとデプロイ環境に一致する認証方法を選択します。

Google Cloud のワークロード: Compute Engine、Cloud Run、Cloud Functions、GKE で実行される自動化されたワークロード（ETL パイプライン、バッチジョブ、バックエンドサービスなど）の場合は、関連付けられたサービスアカウントまたは Workload Identity Federation for GKE を使用してアプリケーションのデフォルト認証情報（ADC）を使用します。
Google Cloud の外部のワークロード: オンプレミスまたは他のクラウドプロバイダで実行される自動化されたワークロードの場合は、 Workload Identity 連携またはサービスアカウントキーを使用してアプリケーションのデフォルト認証情報（ADC）を使用します。
ユーザーに代わって操作する: 外部ユーザー（プラットフォームに登録した広告主など）のアカウントを管理するサードパーティプラットフォームとマルチテナントアプリケーションの場合は、ユーザーごとの更新トークンを使用する OAuth 2.0 ウェブサーバーフローを使用します。承認済みのデータパートナーの場合は、パートナーリンクを使用します。

Google Cloud 認証に関する一般的なガイダンスについては、 Google Cloud 認証の決定木をご覧ください。

Google Cloud のワークロード

Google Cloud で実行する場合は、サービスアカウントをコンピューティングリソースに直接接続するか、 Workload Identity Federation for GKEを構成します。クライアントライブラリは ADC を使用して、認証情報ファイルや環境変数を必要とせずに、サービスアカウントの有効期間の短い認証情報を自動的に取得します。

Compute Engine

仮想マシンインスタンスを作成するときに、サービスアカウントと Data Manager API スコープを指定して、インスタンスメタデータサーバーから返されるアクセストークンに必要な承認を含めます。

gcloud compute instances create INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

既存のインスタンスのスコープまたはサービスアカウントを更新するには、インスタンスを停止し、set-service-account で構成を更新して、インスタンスを再起動します。

gcloud compute instances stop INSTANCE_NAME

gcloud compute instances set-service-account \
  INSTANCE_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform"

gcloud compute instances start INSTANCE_NAME

Cloud Run

サービスをデプロイするときにサービスアカウントを指定します。

gcloud run deploy SERVICE_NAME \
  --image="IMAGE_URL" \
  --service-account="SERVICE_ACCOUNT_EMAIL"

Cloud Functions

関数をデプロイするときにサービスアカウントを指定します。

gcloud functions deploy FUNCTION_NAME \
  --service-account="SERVICE_ACCOUNT_EMAIL" \
  --runtime="RUNTIME" \
  --trigger-http

GKE

クラスタで Workload Identity Federation for GKE を有効にします。

Kubernetes サービスアカウント（KSA）を Google サービスアカウント（GSA）にバインドします。

# Define the Kubernetes service account member:
KUBERNETES_MEMBER="serviceAccount:PROJECT_ID.svc.id.goog[KUBERNETES_NAMESPACE/KUBERNETES_SA_NAME]"

# Grant the Workload Identity User role to the Kubernetes service account:
gcloud iam service-accounts add-iam-policy-binding \
  SERVICE_ACCOUNT_EMAIL \
  --role="roles/iam.workloadIdentityUser" \
  --member="${KUBERNETES_MEMBER}"

Google サービスアカウントのメールアドレスを使用して Kubernetes サービスアカウントにアノテーションを付けます。

kubectl annotate serviceaccount KUBERNETES_SA_NAME \
  --namespace="KUBERNETES_NAMESPACE" \
  iam.gke.io/gcp-service-account="SERVICE_ACCOUNT_EMAIL"

Pod 仕様で Kubernetes サービスアカウントを指定します。

apiVersion: v1
kind: Pod
metadata:
  name: data-manager-worker
spec:
  serviceAccountName: KUBERNETES_SA_NAME
  containers:
  - name: worker
    image: IMAGE_URL

IAM とアカウントアクセスを確認する

本番環境アプリケーションをデプロイする前に、サービスアカウントに必要な権限が付与されていることを確認します。

Google Cloud IAM 権限: Data Manager API が有効になっている Google Cloud プロジェクトで、サービスアカウントに Service Usage Consumer ロール（roles/serviceusage.serviceUsageConsumer）を付与します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
移行先のアカウントへのアクセス: サービスアカウントに必要なアクセス権を移行先のアカウントに付与します。手順については、アカウントアクセスを設定するをご覧ください。

Google Cloud の外部のワークロード

オンプレミスデータセンターまたは他のクラウドプロバイダでコードを実行する場合は、次のいずれかの認証メカニズムを選択します。

Workload Identity 連携（推奨）: サービスアカウントキーを管理せずに、外部 ID プロバイダの認証情報を有効期間の短い Google Cloud 認証情報と交換できるように、Workload Identity 連携を構成します。認証情報の構成ファイルを生成し、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用して ADC に提供します。
サービスアカウントキー（フォールバック）: Workload Identity 連携が使用できない場合は、サービスアカウントキーを作成し、 GOOGLE_APPLICATION_CREDENTIALS環境変数を使用して ADC に提供します。

**注意:** サービスアカウントキーは有効期間が長い認証情報であり、漏洩または誤って管理されるとセキュリティリスクが発生します。サービスアカウントキーの管理に関するベストプラクティスに従い、キーを安全な Secret Manager に保存し、ファイル権限を制限して、キーを定期的にローテーションします。

`GOOGLE_APPLICATION_CREDENTIALS` を設定する

GOOGLE_APPLICATION_CREDENTIALS 環境変数を Workload Identity 連携認証情報の構成ファイルまたはサービスアカウントキーファイルの絶対パスに設定すると、クライアントライブラリは ADC を使用して認証情報を自動的に検出できます。

Linux / macOS

シェルプロファイルまたはデプロイスクリプトで環境変数を設定します。

export GOOGLE_APPLICATION_CREDENTIALS=\
  "/path/to/credentials.json"

Windows（PowerShell）

PowerShell で環境変数を設定します。

$env:GOOGLE_APPLICATION_CREDENTIALS = `
  "C:\path\to\credentials.json"

Docker / コンテナ

認証情報ファイルをコンテナにマウントして、環境変数を設定します。

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

または、実行時に環境変数を渡します。

HOST_CREDS="/host/path/credentials.json"
docker run -e GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json" \
  -v "${HOST_CREDS}:/secrets/credentials.json:ro" \
  IMAGE_NAME

Kubernetes

認証情報を Secret としてマウントし、Pod の環境で参照します。

apiVersion: v1
kind: Pod
metadata:
  name: data-manager-worker
spec:
  containers:
  - name: worker
    image: IMAGE_URL
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: "/etc/secrets/google/credentials.json"
    volumeMounts:
    - name: credentials-volume
      mountPath: "/etc/secrets/google"
      readOnly: true
  volumes:
  - name: credentials-volume
    secret:
      secretName: data-manager-credentials

REST リクエストと curl リクエストを認証する

自動化されたパイプラインがクライアントライブラリを使用するのではなく、curl を使用して未加工の HTTP リクエストを行う場合は、Google Cloud CLI を使用して、トークンを手動で署名せずに、非対話型で認証してアクセストークンを管理します。

環境で構成された認証情報ファイルを使用して Google Cloud CLI を承認します。
```
gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"
```
生成されたアクセストークンを API リクエストの Authorization ヘッダーに渡します。
```
curl -X POST "https://datamanager.googleapis.com/v1/..." \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d @request.json
```
Google Cloud CLI は、アクセストークンを自動的にキャッシュに保存し、有効期限が切れる前に更新します。

IAM とアカウントアクセスを確認する

本番環境アプリケーションをデプロイする前に、サービスアカウントに必要な権限が付与されていることを確認します。

Google Cloud IAM 権限: Data Manager API が有効になっている Google Cloud プロジェクトで、サービスアカウントに Service Usage Consumer ロール（roles/serviceusage.serviceUsageConsumer）を付与します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
移行先のアカウントへのアクセス: サービスアカウントに必要なアクセス権を移行先のアカウントに付与します。手順については、アカウントアクセスを設定するをご覧ください。

ユーザーに代わって操作する

マーケティングプラットフォームや代理店などのサードパーティプラットフォームでは、サービスに登録した複数の広告主の代わりに API リクエストを送信する必要があることがよくあります。

このアーキテクチャでは、アプリケーションのデフォルト認証情報を使用する代わりに、 OAuth 2.0 ウェブサーバーフローを使用して、各広告主からオフラインアクセスでユーザー認証情報を取得します。次に、これらの認証情報を使用して、リクエストを管理する広告主アカウントに基づいて、実行時にクライアントライブラリを構成します。

OAuth 2.0 ウェブフローを実装する

マルチテナントアプリケーションのユーザー委任を設定する方法は次のとおりです。

オフラインアクセスをリクエストする: ユーザーを Google の OAuth 同意画面に誘導し、 https://www.googleapis.com/auth/datamanager スコープを access_type=offline と prompt=consent を使用してリクエストします。サーバーは、認証コードをアクセストークンと refresh_token に交換します。手順ガイドについては、ウェブサーバーアプリケーションに OAuth 2.0 を使用するをご覧ください。
認証情報を安全に保存する: 各ユーザーの更新トークンを、プラットフォーム上のアカウントに関連付けられた暗号化された認証情報ストアに安全に保存します。

実行時にクライアントライブラリを初期化する: 特定のユーザーに代わって API リクエストを送信する場合は、ユーザー用に保存した更新トークンとアプリのクライアント ID とクライアントシークレットからユーザー認証情報を作成し、クライアントの初期化時に渡します。

.NET

using Google.Ads.DataManager.V1;
using Google.Apis.Auth.OAuth2;

UserCredential credential = CredentialFactory.FromJsonParameters<UserCredential>(
    new JsonCredentialParameters
    {
        Type = JsonCredentialParameters.AuthorizedUserCredentialType,
        ClientId = clientId,
        ClientSecret = clientSecret,
        RefreshToken = refreshToken
    });

IngestionServiceClient client = new IngestionServiceClientBuilder
{
    Credential = credential
}.Build();

Go

import (
    "context"

    datamanager "cloud.google.com/go/datamanager/apiv1"
    "golang.org/x/oauth2"
    "golang.org/x/oauth2/google"
    "google.golang.org/api/option"
)

cfg := &oauth2.Config{
    ClientID:     clientID,
    ClientSecret: clientSecret,
    Endpoint:     google.Endpoint,
}
ts := cfg.TokenSource(ctx, &oauth2.Token{RefreshToken: refreshToken})

client, err := datamanager.NewIngestionClient(ctx, option.WithTokenSource(ts))

Java

import com.google.ads.datamanager.v1.IngestionServiceClient;
import com.google.ads.datamanager.v1.IngestionServiceSettings;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.UserCredentials;

UserCredentials credentials =
    UserCredentials.newBuilder()
        .setClientId(clientId)
        .setClientSecret(clientSecret)
        .setRefreshToken(refreshToken)
        .build();

IngestionServiceSettings settings =
    IngestionServiceSettings.newBuilder()
        .setCredentialsProvider(FixedCredentialsProvider.create(credentials))
        .build();

try (IngestionServiceClient client = IngestionServiceClient.create(settings)) {
  // Send API requests using client...
}

Node.js

const {IngestionServiceClient} = require('@google-ads/datamanager').v1;
const {UserRefreshClient} = require('google-auth-library');

const authClient = new UserRefreshClient({
  clientId,
  clientSecret,
  refreshToken,
});

const client = new IngestionServiceClient({authClient});

PHP

use Google\Ads\DataManager\V1\Client\IngestionServiceClient;
use Google\Auth\Credentials\UserRefreshCredentials;

$credentials = new UserRefreshCredentials(
    null,
    [
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'refresh_token' => $refreshToken,
    ]
);

$client = new IngestionServiceClient(['credentials' => $credentials]);

Python

from google.ads.datamanager_v1 import IngestionServiceClient
from google.oauth2.credentials import Credentials

credentials = Credentials.from_authorized_user_info({
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
})

client = IngestionServiceClient(credentials=credentials)

Ruby

require "google/ads/data_manager/v1"
require "googleauth"

credentials = Google::Auth::UserRefreshCredentials.new(
  client_id: client_id,
  client_secret: client_secret,
  refresh_token: refresh_token
)

client = Google::Ads::DataManager::V1::IngestionService::Client.new do |config|
  config.credentials = credentials
end

OAuth アプリの確認を完了する

Data Manager API スコープは機密性の高いスコープであるため、外部の Google アカウントからユーザー認証情報を取得するために使用される Google クラウドアプリは、本番環境に移行する前にGoogle OAuth の検証を受ける必要があります。

開発: アプリの公開ステータスが Google Cloud コンソールの [オーディエンス] ページで [**テスト中**] に設定されている間は、指定されたテストアカウントのみがアプリケーションを承認できます。
本番環境: アプリケーションを外部ユーザーに公開する前に、公開ステータスを [本番環境] に設定して、 [アプリを検証用に送信]します。

サービスアカウントを使用して実行されるワークロードでは、アプリの確認は必要ありません。また、内部アプリケーションなどのシナリオにはいくつかの例外があります。詳細については、検証が不要な場合をご覧ください。

代替方法: パートナーリンク

組織が承認済みのデータパートナーである場合は、継続的なデータの取り込みのためにユーザーごとの OAuth トークンを管理する代わりに、パートナーリンクを使用できます。

パートナーリンクを使用すると、広告主は Google 広告、ディスプレイ＆ビデオ 360、Google アドマネージャーの UI でアカウントをデータパートナーアカウントに接続できます。リンクが確立されると、アプリケーションは ADC を介して独自のサービスアカウント認証情報を使用して取り込みリクエストを送信するため、有効期間の長いユーザー更新トークンを保存して維持する必要がなくなります。

本番環境のベストプラクティス

本番環境に移行する際は、次の運用上の重要な考慮事項を確認してください。

エラー処理と検証: API が高速フェイルモデルを使用してリクエストを検証し、構造化されたエラーの詳細を返す方法を理解します。
再試行戦略: 一時的なサーバーエラーに対して、ジッター付きの指数バックオフを実装します。
バッチ処理と同時実行: レコードをバッチ処理し、制限内でリクエストを同時に送信することで、スループットを最大化します。
診断とモニタリング: レスポンスリクエスト ID をキャプチャし、診断サービスにクエリを実行して、非同期処理を確認し、警告とエラーを検出します。

本番環境にデプロイする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

デプロイ シナリオを選択する

Google Cloud のワークロード

Compute Engine

Cloud Run

Cloud Functions

GKE

IAM とアカウント アクセスを確認する

Google Cloud の外部のワークロード

GOOGLE_APPLICATION_CREDENTIALS を設定する

Linux / macOS

Windows（PowerShell）

Docker / コンテナ

Kubernetes

REST リクエストと curl リクエストを認証する

IAM とアカウント アクセスを確認する

ユーザーに代わって操作する

OAuth 2.0 ウェブフローを実装する

.NET

Go

Java

Node.js

PHP

Python

Ruby

OAuth アプリの確認を完了する

代替方法: パートナー リンク

本番環境のベスト プラクティス

本番環境にデプロイする

デプロイシナリオを選択する

IAM とアカウントアクセスを確認する

`GOOGLE_APPLICATION_CREDENTIALS` を設定する

IAM とアカウントアクセスを確認する

代替方法: パートナーリンク

本番環境のベストプラクティス