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 pháp xác thực phù hợp cho việc triển khai Data Manager API trong môi trường sản xuất.

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ề việc xác thực trên Google Cloud, hãy xem cây quyết định xác thực trên Google Cloud.

Tải 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 đăng nhập có thời hạn ngắn cho tài khoản dịch vụ mà không cần tệp thông tin đăng nhập 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 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. Quyền IAM của Google Cloud: Cấp cho tài khoản dịch vụ vai trò Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) trong dự án Google Cloud mà bạn đã 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.

Tải bên ngoài Google Cloud

Khi chạy mã trong các 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:

  • Workload Identity Federation (Được đề xuất): Định cấu hình Workload Identity Federation để 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 một 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 không có Workload Identity Federation, hãy tạo một khoá tài khoản dịch vụ và 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 đăng nhập 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 nhóm:

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 một thư viện ứng dụng, hãy 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ã thông báo 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 các 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ã này trước khi hết hạn.

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. Quyền IAM của Google Cloud: Cấp cho tài khoản dịch vụ vai trò Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) trong dự án Google Cloud mà bạn đã 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.

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. Yêu cầu quyền truy cập khi không có mạng: Chuyển 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 phần OAuth 2.0 cho ứng dụng máy chủ web.

  2. Lưu trữ thông tin đăng nhập 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 một kho thông tin đăng nhập đượ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 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 và khoá bí mật của ứng dụng, rồi truyền thông tin đăng nhập đó khi khởi chạy ứng dụng:

    .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ì https://www.googleapis.com/auth/datamanager là một phạm vi nhạy cảm, nên mọi ứng dụng Google Cloud được dùng để lấy thông tin đăng nhập 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 chuyển sang giai đoạn phát hành công khai:

  • 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 Google Cloud Console, 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 cho 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à một đối tác dữ liệu được phê duyệt, bạn có thể sử dụng đường liên kết đối tác thay vì quản lý mã thông báo OAuth cho từng người dùng để liên tục nhập dữ liệu.

Thông qua mối liên kết với đối tác, nhà quảng cáo có thể 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 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 các yêu cầu tiếp nhận bằng thông tin xác thực tài khoản dịch vụ của riêng bạn thông qua ADC, tránh nhu cầu lưu trữ và duy trì mã làm mới người dùng có thời gian tồn tại lâu dài.

Các phương pháp hay nhất về sản xuất

Hãy xem xét những điểm cần cân nhắc chính về hoạt động khi chuyển sang giai đoạn phát hành công khai: