Triển khai vào giai đoạn sản xuất

Hướng dẫn này giúp bạn chọn và định cấu hình phương thức xác thực phù hợp cho quá trình triển khai chính thức Data Manager API.

Chọn trường hợp triển khai

Chọn phương pháp xác thực phù hợp với cấu trúc ứng dụng và môi trường triển khai của bạn:

Để biết hướng dẫn chung về quy trình xác thực của Google Cloud, hãy xem Sơ đồ quyết định xác thực của Google Cloud.

Khối lượng công việc trong Google Cloud

Khi chạy trên Google Cloud, hãy đính kèm một tài khoản dịch vụ trực tiếp vào tài nguyên điện toán của bạn hoặc định cấu hình Workload Identity Federation cho GKE. Thư viện ứng dụng sử dụng ADC để tự động truy xuất thông tin xác thực tạm thời cho tài khoản dịch vụ mà không cần tệp thông tin xác thực hoặc biến môi trường.

Compute Engine

Khi tạo một phiên bản máy ảo, hãy chỉ định tài khoản dịch vụ và phạm vi Data Manager API để mã truy cập do máy chủ siêu dữ liệu phiên bản trả về bao gồm cả uỷ quyền bắt buộc.

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"

Để cập nhật các phạm vi hoặc tài khoản dịch vụ trên một phiên bản hiện có, hãy dừng phiên bản, cập nhật cấu hình bằng set-service-account và khởi động lại phiên bản:

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

Chỉ định tài khoản dịch vụ khi triển khai dịch vụ:

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

Cloud Functions

Chỉ định tài khoản dịch vụ khi triển khai hàm:

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

GKE

  1. Bật tính năng Liên kết Workload Identity cho GKE trên cụm của bạn.

  2. Liên kết Tài khoản dịch vụ Kubernetes (KSA) với Tài khoản dịch vụ 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}"

  3. Chú thích Tài khoản dịch vụ Kubernetes bằng email Tài khoản dịch vụ Google:

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

  4. Chỉ định Tài khoản dịch vụ Kubernetes trong thông số kỹ thuật của nhóm:

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

Xác minh quyền truy cập vào IAM và tài khoản

Trước khi triển khai ứng dụng phát hành công khai, hãy xác minh rằng tài khoản dịch vụ của bạn có các quyền cần thiết:

  1. Cloud IAM của Google Cloud: Cấp cho tài khoản dịch vụ vai trò Người dùng dịch vụ (roles/serviceusage.serviceUsageConsumer) trong dự án trên đám mây của Google Cloud đã bật Data Manager API.

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"

  2. Quyền truy cập vào tài khoản đích: Cấp cho tài khoản dịch vụ quyền truy cập cần thiết vào tài khoản đích của bạn. Để xem hướng dẫn từng bước, hãy xem bài viết Thiết lập quyền truy cập vào tài khoản.

Khối lượng công việc bên ngoài Google Cloud

Khi chạy mã trong trung tâm dữ liệu tại chỗ hoặc trên các nhà cung cấp dịch vụ đám mây khác, hãy chọn một trong các cơ chế xác thực sau:

  • Liên kết Workload Identity (Nên dùng): Định cấu hình Liên kết Workload Identity để cho phép ứng dụng của bạn trao đổi thông tin xác thực từ nhà cung cấp danh tính bên ngoài để lấy thông tin xác thực ngắn hạn của Google Cloud mà không cần quản lý khoá tài khoản dịch vụ. Tạo tệp cấu hình thông tin xác thực và cung cấp tệp đó cho ADC bằng biến môi trường GOOGLE_APPLICATION_CREDENTIALS.

  • Khoá tài khoản dịch vụ (Dự phòng): Nếu bạn không thể sử dụng Workload Identity Federation, hãy tạo một khoá tài khoản dịch vụ rồi cung cấp khoá đó cho ADC bằng biến môi trường GOOGLE_APPLICATION_CREDENTIALS.

Đặt GOOGLE_APPLICATION_CREDENTIALS

Đặt biến môi trường GOOGLE_APPLICATION_CREDENTIALS thành đường dẫn tuyệt đối của tệp cấu hình thông tin xác thực Workload Identity Federation hoặc tệp khoá tài khoản dịch vụ để các thư viện ứng dụng có thể tự động xác định thông tin xác thực của bạn bằng ADC.

Linux / macOS

Đặt biến môi trường trong hồ sơ shell hoặc tập lệnh triển khai:

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

Windows (PowerShell)

Đặt biến môi trường trong PowerShell:

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

Docker / Vùng chứa

Gắn tệp thông tin xác thực vào vùng chứa và đặt biến môi trường:

ENV GOOGLE_APPLICATION_CREDENTIALS="/secrets/credentials.json"

Hoặc truyền biến môi trường trong thời gian chạy:

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

Gắn thông tin đăng nhập dưới dạng một Secret và tham chiếu thông tin đó trong môi trường của 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

Xác thực các yêu cầu REST và curl

Nếu quy trình tự động của bạn đưa ra các yêu cầu HTTP thô bằng curl thay vì sử dụng thư viện ứng dụng, hãy sử dụng Google Cloud CLI để xác thực không tương tác và quản lý mã truy cập mà không cần ký mã theo cách thủ công:

  1. Uỷ quyền cho Google Cloud CLI bằng tệp thông tin xác thực được định cấu hình trong môi trường của bạn:

    gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"

  2. Truyền mã truy cập đã tạo trong tiêu đề Authorization của yêu cầu API:

    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 tự động lưu mã truy cập vào bộ nhớ đệm và làm mới mã đó trước khi hết hạn.

