ทำให้ใช้งานได้เป็นเวอร์ชันที่ใช้งานจริง

คู่มือนี้จะช่วยคุณเลือกและกำหนดค่าแนวทางการตรวจสอบสิทธิ์ที่เหมาะสมสำหรับการติดตั้งใช้งาน Data Manager API ในเวอร์ชันที่ใช้งานจริง

เลือกสถานการณ์การติดตั้งใช้งาน

เลือกวิธีการตรวจสอบสิทธิ์ที่ตรงกับสถาปัตยกรรมแอปพลิเคชันและสภาพแวดล้อมการติดตั้งใช้งาน ดังนี้

ดูคำแนะนำทั่วไปเกี่ยวกับการตรวจสอบสิทธิ์ Google Cloud ได้ที่แผนผังการตัดสินใจในการตรวจสอบสิทธิ์ Google Cloud

ภาระงานใน Google Cloud

เมื่อใช้งานใน Google Cloud ให้แนบบัญชีบริการกับทรัพยากรการประมวลผลโดยตรงหรือกำหนดค่าWorkload Identity Federation สำหรับ 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

  1. เปิดใช้ Workload Identity Federation สำหรับ GKE ในคลัสเตอร์

  2. เชื่อมโยงบัญชีบริการ 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}"

  3. ใส่คำอธิบายประกอบบัญชีบริการ Kubernetes ด้วยอีเมลบัญชีบริการ Google ดังนี้

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

  4. ระบุบัญชีบริการ Kubernetes ในข้อกำหนดเฉพาะของพ็อด ดังนี้

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

ยืนยัน IAM และสิทธิ์เข้าถึงบัญชี

ก่อนทำให้แอปพลิเคชันเวอร์ชันที่ใช้งานจริงใช้งานได้ ให้ตรวจสอบว่าบัญชีบริการของคุณมีสิทธิ์ที่จำเป็นดังต่อไปนี้

  1. สิทธิ์ IAM ของ Google Cloud: มอบบทบาทผู้ใช้บริการ (roles/serviceusage.serviceUsageConsumer) ให้กับบัญชีบริการในโปรเจ็กต์ Google Cloud ที่เปิดใช้ Data Manager API

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

  2. สิทธิ์เข้าถึงบัญชีปลายทาง: ให้สิทธิ์เข้าถึงที่จำเป็นแก่บัญชีบริการในบัญชีปลายทาง ดูวิธีการทีละขั้นตอนได้ที่หัวข้อตั้งค่าสิทธิ์เข้าถึงบัญชี

ภาระงานนอก Google Cloud

เมื่อเรียกใช้โค้ดในศูนย์ข้อมูลภายในองค์กรหรือในผู้ให้บริการคลาวด์รายอื่น ให้เลือกกลไกการตรวจสอบสิทธิ์อย่างใดอย่างหนึ่งต่อไปนี้

  • Workload Identity Federation (แนะนำ): กำหนดค่า Workload Identity Federation เพื่อให้แอปพลิเคชันแลกเปลี่ยนข้อมูลเข้าสู่ระบบจากผู้ให้บริการข้อมูลประจำตัวภายนอกเป็นข้อมูลเข้าสู่ระบบ Google Cloud ที่มีอายุสั้นโดยไม่ต้องจัดการคีย์บัญชีบริการ สร้างไฟล์การกำหนดค่าข้อมูลเข้าสู่ระบบและส่งให้ ADC โดยใช้ตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS

  • คีย์บัญชีบริการ (สำรอง): หาก Workload Identity Federation ไม่พร้อมใช้งาน ให้สร้างคีย์บัญชีบริการและระบุให้กับ ADC โดยใช้ตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS

ชุด GOOGLE_APPLICATION_CREDENTIALS

ตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เป็น Absolute Path ของไฟล์การกำหนดค่าข้อมูลเข้าสู่ระบบการรวมศูนย์ Workload Identity หรือไฟล์คีย์บัญชีบริการ เพื่อให้ไลบรารีของไคลเอ็นต์ค้นหาข้อมูลเข้าสู่ระบบของคุณได้โดยอัตโนมัติโดยใช้ ADC

Linux / macOS

ตั้งค่าตัวแปรสภาพแวดล้อมในโปรไฟล์ Shell หรือสคริปต์การติดตั้งใช้งาน ดังนี้

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

ต่อเชื่อมข้อมูลเข้าสู่ระบบเป็นข้อมูลลับและอ้างอิงในสภาพแวดล้อมของพ็อด ดังนี้

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

หากไปป์ไลน์อัตโนมัติของคุณส่งคำขอ HTTP ดิบด้วย curl แทนที่จะใช้ไลบรารีของไคลเอ็นต์ ให้ใช้ Google Cloud CLI เพื่อตรวจสอบสิทธิ์แบบไม่โต้ตอบและจัดการโทเค็นเพื่อการเข้าถึงโดยไม่ต้องลงชื่อโทเค็นด้วยตนเอง

  1. ให้สิทธิ์ Google Cloud CLI โดยใช้ไฟล์ข้อมูลเข้าสู่ระบบที่กำหนดค่าไว้ในสภาพแวดล้อมของคุณ โดยทำดังนี้

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

  2. ส่งโทเค็นเพื่อการเข้าถึงที่สร้างขึ้นในส่วนหัว Authorization ของคำขอ 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 จะแคชโทเค็นเพื่อการเข้าถึงและรีเฟรชโดยอัตโนมัติก่อนหมดอายุ

