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

این راهنما به شما کمک می‌کند رویکرد اصالت‌سنجی مناسب را برای استقرار تولید Data Manager API انتخاب و پیکربندی کنید.

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

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

برای راهنمایی کلی درباره اصالت‌سنجی 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

  1. Workload Identity Federation for 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» را در مشخصات pod خود مشخص کنید:

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

درستی‌سنجی IAM و دسترسی به حساب

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

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

  2. دسترسی به حساب مقصد: به حساب سرویس دسترسی لازم را به حساب‌های مقصدتان اعطا کنید. برای دستورالعمل‌های گام‌به‌گام، راه‌اندازی دسترسی به حساب را ببینید.

حجم‌های کاری خارج از 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 برای اصالت‌سنجی غیرتعاملی و مدیریت کد دسترسی بدون امضای دستی کدها استفاده کنید:

  1. بااستفاده از فایل اطلاعات اعتباری پیکربندی‌شده در محیطتان، Google Cloud CLI را مجاز کنید:

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

  2. کد دسترسی تولیدشده را در سرصفحه 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 CLI به‌طور خودکار کد دسترسی را ذخیره می‌کند و آن را قبل‌از انقضا بازآوری می‌کند.

درستی‌سنجی IAM و دسترسی به حساب

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

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

  2. دسترسی به حساب مقصد: به حساب سرویس دسترسی لازم را به حساب‌های مقصدتان اعطا کنید. برای دستورالعمل‌های گام‌به‌گام، راه‌اندازی دسترسی به حساب را ببینید.

اقدام ازطرف کاربران

پلاتفرم‌های شخص ثالث مانند پلاتفرم‌ها و آژانس‌های بازاریابی اغلب نیاز دارند درخواست‌های API را ازطرف چندین تبلیغ‌کننده که برای سرویس آن‌ها ثبت‌نام می‌کنند ارسال کنند.

در این معماری، به‌جای استفاده از «اطلاعات اعتباری پیش‌فرض برنامه»، از جریان سرور وب OAuth 2.0 برای دریافت اطلاعات اعتباری کاربر با دسترسی آفلاین از هر تبلیغ‌کننده استفاده کنید، و سپس از آن اطلاعات اعتباری برای پیکربندی کتابخانه کارخواه در زمان اجرا براساس اینکه درخواست کدام حساب تبلیغ‌کننده را مدیریت می‌کند استفاده کنید.

پیاده‌سازی جریان وب OAuth 2.0

در اینجا نحوه راه‌اندازی واگذاری کاربر برای برنامه‌های چندمستأجری آورده شده است:

  1. درخواست دسترسی آفلاین: کاربران را به صفحه کسب رضایت OAuth در Google هدایت کنید و با access_type=offline و prompt=consent، حوزه https://www.googleapis.com/auth/datamanager را درخواست کنید. سرور شما کد مجوز را با کد دسترسی و refresh_token معاوضه می‌کند. برای دستورالعمل‌های گام‌به‌گام، OAuth 2.0 برای برنامه‌های وب سرور را ببینید.

  2. ذخیره کردن ایمن اطلاعات کاربری: ژتون بازآوری هر کاربر را به‌طور ایمن در فضای ذخیره‌سازی اطلاعات کاربری رمزگذاری‌شده مرتبط با حساب او در پلاتفرمتان ذخیره کنید.

  3. مقداردهی اولیه کتابخانه‌های کارخواه در زمان اجرا: هنگام ارسال درخواست 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 ارسال می‌کند و نیاز به ذخیره و نگهداری ژتون‌های بازآوری کاربر با عمر طولانی را ازبین می‌برد.

روال‌های مطلوب تولید

هنگام انتقال به تولید، این ملاحظات عملیاتی کلیدی را مرور کنید: