‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

استقرار در دسته هدف تولید

این راهنما به شما کمک می‌کند رویکرد اصالت‌سنجی مناسب را برای استقرار تولید «میانای برنامه‌سازی کاربردی مدیر داده» خود انتخاب و پیکربندی کنید.

سناریو استقرار خود را انتخاب کنید

رویکرد اصالت‌سنجی‌ای را انتخاب کنید که با معماری برنامه و محیط استقرار شما مطابقت داشته باشد:

حجم‌های کاری در 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 اجرا می‌کنید، حساب سرویس را مستقیماً به منبع محاسباتی خودتان پیوست کنید یا فدراسیون هویت بار کاری را برای 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

فدراسیون هویت بار کاری برای 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 و حساب را تأیید کنید

قبل‌از استقرار برنامه تولید، بررسی کنید که حساب سرویس شما اجازه‌های لازم را داشته باشد:

اجازه‌های 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

اگر خط لوله خودکارسازی‌شده شما درخواست‌های اچ‌تی‌تی‌پی خام با 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.json
```
«خط فرمان Google Cloud» به‌طور خودکار نشان دسترسی را در حافظه نهان ذخیره می‌کند و آن را قبل‌از انقضا بازآوری می‌کند.

درستی‌سنجی 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 هدایت کنید و با access_type=offline و prompt=consent، حوزه https://www.googleapis.com/auth/datamanager را درخواست کنید. سرور شما کد مجوز را با یک کد دسترسی و یک 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 بااستفاده از مدل شکست سریع و برگرداندن جزئیات خطای ساختاریافته آشنا شوید.
استراتژی تلاش مجدد: برای خطاهای سرور موقت، عقب‌گرد نمایی با لرزش پیاده‌سازی کنید.
دسته‌بندی و هم‌زمانی: با دسته‌بندی کردن سوابق و ارسال هم‌زمان درخواست‌ها در چارچوب محدودیت‌ها، توان عملیاتی را به حداکثر برسانید.
عیب‌یابی و نظارت: شناسه‌های درخواست پاسخ را ضبط کنید و سرویس عیب‌یابی را برای تأیید پردازش ناهمگام و شناسایی هشدارها و خطاها جستجو کنید.

استقرار در دسته هدف تولید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.