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

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

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

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

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

أعباء العمل في Google Cloud: بالنسبة إلى أعباء العمل المبرمَجة (مثل مسارات الاستخراج والتحويل والتحميل أو مهام الدفعات أو خدمات الخلفية) التي تعمل على Compute Engine أو Cloud Run أو Cloud Functions أو GKE، استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC) مع حساب خدمة مرفق أو Workload Identity في 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

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

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

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

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

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

أعباء العمل خارج 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 للمصادقة وإدارة رموز الدخول بشكل غير تفاعلي بدون توقيع الرموز يدويًا:

امنح الإذن لواجهة سطر الأوامر في Google Cloud باستخدام ملف بيانات الاعتماد الذي تم ضبطه في بيئتك:
```
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 CLI رمز الدخول مؤقتًا تلقائيًا وتُعيد تحميله قبل انتهاء صلاحيته.

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

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

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

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

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

في هذه البنية، بدلاً من استخدام "بيانات الاعتماد التلقائية للتطبيق"، استخدِم مسار خادم الويب OAuth 2.0 للحصول على بيانات اعتماد المستخدم مع إمكانية الوصول بلا إنترنت من كل معلِن، ثم استخدِم بيانات الاعتماد هذه لضبط مكتبة العميل في وقت التشغيل استنادًا إلى حساب المعلِن الذي يديره الطلب.

تنفيذ مسار OAuth 2.0 على الويب

في ما يلي كيفية إعداد تفويض المستخدمين للتطبيقات المتعددة المستأجرين:

طلب التشغيل بلا إنترنت: يمكنك توجيه المستخدمين إلى شاشة طلب الموافقة في OAuth من Google لطلب نطاق https://www.googleapis.com/auth/datamanager باستخدام access_type=offline وprompt=consent. يستبدل الخادم رمز التفويض برمز مميّز للوصول وrefresh_token. للحصول على تعليمات مفصّلة، يُرجى الاطّلاع على OAuth 2.0 لتطبيقات خادم الويب.
تخزين بيانات الاعتماد بأمان: يجب تخزين الرمز المميز لإعادة التحميل لكل مستخدم بأمان في وحدة تخزين بيانات اعتماد مشفّرة مرتبطة بحسابه على منصتك.

بدء مكتبات البرامج في وقت التشغيل: عند إرسال طلب بيانات من واجهة برمجة التطبيقات نيابةً عن مستخدم معيّن، أنشئ بيانات اعتماد المستخدم من الرمز المميز لإعادة التحميل الذي خزّنته للمستخدم ومعرّف العميل وسر العميل لتطبيقك، وأدخِلها عند بدء العميل:

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 المميّزة لكل مستخدم من أجل نقل البيانات بشكل مستمر.

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

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

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

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

النشر في قناة الإصدار العلني تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

أعباء العمل في Google Cloud

Compute Engine

Cloud Run

وظائف السحابة الإلكترونية

GKE

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

أعباء العمل خارج Google Cloud

المجموعة GOOGLE_APPLICATION_CREDENTIALS

‫Linux / macOS

‫Windows ‏ (PowerShell)

‫Docker / الحاويات

Kubernetes

مصادقة طلبات REST وcurl

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

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

تنفيذ مسار OAuth 2.0 على الويب

NET.

Go

جافا

Node.js

PHP

Python

Ruby

إكمال عملية التحقّق من تطبيق OAuth

بديل: روابط الشركاء

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

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

المجموعة `GOOGLE_APPLICATION_CREDENTIALS`