Xác minh quyền truy cập vào tài khoản và IAM

Trước khi triển khai ứng dụng phát hành công khai, hãy xác minh rằng tài khoản dịch vụ của bạn có các quyền cần thiết:

  1. Cloud IAM của Google Cloud: Cấp cho tài khoản dịch vụ vai trò Người dùng dịch vụ (roles/serviceusage.serviceUsageConsumer) trong dự án trên đám mây của Google Cloud đã bật Data Manager API.

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
  --role="roles/serviceusage.serviceUsageConsumer"

  2. Quyền truy cập vào tài khoản đích: Cấp cho tài khoản dịch vụ quyền truy cập cần thiết vào tài khoản đích. Để xem hướng dẫn từng bước, hãy xem bài viết Thiết lập quyền truy cập vào tài khoản.

Hành động thay cho người dùng

Các nền tảng bên thứ ba như nền tảng tiếp thị và công ty quảng cáo thường cần gửi yêu cầu API thay mặt cho nhiều nhà quảng cáo đăng ký dịch vụ của họ.

Trong cấu trúc này, thay vì sử dụng Thông tin xác thực mặc định của ứng dụng, hãy sử dụng quy trình Máy chủ web OAuth 2.0 để lấy thông tin xác thực người dùng có quyền truy cập ngoại tuyến từ mỗi nhà quảng cáo, sau đó sử dụng thông tin xác thực đó để định cấu hình thư viện ứng dụng trong thời gian chạy dựa trên tài khoản nhà quảng cáo mà yêu cầu đang quản lý.

Triển khai quy trình web OAuth 2.0

Sau đây là cách thiết lập uỷ quyền cho người dùng đối với các ứng dụng nhiều đối tượng thuê:

  1. Xem không cần mạng: Chuyển hướng người dùng đến màn hình xin phép bằng OAuth của Google để yêu cầu phạm vi https://www.googleapis.com/auth/datamanager bằng access_type=offline và prompt=consent. Máy chủ của bạn trao đổi mã uỷ quyền để lấy mã truy cập và refresh_token. Để xem hướng dẫn từng bước, hãy xem bài viết OAuth 2.0 cho ứng dụng máy chủ web.

  2. Lưu trữ thông tin xác thực một cách an toàn: Lưu trữ mã làm mới của mỗi người dùng một cách an toàn trong vùng lưu trữ thông tin xác thực đã mã hoá liên kết với tài khoản của họ trên nền tảng của bạn.

  3. Khởi chạy thư viện ứng dụng khách trong thời gian chạy: Khi gửi yêu cầu API thay cho một người dùng cụ thể, hãy tạo thông tin đăng nhập của người dùng từ mã làm mới mà bạn đã lưu trữ cho người dùng, cũng như mã ứng dụng khách và khoá bí mật của ứng dụng khách, rồi truyền thông tin đăng nhập đó khi khởi chạy ứng dụng khách:

    .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

Hoàn tất quy trình xác minh ứng dụng OAuth

Vì phạm vi của Data Manager API là phạm vi nhạy cảm, nên mọi ứng dụng chạy trên đám mây của Google dùng để lấy thông tin xác thực của người dùng từ Tài khoản Google bên ngoài đều phải trải qua quy trình xác minh OAuth của Google trước khi đưa vào hoạt động chính thức:

  • Phát triển: Khi trạng thái xuất bản của ứng dụng được đặt thành Kiểm thử trên trang Đối tượng trong bảng điều khiển Google Cloud, chỉ những tài khoản kiểm thử được chỉ định mới có thể uỷ quyền cho ứng dụng của bạn.
  • Phát hành công khai: Trước khi cung cấp ứng dụng cho người dùng bên ngoài, hãy đặt trạng thái phát hành thành Đang phát hành công khai và gửi ứng dụng để xác minh.

Bạn không cần xác minh ứng dụng đối với những khối lượng công việc chạy bằng tài khoản dịch vụ. Ngoài ra, có một số trường hợp ngoại lệ đối với các trường hợp như ứng dụng nội bộ. Hãy xem phần Khi nào không cần xác minh để biết thông tin chi tiết.

Nếu tổ chức của bạn là đối tác dữ liệu được phê duyệt, thì bạn có thể sử dụng liên kết đối tác thay vì quản lý mã thông báo OAuth cho mỗi người dùng để nhập dữ liệu liên tục.

Thông qua mối liên kết đối tác, nhà quảng cáo kết nối tài khoản của họ với tài khoản đối tác dữ liệu của bạn trong giao diện người dùng của Google Ads, Display & Video 360 hoặc Google Ad Manager. Sau khi thiết lập mối liên kết, ứng dụng của bạn sẽ gửi yêu cầu nhập dữ liệu bằng thông tin đăng nhập tài khoản dịch vụ của riêng bạn thông qua ADC, tránh việc phải lưu trữ và duy trì mã làm mới người dùng có thời hạn dài.

Các phương pháp hay nhất về môi trường phát hành chính thức

Hãy xem xét những điểm quan trọng sau đây về hoạt động khi chuyển sang môi trường thực tế: