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

本番環境にデプロイする

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

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

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

Google Cloud のワークロード: Compute Engine、Cloud Run、Cloud Functions、GKE で実行される自動ワークロード（ETL パイプライン、バッチジョブ、バックエンドサービスなど）の場合は、サービスアカウントが関連付けられたアプリケーションのデフォルト認証情報（ADC）または Workload Identity Federation for GKE を使用します。
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 コンシューマーロール（roles/serviceusage.serviceUsageConsumer）を付与します。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
移行先のアカウントへのアクセス: 移行先のアカウントに必要なアクセス権をサービスアカウントに付与します。詳しい手順については、アカウントアクセスを設定するをご覧ください。

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

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

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

注意: サービスアカウントキーは有効期間が長い認証情報であり、漏洩や不適切な管理によりセキュリティリスクが発生する可能性があります。サービスアカウントキーの管理に関するベストプラクティスに従い、安全なシークレットマネージャーにキーを保存し、ファイルへのアクセス許可を制限して、キーを定期的にローテーションします。

`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 コンシューマーロール（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 ウェブフローを実装する

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

オフラインアクセスをリクエストする: access_type=offline と prompt=consent を使用して https://www.googleapis.com/auth/datamanager スコープをリクエストする Google の OAuth 同意画面にユーザーをリダイレクトします。サーバーは認証コードをアクセストークンと 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 Cloud アプリは、本番環境に移行する前に 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 アプリの確認を完了する

代替: パートナー リンク

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

本番環境にデプロイする

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

`GOOGLE_APPLICATION_CREDENTIALS` を設定

代替: パートナーリンク

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