ยืนยัน IAM และสิทธิ์เข้าถึงบัญชี

ก่อนทำให้แอปพลิเคชันเวอร์ชันที่ใช้งานจริงใช้งานได้ ให้ตรวจสอบว่าบัญชีบริการของคุณมีสิทธิ์ที่จำเป็นดังต่อไปนี้

  1. สิทธิ์ IAM ของ Google Cloud: มอบบทบาทผู้ใช้บริการ (roles/serviceusage.serviceUsageConsumer) ให้กับบัญชีบริการในโปรเจ็กต์ Google Cloud ที่เปิดใช้ Data Manager API

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

  2. สิทธิ์เข้าถึงบัญชีปลายทาง: ให้สิทธิ์เข้าถึงที่จำเป็นแก่บัญชีบริการในบัญชีปลายทาง ดูวิธีการทีละขั้นตอนได้ที่หัวข้อตั้งค่าสิทธิ์เข้าถึงบัญชี

ดำเนินการในนามของผู้ใช้

แพลตฟอร์มของบุคคลที่สาม เช่น แพลตฟอร์มการตลาดและเอเจนซี มักจะต้องส่งคำขอ API ในนามของผู้ลงโฆษณาหลายรายที่ลงชื่อสมัครใช้บริการของตน

ในสถาปัตยกรรมนี้ ให้ใช้ขั้นตอนของเว็บเซิร์ฟเวอร์ OAuth 2.0 เพื่อรับข้อมูลเข้าสู่ระบบของผู้ใช้ที่มีการเข้าถึงแบบออฟไลน์จากผู้ลงโฆษณาแต่ละรายแทนการใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน จากนั้นใช้ข้อมูลเข้าสู่ระบบเหล่านั้นเพื่อกำหนดค่าไลบรารีของไคลเอ็นต์ที่รันไทม์ตามบัญชีผู้ลงโฆษณาที่คำขอจัดการอยู่

ใช้ขั้นตอนการทำงานบนเว็บของ OAuth 2.0

วิธีตั้งค่าการมอบสิทธิ์ของผู้ใช้สำหรับแอปพลิเคชันแบบหลายกลุ่มผู้ใช้มีดังนี้

  1. ขอสิทธิ์เข้าถึงแบบออฟไลน์: นำผู้ใช้ไปยังหน้าจอขอความยินยอม OAuth ของ Google ที่ขอขอบเขต https://www.googleapis.com/auth/datamanager พร้อม access_type=offline และ prompt=consent เซิร์ฟเวอร์ของคุณจะแลกรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึงและ refresh_token ดูวิธีการทีละขั้นตอนได้ที่หัวข้อ OAuth 2.0 สำหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์

  2. จัดเก็บข้อมูลเข้าสู่ระบบอย่างปลอดภัย: จัดเก็บโทเค็นการรีเฟรชของผู้ใช้แต่ละรายอย่างปลอดภัยในที่เก็บข้อมูลเข้าสู่ระบบที่เข้ารหัสซึ่งเชื่อมโยงกับบัญชีของผู้ใช้ในแพลตฟอร์มของคุณ

  3. เริ่มต้นไลบรารีของไคลเอ็นต์ที่รันไทม์: เมื่อส่งคำขอ API ในนามของผู้ใช้ที่เฉพาะเจาะจง ให้สร้างข้อมูลเข้าสู่ระบบของผู้ใช้จากโทเค็นการรีเฟรชที่คุณจัดเก็บไว้สำหรับผู้ใช้ รวมถึงรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์สำหรับแอปของคุณ แล้วส่งข้อมูลดังกล่าวเมื่อเริ่มต้นไคลเอ็นต์

    .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 ต่อผู้ใช้สำหรับการนำเข้าข้อมูลอย่างต่อเนื่องได้

ลิงก์พาร์ทเนอร์ช่วยให้ผู้ลงโฆษณาเชื่อมต่อบัญชีของตนกับบัญชีพาร์ทเนอร์ด้านข้อมูลใน UI ของ Google Ads, Display & Video 360 หรือ Google Ad Manager ได้ หลังจากสร้างลิงก์แล้ว แอปพลิเคชันจะส่งคำขอส่งผ่านข้อมูลโดยใช้ข้อมูลเข้าสู่ระบบของบัญชีบริการของคุณเองผ่าน ADC ซึ่งช่วยหลีกเลี่ยงความจำเป็นในการจัดเก็บและดูแลรักษาโทเค็นการรีเฟรชของผู้ใช้ที่มีอายุการใช้งานยาวนาน

แนวทางปฏิบัติแนะนำสำหรับการผลิต

โปรดตรวจสอบข้อควรพิจารณาด้านการดำเนินการที่สำคัญต่อไปนี้เมื่อเปลี่ยนไปใช้เวอร์ชันที่ใช้งานจริง