این راهنما به شما کمک میکند رویکرد اصالتسنجی مناسب را برای استقرار تولید Data Manager API انتخاب و پیکربندی کنید.
سناریو استقرار خود را انتخاب کنید
رویکرد اصالتسنجیای را انتخاب کنید که با معماری برنامه و محیط استقرار شما مطابقت داشته باشد:
- حجمهای کاری در Google Cloud: برای حجمهای کاری خودکارشده (مثل خطوط لوله ETL، کارهای دستهای، یا سرویسهای پسبک) که در Compute Engine، Cloud Run، Cloud Functions، یا GKE اجرا میشوند، از اطلاعات اعتباری پیشفرض برنامه (ADC) با حساب سرویس پیوستشده یا Workload Identity Federation برای 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"
توابع ابری
هنگام استقرار تابع، حساب سرویس را مشخص کنید:
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}"حساب سرویس Kubernetes را با ایمیل حساب سرویس Google حاشیهنویسی کنید:
kubectl annotate serviceaccount KUBERNETES_SA_NAME \ --namespace="KUBERNETES_NAMESPACE" \ iam.gke.io/gcp-service-account="SERVICE_ACCOUNT_EMAIL"«حساب سرویس Kubernetes» را در مشخصات pod خود مشخص کنید:
apiVersion: v1 kind: Pod metadata: name: data-manager-worker spec: serviceAccountName: KUBERNETES_SA_NAME containers: - name: worker image: IMAGE_URL
تأیید دسترسی به حساب و IAM
قبلاز استقرار برنامه تولیدیتان، بررسی کنید که حساب سرویس شما اجازههای لازم را داشته باشد:
اجازههای Google Cloud IAM: به حساب سرویس نقش مصرفکننده استفاده از سرویس (
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"دسترسی به حساب مقصد: دسترسی لازم به حسابهای مقصد را به حساب سرویس اعطا کنید. برای دستورالعملهای گامبهگام، راهاندازی دسترسی به حساب را ببینید.
حجمهای کاری خارج از Google Cloud
هنگام اجرای کد در مراکز داده درونمحل یا در سایر ارائهدهندگان ابری، یکی از سازوکارهای اصالتسنجی زیر را انتخاب کنید:
Workload Identity Federation (توصیهشده): Workload Identity Federation را پیکربندی کنید تا به برنامهتان اجازه دهید اعتبارنامههای ارائهدهنده هویت خارجیتان را با اعتبارنامههای کوتاهمدت Google Cloud مبادله کند، بدون اینکه نیاز به مدیریت کلیدهای حساب سرویس باشد. فایل پیکربندی اعتبارنامه تولید کنید و آن را بااستفاده از متغیر محیطی
GOOGLE_APPLICATION_CREDENTIALSبه ADC ارائه دهید.کلیدهای حساب سرویس (جایگزین): اگر Workload Identity Federation دردسترس نیست، کلید حساب سرویس ایجاد کنید و آن را بااستفاده از متغیر محیطی
GOOGLE_APPLICATION_CREDENTIALSبه ADC ارائه دهید.
دور GOOGLE_APPLICATION_CREDENTIALS
متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر مطلق فایل پیکربندی اعتبارنامه Workload Identity Federation یا فایل کلید حساب سرویس تنظیم کنید تا کتابخانههای کارخواه بتوانند اعتبارنامههایتان را بهطور خودکار بااستفاده از ADC پیدا کنند.
Linux / macOS
متغیر محیطی را در نمایه پوسته یا اسکریپت استقرار تنظیم کنید:
export GOOGLE_APPLICATION_CREDENTIALS=\
"/path/to/credentials.json"
Windows (PowerShell)
متغیر محیط را در PowerShell تنظیم کنید:
$env:GOOGLE_APPLICATION_CREDENTIALS = `
"C:\path\to\credentials.json"
Docker / Containers
فایل اعتبارنامه را در محفظه سوار کنید و متغیر محیطی را تنظیم کنید:
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درخواستهای میانای برنامهسازی کاربردی خود ارسال کنید:curl -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
قبلاز استقرار برنامه تولید، بررسی کنید که حساب سرویس شما اجازههای لازم را داشته باشد:
اجازههای Google Cloud IAM: به حساب سرویس نقش مصرفکننده استفاده از سرویس (
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"دسترسی به حساب مقصد: به حساب سرویس دسترسی لازم را به حسابهای مقصدتان اعطا کنید. برای دستورالعملهای گامبهگام، راهاندازی دسترسی به حساب را ببینید.
اقدام ازطرف کاربران
پلاتفرمهای شخص ثالث مانند پلاتفرمها و آژانسهای بازاریابی اغلب باید درخواستهای 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 ازطرف یک کاربر خاص، اطلاعات اعتباری کاربر را از ژتون بازآوری که برای کاربر ذخیره کردهاید و شناسه کارخواه و رمز کارخواه برای برنامهتان بسازید و آنها را هنگام مقداردهی اولیه کارخواه ارسال کنید:
دات نت
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();رفتن
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))جاوا
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 Cloud که برای دریافت اطلاعات کاربری کاربر از «حسابهای Google» خارجی استفاده میشود باید قبلاز رفتن به مرحله تولید، درستیسنجی Google OAuth را بگذراند:
- توسعه: وقتی وضعیت انتشار برنامه در صفحه مخاطبان در کنسول Google Cloud روی آزمایش تنظیم شده باشد، فقط حسابهای آزمایشی تعیینشده میتوانند برنامه شما را مجاز کنند.
- تولید: قبلاز دردسترس قرار دادن برنامهتان برای کاربران خارجی، وضعیت انتشار را روی در مرحله تولید تنظیم کنید و برنامه را برای درستیسنجی ارسال کنید.
درستیسنجی برنامه برای حجمهای کاری که بااستفاده از حسابهای سرویس اجرا میشوند لازم نیست. علاوهبراین، چند مورد استثنا برای سناریوهایی مثل برنامههای داخلی وجود دارد. برای جزئیات، چه زمانی درستیسنجی لازم نیست را بررسی کنید.
جایگزین: پیوندهای شریک
اگر سازمانتان شریک داده تأییدشده است، میتوانید بهجای مدیریت کردن توکنهای OAuth برای هر کاربر، از پیوندهای شریک برای دریافت مداوم دادهها استفاده کنید.
با پیوندهای شریک، آگهیدهندگان حسابهایشان را به حساب شریک داده شما در میانای کاربر Google Ads، Display & Video 360، یا Google Ad Manager متصل میکنند. پساز برقراری پیوند، برنامه شما درخواستهای انتقال را بااستفاده از اعتبارنامههای حساب سرویس خودتان ازطریق ADC ارسال میکند و نیاز به ذخیره و نگهداری ژتونهای بازآوری کاربر با عمر طولانی را ازبین میبرد.
روالهای مطلوب تولید
هنگام انتقال به تولید، این ملاحظات عملیاتی کلیدی را مرور کنید:
- رسیدگی به خطا و اعتبارسنجی: با نحوه اعتبارسنجی درخواستها توسط API بااستفاده از مدل شکست سریع و برگرداندن جزئیات ساختاریافته خطا آشنا شوید.
- استراتژی امتحان مجدد: برای خطاهای موقت سرور، عقبگرد نمایی با لرزش را پیادهسازی کنید.
- دستهبندی و همزمانی: با دستهبندی کردن سوابق و ارسال همزمان درخواستها در چارچوب محدودیتها، توان عملیاتی را به حداکثر برسانید.
- عیبیابی و نظارت: شناسههای درخواست پاسخ را ضبط کنید و سرویس عیبیابی را برای تأیید پردازش ناهمگام و شناسایی هشدارها و خطاها جستجو کنید.