Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

部署至正式環境

本指南可協助您為 Data Manager API 實際部署作業選擇及設定適當的驗證方法。

選擇部署情境

請根據應用程式架構和部署環境，選取相應的驗證方法：

Google Cloud 中的工作負載：對於在 Compute Engine、Cloud Run、Cloud Functions 或 GKE 上執行的自動化工作負載 (例如 ETL 管道、批次作業或後端服務)，請使用應用程式預設憑證 (ADC)，並附加服務帳戶或 Workload Identity Federation for GKE。
Google Cloud 以外的工作負載：對於在地端部署或其他雲端服務供應商上執行的自動化工作負載，請搭配使用應用程式預設憑證 (ADC) 與 Workload Identity Federation 或服務帳戶金鑰。
代表使用者採取行動：如果是管理外部使用者帳戶的第三方平台和多租戶應用程式 (例如在您平台上註冊的廣告主)，請使用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 專案中，授予服務帳戶「服務使用情形消費者」角色 (roles/serviceusage.serviceUsageConsumer)。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"
```
目的地帳戶存取權：授予服務帳戶目的地帳戶的必要存取權。如需逐步操作說明，請參閱「設定帳戶存取權」。

Google Cloud 以外的工作負載

在內部部署資料中心或其他雲端供應商執行程式碼時，請選擇下列其中一種驗證機制：

工作負載身分聯盟 (建議使用)：設定工作負載身分聯盟，讓應用程式交換外部身分提供者的憑證，取得短效期的 Google Cloud 憑證，不必管理服務帳戶金鑰。產生憑證設定檔，並使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數提供給 ADC。
服務帳戶金鑰 (備援)：如果無法使用 Workload Identity 聯盟，請建立服務帳戶金鑰，並透過 GOOGLE_APPLICATION_CREDENTIALS 環境變數提供給 ADC。

注意： 服務帳戶金鑰是長期有效的憑證，如果外洩或管理不當，就會帶來安全風險。請遵循管理服務帳戶金鑰的最佳做法，將金鑰儲存在安全的密鑰管理工具中、限制檔案權限，並定期輪替金鑰。

設定`GOOGLE_APPLICATION_CREDENTIALS`

將 GOOGLE_APPLICATION_CREDENTIALS 環境變數設為工作負載身分聯盟憑證設定檔或服務帳戶金鑰檔案的絕對路徑，這樣一來，用戶端程式庫就能使用 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 專案中，授予服務帳戶「服務使用情形消費者」角色 (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 同意畫面，並使用 access_type=offline 和 prompt=consent 要求 https://www.googleapis.com/auth/datamanager 範圍。伺服器會將授權碼換成存取權杖和 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)

小茹

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 應用程式驗證

由於 https://www.googleapis.com/auth/datamanager 是敏感範圍，因此任何用於從外部 Google 帳戶取得使用者憑證的 Google Cloud 應用程式，都必須先通過 Google OAuth 驗證，才能投入正式環境：

開發：在 Google Cloud 控制台的「目標對象」頁面，將應用程式的發布狀態設為「測試中」時，只有指定的測試帳戶可以授權您的應用程式。
正式版：向外部使用者提供應用程式前，請將發布狀態設為「正式版」，並將應用程式送交驗證。

使用服務帳戶執行的工作負載不需要進行應用程式驗證。此外，內部應用程式等情境也有一些例外狀況。詳情請參閱「何時不需要驗證」。

替代做法：合作夥伴連結

如果貴機構是核准的資料合作夥伴，可以改用合作夥伴連結，不必管理每個使用者的 OAuth 權杖，即可持續擷取資料。

廣告主可透過合作夥伴連結，在 Google Ads、Display & Video 360 或 Google Ad Manager 使用者介面中，將帳戶連結至您的資料合作夥伴帳戶。建立連結後，應用程式會透過 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

小茹

完成 OAuth 應用程式驗證

替代做法：合作夥伴連結

正式環境最佳做法

部署至正式環境

設定`GOOGLE_APPLICATION_CREDENTIALS`