النشر في قناة الإصدار العلني

يساعدك هذا الدليل في اختيار طريقة المصادقة المناسبة وضبطها لنشر واجهة Data Manager API في بيئة الإنتاج.

اختيار سيناريو النشر

اختَر طريقة المصادقة التي تتوافق مع بنية تطبيقك وبيئة النشر:

للحصول على إرشادات عامة حول المصادقة في 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

  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 في مواصفات مجموعة الإعدادات:

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

التحقّق من "إدارة الهوية وإمكانية الوصول" والوصول إلى الحساب

قبل نشر تطبيقك في قناة الإصدار العلني، تأكَّد من أنّ حساب الخدمة لديه الأذونات اللازمة:

  1. أذونات Google Cloud IAM: امنح حساب الخدمة دور مستهلك استخدام الخدمة (roles/serviceusage.serviceUsageConsumer) في مشروع على السحابة الإلكترونية حيث تم تفعيل 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 متاحة، يمكنك إنشاء مفتاح حساب خدمة وتقديمه إلى "بيانات الاعتماد التلقائية للتطبيق" باستخدام متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS.

المجموعة 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 / الحاويات

ثبِّت ملف بيانات الاعتماد في الحاوية واضبط متغيّر البيئة:

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 باستخدام ملف بيانات الاعتماد الذي تم ضبطه في بيئتك:

    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 رمز الدخول مؤقتًا تلقائيًا وتُعيد تحميله قبل انتهاء صلاحيته.

التحقّق من "إدارة الهوية وإمكانية الوصول" والوصول إلى الحساب

قبل نشر تطبيقك في قناة الإصدار العلني، تأكَّد من أنّ حساب الخدمة لديه الأذونات اللازمة:

  1. أذونات Google Cloud IAM: امنح حساب الخدمة دور مستهلك استخدام الخدمة (roles/serviceusage.serviceUsageConsumer) في مشروع على السحابة الإلكترونية حيث تم تفعيل Data Manager API.

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

  2. الوصول إلى حساب الوجهة: امنح حساب الخدمة إذن الوصول المطلوب إلى حسابات الوجهة. للحصول على تعليمات مفصّلة، يُرجى الاطّلاع على مقالة إعداد إمكانية الوصول إلى الحساب.

التصرّف نيابةً عن المستخدمين

غالبًا ما تحتاج المنصات التابعة لجهات خارجية، مثل المنصات والوكالات التسويقية، إلى إرسال طلبات بيانات من واجهة برمجة التطبيقات نيابةً عن عدة معلنين يشتركون في خدماتها.

في هذه البنية، بدلاً من استخدام "بيانات الاعتماد التلقائية للتطبيق"، استخدِم مسار خادم الويب 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. تهيئة مكتبات العميل في وقت التشغيل: عند إرسال طلب بيانات من واجهة برمجة التطبيقات نيابةً عن مستخدم معيّن، أنشئ بيانات اعتماد المستخدم من الرمز المميز لإعادة التحميل الذي خزّنته للمستخدم ومعرّف العميل وسر العميل لتطبيقك، وأرسِلها عند تهيئة العميل:

    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))

    جافا

    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 Console، يمكن فقط لحسابات الاختبار المحدّدة منح الإذن لتطبيقك.
  • الإصدار العلني: قبل إتاحة تطبيقك للمستخدمين الخارجيين، اضبط حالة النشر على في مرحلة الإنتاج وأرسِل التطبيق لإثبات ملكيته.

لا يلزم التحقّق من التطبيقات لأعباء العمل التي يتم تشغيلها باستخدام حسابات الخدمة. بالإضافة إلى ذلك، هناك بعض الاستثناءات لسيناريوهات مثل التطبيقات الداخلية. يُرجى الاطّلاع على الحالات التي لا تتطلّب إثبات الهوية لمزيد من التفاصيل.

إذا كانت مؤسستك شريك بيانات معتمَدًا، يمكنك استخدام روابط الشركاء بدلاً من إدارة رموز OAuth المميّزة لكل مستخدم من أجل نقل البيانات المستمر.

من خلال روابط الشركاء، يربط المعلِنون حساباتهم بحساب شريك البيانات في واجهة مستخدم "إعلانات Google" أو "مساحة العرض والفيديو 360" أو "مدير إعلانات Google". بعد إنشاء الرابط، يرسل تطبيقك طلبات نقل البيانات باستخدام بيانات اعتماد حساب الخدمة الخاص بك من خلال ADC، ما يجنّبك الحاجة إلى تخزين الرموز المميزة لإعادة التحميل الخاصة بالمستخدمين والاحتفاظ بها لفترة طويلة.

أفضل الممارسات المتعلّقة بالإنتاج

راجِع هذه الاعتبارات التشغيلية الرئيسية عند الانتقال إلى مرحلة الإنتاج: