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

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

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

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

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

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

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

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

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

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