Authentication

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

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

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

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

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

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

تفعيل Ad Manager API

  1. فعِّل Ad Manager API في مشروع Google API Console Cloud.

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

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

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

حساب الخدمة

على Google Cloud

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

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

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

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

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

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

  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. اختَر المشروع الذي فعّلت فيه واجهة برمجة التطبيقات "مدير إعلانات Google"، إذا طُلب منك ذلك.

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

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

  5. املأ النموذج وانقر على إنشاء. يجب أن تحدّد التطبيقات التي تستخدم لغات وأُطر عمل مثل PHP وJava وPython وRuby و‎ .NET معرّفات موارد منتظمة لإعادة التوجيه معتمَدة. معرّفات الموارد المنتظمة (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 أو قيمة Bearer في عنوان HTTP Authorization. عند الإمكان، يُفضّل استخدام عنوان 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"