Authentication

يصف هذا المستند كيفية المصادقة على Ad Manager API. تعتمد طريقة المصادقة على الواجهة التي تستخدمها والبيئة التي يتم فيها تشغيل الرمز البرمجي، ولكن يجب أن تتضمّن جميع طلبات البيانات من واجهة برمجة التطبيقات رمز دخول مميزًا مع نطاق Ad Manager API.

تستخدم مكتبات عملاء "مدير إعلانات Google" بيانات الاعتماد التلقائية للتطبيق لإنشاء رموز الدخول باستخدام نطاقات Ad Manager API. يوضّح هذا الدليل كيفية ضبط "بيانات الاعتماد التلقائية للتطبيق".

إذا لم تكن تستخدم مكتبة عميل، عليك إنشاء بيانات اعتماد واستخدامها لمنح الإذن لطلباتك.

لمزيد من المعلومات حول المصادقة والتفويض، يُرجى الاطّلاع على دليل استخدام OAuth 2.0.

تحديد نوع المصادقة

نوع المصادقة الوصف
حساب الخدمة يُرجى تحديد هذا الخيار إذا أردت المصادقة كحساب مخصّص بدلاً من شخص معيّن.
مزيد من المعلومات
تطبيق الويب اختَر هذا الخيار إذا كنت تريد المصادقة كمستخدم يمنح الإذن لتطبيقك بالوصول إلى بياناته في "مدير الإعلانات".
مزيد من المعلومات
التطوير المحلي اختَر هذا الخيار إذا أردت المصادقة باستخدام حساب Google الخاص بك أو حساب خدمة من بيئة التطوير المحلية.

تفعيل Ad Manager API

  1. فعِّل Ad Manager API في مشروعك على السحابة الإلكترونية في Google API Console.

  2. اختَر مشروعًا أو أنشِئ مشروعًا جديدًا إذا طُلب منك ذلك.

إنشاء بيانات اعتماد

انقر على علامة التبويب الخاصة بنوع المصادقة واتّبِع التعليمات لإنشاء بيانات الاعتماد:

حساب الخدمة

على Google Cloud

لمصادقة عبء عمل قيد التشغيل على Google Cloud، يمكنك استخدام بيانات اعتماد حساب الخدمة المرتبط بمورد الحوسبة الذي يتم تشغيل الرمز البرمجي عليه.

على سبيل المثال، يمكنك إرفاق حساب خدمة بمثيل جهاز افتراضي (VM) في Compute Engine أو خدمة Cloud Run أو مهمة Dataflow. هذا النهج هو طريقة المصادقة المفضّلة للرموز البرمجية التي يتم تشغيلها على أحد موارد الحوسبة في Google Cloud.

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

على أجهزة الشركة أو على مقدّم خدمات سحابة إلكترونية مختلف

الطريقة المفضّلة لإعداد المصادقة من خارج Google Cloud هي استخدام Workload Identity federation، حيث يمكنك إنشاء ملف إعداد بيانات الاعتماد وضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS للإشارة إليه. هذه الطريقة أكثر أمانًا من إنشاء مفتاح حساب خدمة.

إذا لم تتمكّن من ضبط اتحاد Workload Identity، عليك إنشاء حساب خدمة ومفتاح له:

  1. افتح صفحة بيانات الاعتماد في Google API Console.

  2. في صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد، ثم على حساب الخدمة.

  3. انقر على عنوان البريد الإلكتروني لحساب الخدمة الذي تريد إنشاء مفتاح له.

  4. انقر على علامة التبويب المفاتيح.

  5. انقر على القائمة المنسدلة إضافة مفتاح، ثم اختَر إنشاء مفتاح جديد.

  6. اختَر JSON كـ نوع المفتاح وانقر على إنشاء.

  7. اضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف JSON.

‫Linux أو macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

تطبيق الويب

  1. افتح صفحة بيانات الاعتماد في Google API Console.

  2. اختَر المشروع الذي فعّلت فيه Ad Manager API إذا طُلب منك ذلك.

  3. في صفحة "بيانات الاعتماد"، انقر على إنشاء بيانات اعتماد، ثم على معرِّف عميل OAuth.

  4. اختَر نوع التطبيق تطبيق ويب.

  5. املأ النموذج وانقر على إنشاء. يجب أن تحدّد التطبيقات التي تستخدم لغات وأُطر عمل مثل PHP وJava وPython وRuby و‎ .NET معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المصرَّح بها. معرّفات الموارد المنتظمة (URI) لإعادة التوجيه هي نقاط النهاية التي يمكن لخادم OAuth 2.0 إرسال الردود إليها. يجب أن تلتزم نقاط النهاية هذه بقواعد التحقّق من Google.

  6. بعد إنشاء بيانات الاعتماد، نزِّل ملف client_secret.json. خزِّن الملف بأمان في مكان لا يمكن لأحد غير تطبيقك الوصول إليه.

