คำแนะนำนี้จะช่วยคุณเลือกและกำหนดค่าแนวทางการตรวจสอบสิทธิ์ที่เหมาะสมสำหรับการติดตั้งใช้งาน Data Manager API ในเวอร์ชันที่ใช้งานจริง
เลือกสถานการณ์การติดตั้งใช้งาน
เลือกแนวทางการตรวจสอบสิทธิ์ที่ตรงกับสถาปัตยกรรมแอปพลิเคชันและสภาพแวดล้อมการติดตั้งใช้งาน
- ภาระงานใน Google Cloud: สำหรับภาระงานอัตโนมัติ (เช่น ไปป์ไลน์ ETL, งานแบบกลุ่ม หรือบริการแบ็กเอนด์) ที่ทำงาน ใน Compute Engine, Cloud Run, Cloud Functions หรือ GKE ให้ใช้ ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน (ADC) กับบัญชีบริการที่แนบไว้ หรือการรวมศูนย์ Workload Identity สำหรับ GKE
- ภาระงานนอก Google Cloud: สำหรับภาระงานอัตโนมัติที่ทำงานภายในองค์กรหรือในผู้ให้บริการคลาวด์รายอื่น ให้ใช้ ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน (ADC) กับการรวมศูนย์ Workload Identity หรือคีย์บัญชีบริการ
- ดำเนินการในนามของผู้ใช้: สำหรับแพลตฟอร์มของบุคคลที่สาม และแอปพลิเคชันแบบหลายผู้เช่าที่จัดการบัญชีสำหรับผู้ใช้ภายนอก (เช่น ผู้ลงโฆษณาที่ลงชื่อสมัครใช้ในแพลตฟอร์มของคุณ) ให้ใช้ ขั้นตอน OAuth 2.0 สำหรับเว็บเซิร์ฟเวอร์ที่มีโทเค็นเพื่อรีเฟรชต่อผู้ใช้ หรือลิงก์พาร์ทเนอร์หากคุณเป็นพาร์ทเนอร์ด้านข้อมูลที่ได้รับอนุมัติ
ดูคำแนะนำทั่วไปเกี่ยวกับการตรวจสอบสิทธิ์ของ Google Cloud ได้ที่ แผนผังการตัดสินใจเกี่ยวกับการตรวจสอบสิทธิ์ของ Google Cloud
ภาระงานใน Google Cloud
เมื่อทำงานใน Google Cloud ให้แนบบัญชีบริการกับทรัพยากรการประมวลผลโดยตรงหรือ กำหนดค่า การรวมศูนย์ Workload Identity สำหรับ 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 สำหรับ 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}"ใส่คำอธิบายประกอบในบัญชีบริการ Kubernetes ด้วยอีเมลบัญชีบริการ Google
kubectl annotate serviceaccount KUBERNETES_SA_NAME \ --namespace="KUBERNETES_NAMESPACE" \ iam.gke.io/gcp-service-account="SERVICE_ACCOUNT_EMAIL"ระบุบัญชีบริการ Kubernetes ในข้อกำหนดของพ็อด
apiVersion: v1 kind: Pod metadata: name: data-manager-worker spec: serviceAccountName: KUBERNETES_SA_NAME containers: - name: worker image: IMAGE_URL
ยืนยัน IAM และสิทธิ์เข้าถึงบัญชี
ก่อนติดตั้งใช้งานแอปพลิเคชันเวอร์ชันที่ใช้งานจริง ให้ตรวจสอบว่าบัญชีบริการมีสิทธิ์ที่จำเป็นดังนี้
สิทธิ์ IAM ของ Google Cloud: ให้บัญชีบริการ บทบาทผู้ใช้บริการ (
roles/serviceusage.serviceUsageConsumer) ใน โปรเจ็กต์ Google Cloud ที่เปิดใช้ Data Manager APIgcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role="roles/serviceusage.serviceUsageConsumer"สิทธิ์เข้าถึงบัญชีปลายทาง: ให้สิทธิ์เข้าถึงที่จำเป็นแก่บัญชีบริการ ในบัญชีปลายทาง ดูวิธีการทีละขั้นตอนได้ที่ หัวข้อตั้งค่าสิทธิ์เข้าถึงบัญชี
ภาระงานนอก Google Cloud
เมื่อเรียกใช้โค้ดในศูนย์ข้อมูลภายในองค์กรหรือในผู้ให้บริการคลาวด์รายอื่น ให้เลือกกลไกการตรวจสอบสิทธิ์อย่างใดอย่างหนึ่งต่อไปนี้
การรวมศูนย์ Workload Identity (แนะนำ): กำหนดค่า การรวมศูนย์ Workload Identity เพื่อให้แอปพลิเคชันแลกเปลี่ยน ข้อมูลเข้าสู่ระบบจากผู้ให้บริการข้อมูลประจำตัวภายนอกเป็นข้อมูลเข้าสู่ระบบ Google Cloud ที่มีอายุสั้นได้โดยไม่ต้องจัดการคีย์บัญชีบริการ สร้างไฟล์การกำหนดค่าข้อมูลเข้าสู่ระบบและระบุไฟล์ดังกล่าวให้กับ ADC โดยใช้ตัวแปรสภาพแวดล้อม
GOOGLE_APPLICATION_CREDENTIALSคีย์บัญชีบริการ (ตัวเลือกสำรอง): หากการรวมศูนย์ Workload Identity ไม่ พร้อมใช้งาน ให้สร้างคีย์บัญชีบริการและระบุคีย์ดังกล่าวให้กับ ADC โดยใช้ตัวแปรสภาพแวดล้อม
GOOGLE_APPLICATION_CREDENTIALS
ตั้งค่า 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
ต่อเชื่อมข้อมูลเข้าสู่ระบบเป็นข้อมูลลับและอ้างอิงข้อมูลเข้าสู่ระบบในสภาพแวดล้อมของพ็อดโดยทำดังนี้
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 เพื่อตรวจสอบสิทธิ์แบบไม่โต้ตอบและจัดการโทเค็นเพื่อการเข้าถึงโดยไม่ต้องลงชื่อโทเค็นด้วยตนเองโดยทำดังนี้
ให้สิทธิ์ Google Cloud CLI โดยใช้ไฟล์ข้อมูลเข้าสู่ระบบที่กำหนดค่าไว้ในสภาพแวดล้อม
gcloud auth login --cred-file="${GOOGLE_APPLICATION_CREDENTIALS}"ส่งโทเค็นเพื่อการเข้าถึงที่สร้างขึ้นในส่วนหัว
Authorizationของคำขอ APIcurl -X POST "https://datamanager.googleapis.com/v1/..." \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @request.jsonGoogle Cloud CLI จะแคชโทเค็นเพื่อการเข้าถึงและรีเฟรชโทเค็นโดยอัตโนมัติก่อนที่โทเค็นจะหมดอายุ
ยืนยัน IAM และสิทธิ์เข้าถึงบัญชี
ก่อนติดตั้งใช้งานแอปพลิเคชันเวอร์ชันที่ใช้งานจริง ให้ตรวจสอบว่าบัญชีบริการมีสิทธิ์ที่จำเป็นดังนี้
สิทธิ์ IAM ของ Google Cloud: ให้บัญชีบริการ บทบาทผู้ใช้บริการ (
roles/serviceusage.serviceUsageConsumer) ใน โปรเจ็กต์ Google Cloud ที่เปิดใช้ Data Manager APIgcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role="roles/serviceusage.serviceUsageConsumer"สิทธิ์เข้าถึงบัญชีปลายทาง: ให้สิทธิ์เข้าถึงที่จำเป็นแก่บัญชีบริการ ในบัญชีปลายทาง ดูวิธีการทีละขั้นตอนได้ที่ หัวข้อตั้งค่าสิทธิ์เข้าถึงบัญชี
ดำเนินการในนามของผู้ใช้
แพลตฟอร์มของบุคคลที่สาม เช่น แพลตฟอร์มการตลาดและเอเจนซี มักต้องส่งคำขอ API ในนามของผู้ลงโฆษณาหลายรายที่ลงชื่อสมัครใช้บริการ
ในสถาปัตยกรรมนี้ ให้ใช้ ขั้นตอน OAuth 2.0 สำหรับเว็บเซิร์ฟเวอร์เพื่อรับข้อมูลเข้าสู่ระบบของผู้ใช้ที่มี การเข้าถึงแบบออฟไลน์จากผู้ลงโฆษณาแต่ละรายแทนการใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน จากนั้นใช้ข้อมูลเข้าสู่ระบบเหล่านั้นเพื่อกำหนดค่า ไลบรารีของไคลเอ็นต์ในรันไทม์โดยอิงตามบัญชีผู้ลงโฆษณาที่คำขอ จัดการ
ใช้ขั้นตอน OAuth 2.0 สำหรับเว็บ
วิธีตั้งค่าการมอบสิทธิ์ของผู้ใช้สำหรับแอปพลิเคชันแบบหลายผู้เช่ามีดังนี้
ขอสิทธิ์เข้าถึงแบบออฟไลน์: นำผู้ใช้ไปยังหน้าจอขอความยินยอม OAuth ของ Google เพื่อขอขอบเขต
https://www.googleapis.com/auth/datamanagerด้วยaccess_type=offlineและprompt=consentเซิร์ฟเวอร์จะแลกรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึงและrefresh_tokenดูวิธีการทีละขั้นตอนได้ที่หัวข้อ OAuth 2.0 สำหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์จัดเก็บข้อมูลเข้าสู่ระบบอย่างปลอดภัย: จัดเก็บโทเค็นการรีเฟรชของผู้ใช้แต่ละรายอย่างปลอดภัย ในที่เก็บข้อมูลเข้าสู่ระบบที่เข้ารหัสซึ่งเชื่อมโยงกับบัญชีของผู้ใช้ใน แพลตฟอร์ม
เริ่มต้นไลบรารีของไคลเอ็นต์ในรันไทม์: เมื่อส่งคำขอ 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 ภายนอกจะต้องผ่านการยืนยัน OAuth ของ Googleก่อนที่จะเผยแพร่เป็นเวอร์ชันที่ใช้งานจริง
- การพัฒนา: ขณะที่สถานะการเผยแพร่ของแอปตั้งค่าเป็น การทดสอบ ใน หน้า กลุ่มเป้าหมาย ในคอนโซล Google Cloud เฉพาะบัญชีทดสอบที่กำหนดเท่านั้นที่จะให้สิทธิ์แอปพลิเคชันของคุณได้
- เวอร์ชันที่ใช้งานจริง: ก่อนที่จะทำให้แอปพลิเคชันพร้อมให้บริการแก่ผู้ใช้ภายนอก ให้ตั้งค่าสถานะการเผยแพร่เป็น พร้อมใช้งาน แล้ว ส่งแอปเพื่อรับการยืนยัน
ระบบไม่จำเป็นต้องยืนยันแอปสำหรับภาระงานที่ทำงานโดยใช้บัญชีบริการ นอกจากนี้ ยังมีข้อยกเว้นบางประการสำหรับสถานการณ์ต่างๆ เช่น แอปพลิเคชันภายใน ดูรายละเอียดได้ที่หัวข้อ กรณีที่ไม่จำเป็นต้องยืนยันแอป
ตัวเลือกอื่น: ลิงก์พาร์ทเนอร์
หากองค์กรของคุณเป็นพาร์ทเนอร์ด้านข้อมูลที่ได้รับอนุมัติ คุณสามารถใช้ ลิงก์พาร์ทเนอร์แทนการจัดการโทเค็น OAuth ต่อผู้ใช้สำหรับ การนำเข้าข้อมูลอย่างต่อเนื่อง
ลิงก์พาร์ทเนอร์ช่วยให้ผู้ลงโฆษณาสามารถเชื่อมต่อบัญชีของตนกับบัญชีพาร์ทเนอร์ด้านข้อมูลของคุณใน UI ของ Google Ads, Display &Video 360 หรือ Google Ad Manager หลังจากสร้างลิงก์แล้ว แอปพลิเคชันจะส่งคำขอการนำเข้าโดยใช้ข้อมูลเข้าสู่ระบบบัญชีบริการของคุณเองผ่าน ADC ซึ่งช่วยลดความจำเป็นในการจัดเก็บและดูแลรักษาโทเค็นการรีเฟรชของผู้ใช้ที่มีอายุยาวนาน
แนวทางปฏิบัติแนะนำสำหรับเวอร์ชันที่ใช้งานจริง
โปรดตรวจสอบข้อควรพิจารณาด้านการดำเนินงานที่สำคัญต่อไปนี้เมื่อย้ายไปใช้เวอร์ชันที่ใช้งานจริง
- การจัดการข้อผิดพลาดและการตรวจสอบ: ทำความเข้าใจวิธีที่ API ตรวจสอบคำขอโดยใช้ โมเดลการล้มเหลวอย่างรวดเร็ว และแสดง รายละเอียดข้อผิดพลาดแบบมีโครงสร้าง
- กลยุทธ์การลองใหม่: ใช้ Exponential Backoff พร้อมการสุ่มเวลาหน่วงสำหรับข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ชั่วคราว
- การจัดกลุ่มและการทำงานพร้อมกัน: เพิ่มปริมาณงานสูงสุดโดยการ จัดกลุ่มระเบียนและส่งคำขอพร้อมกันภายในขีดจำกัด
- การวินิจฉัยและการตรวจสอบ: บันทึกรหัสคำขอการตอบกลับและค้นหาบริการวินิจฉัยเพื่อยืนยันการประมวลผลแบบไม่พร้อมกัน รวมถึงตรวจหาคำเตือนและข้อผิดพลาด