من هنا، اتّبِع الخطوات للحصول على رموز الدخول عبر OAuth 2.0

التطوير المحلي

اضبط "بيانات الاعتماد التلقائية للتطبيق" (ADC) في بيئتك المحلية.

ثبِّت Google Cloud CLI، ثم ابدأه من خلال تشغيل الأمر التالي:

gcloud init

أنشئ بيانات اعتماد المصادقة المحلية لحساب Google واضبط رقم تعريف المشروع على مشروع تم فيه تفعيل Ad Manager API:

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/admanager"
gcloud auth application-default set-quota-project PROJECT_ID

بدلاً من ذلك، يمكنك المصادقة كحساب خدمة من خلال ضبط متغيّر البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف المفتاح.

‫Linux أو macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

ضبط إعدادات شبكة "إدارة الإعلانات"

حساب الخدمة

  1. انتقِل إلى شبكة "إدارة الإعلانات".
  2. انقر على علامة التبويب المشرف.
  3. تأكَّد من تفعيل الوصول إلى واجهة برمجة التطبيقات.
  4. انقر على الزر إضافة مستخدم حساب خدمة.
  5. املأ النموذج باستخدام عنوان البريد الإلكتروني لحساب الخدمة. يجب إضافة مستخدم حساب الخدمة إلى الأدوار والفِرق المناسبة لدمج واجهة برمجة التطبيقات.
  6. انقر على الزر حفظ. من المفترض أن تظهر رسالة تؤكّد إضافة حساب الخدمة.
  7. يمكنك الاطّلاع على مستخدمي حسابات الخدمة الحاليين من خلال الانتقال إلى علامة التبويب "المستخدمون"، ثم النقر على فلتر حساب الخدمة.

تطبيق الويب

  1. انتقِل إلى شبكة "إدارة الإعلانات".
  2. انقر على علامة التبويب المشرف.
  3. تأكَّد من تفعيل الوصول إلى واجهة برمجة التطبيقات.

التطوير المحلي

  1. انتقِل إلى شبكة "إدارة الإعلانات".
  2. انقر على علامة التبويب المشرف.
  3. تأكَّد من تفعيل الوصول إلى واجهة برمجة التطبيقات.

بدون مكتبة برامج

إذا لم تكن تستخدم مكتبة برامج، ننصحك بشدة باستخدام مكتبة OAuth2 للمصادقة.

للحصول على تعليمات مفصّلة حول الحصول على رموز الدخول، يُرجى الاطّلاع على مقالة استخدام OAuth2 مع Google APIs.

رموز الدخول

يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات من خلال تضمين إما معلَمة طلب البحث access_token أو قيمة عنوان HTTP Authorization Bearer. ويُفضَّل استخدام عنوان HTTP عندما يكون ذلك ممكنًا، لأنّ سلاسل طلبات البحث تظهر عادةً في سجلّات الخادم.

على سبيل المثال:

GET /v1/networks/1234
Host: admanager.googleapis.com
Authorization: Bearer ya29.a0Ad52N3_shYLX

GET https://admanager.googleapis.com/v1/networks/1234?access_token=1/fFAGRNJru1FTz70BzhT3Zg

النطاق

يرتبط كل رمز مميّز للوصول بنطاق واحد أو أكثر. يتحكّم النطاق في مجموعة الموارد والعمليات التي يسمح بها رمز الدخول. تتضمّن Ad Manager API نطاقَين. ننصحك باستخدام نطاق admanager.readonly الأضيق إذا لم يكن تطبيقك بحاجة إلى كتابة البيانات.

النطاق الأذونات
https://www.googleapis.com/auth/admanager عرض حملاتك وإدارتها على "إدارة إعلانات Google"
https://www.googleapis.com/auth/admanager.readonly الاطّلاع على حملاتك وبياناتك على "إدارة إعلانات Google"