استخدام DAI Ad Break API

تتيح لك واجهة برمجة التطبيقات "إدراج إعلان ديناميكي" إنشاء بيانات الفواصل الإعلانية وإدارتها وتحديد توقيتها واستهداف الإعلانات في البث المباشر.

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

المتطلبات الأساسية

لاستخدام واجهة برمجة التطبيقات "فواصل إعلانية في DAI"، يجب استيفاء الشروط التالية:

إعداد إذن الوصول إلى واجهة برمجة التطبيقات

لتفعيل واجهة برمجة التطبيقات، أكمِل الخطوات التالية:

  1. أنشئ حساب خدمة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء حساب خدمة.
  2. أضِف حساب الخدمة إلى شبكة "إدارة إعلانات Google". لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إضافة مستخدم لحساب خدمة للوصول إلى واجهة برمجة التطبيقات.
  3. قدِّم عنوان البريد الإلكتروني لحساب الخدمة ومعرِّف شبكة "مدير إعلانات Google" إلى مدير حسابات في Google.
  4. فعِّل Google Ad Manager Video API في مشروعك على Google Cloud. لمزيد من المعلومات، اطّلِع على مقالة تفعيل "واجهات برمجة التطبيقات والخدمات" لتطبيقك.

المصادقة باستخدام OAuth2

للسماح بطلبات واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

  1. أنشئ رمز الدخول باستخدام النطاق https://www.googleapis.com/auth/video-ads.
  2. في كل طلب، أدرِج رمز الدخول إلى واجهة برمجة التطبيقات كقيمة Authorization لعنوان HTTP Bearer. لمزيد من المعلومات، يُرجى الاطّلاع على طلب بيانات من واجهات Google APIs.

ينشئ المثال التالي رمز OAuth مميزًا باستخدام نطاق DAI Ad Break API:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

في حال نجاح العملية، سيظهر لك رمز الدخول التالي:

ya29.c.c0ASRK0GYUYU0...

تقديم الطلب الأول

لاسترداد فواصل إعلانية لحدث بث مباشر، استخدِم الطريقة GET لعرض جميع عناصر AdBreak حسب مفتاح العنصر الذي ينشئه النظام للحدث أو مفتاح العنصر المخصّص.

لا تعرض واجهة برمجة التطبيقات "فواصل إعلانية في DAI" سوى عناصر AdBreak التي يتم إنشاؤها من خلال واجهة برمجة التطبيقات، باستثناء الفواصل الإعلانية التي يتم إنشاؤها من ملف البيان أو طلب مقطع الفيديو أو طلب ملف البيان.

يعرض طلب المثال التالي قائمة بكيانات AdBreak حسب قيمة assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

في حال نجاح العملية، ستظهر لك استجابة JSON التالية:

{
 "adBreaks": []
}

عند إنشاء كيانات AdBreak إضافية من خلال واجهة برمجة التطبيقات وطلب القائمة، ستظهر لك استجابة JSON التالية:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_SCHEDULED",
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_COMPLETE",
    },
    …
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

إنشاء كيان AdBreak

لإعلام Google DAI بفاصل إعلاني قادم لحدث بث مباشر، استخدِم الطريقة POST.

  • لإنشاء عنصر AdBreak جديد، عليك الانتظار إلى أن ينتقل العنصر السابق إلى الحالة BREAK_STATE_COMPLETE.
  • يمكنك بدلاً من ذلك حذف كيان AdBreak في انتظار المراجعة لإنشاء كيان جديد.
  • لإنشاء أكثر من AdBreak كيان لحدث بث مباشر واحد، يُرجى التواصل مع مدير حسابك للحصول على إعدادات متقدّمة.

ينشئ طلب المثال التالي استراحة إعلانية من المتوقّع أن تبدأ في 3 يونيو 2025 الساعة 15:00:00 بالتوقيت العالمي المتفق عليه:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/{NETWORK_CODE}/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

في حال نجاح العملية، ستظهر لك استجابة JSON التالية:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

تحتوي النتيجة على معرّف الفاصل الإعلاني المطلوب لاسترداد الفاصل الإعلاني أو تعديله أو حذفه. في مثال الردّ، يكون رقم تعريف فاصل الإعلانات الذي تم إنشاؤه هو bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

استرداد كيان AdBreak

استخدِم طريقة GET لاسترداد تفاصيل عنصر AdBreak معيّن، بما في ذلك البيانات الوصفية الخاصة بحالة الفاصل الإعلاني وتوقيته.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

في حال نجاح العملية، ستظهر لك استجابة JSON التالية:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

تعديل كيان AdBreak

لتعديل فاصل إعلاني قادم قبل بدء عملية اتّخاذ قرار عرض الإعلان، استخدِم طريقة PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

في حال نجاح العملية، ستظهر لك استجابة JSON التالية:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

حذف كيان AdBreak

استخدِم الطريقة DELETE لإلغاء قرار الإعلان لفاصل إعلاني تم إنشاؤه من خلال واجهة برمجة التطبيقات قبل أن يبدأ عرض الفاصل الإعلاني.

يحذف طلب المثال التالي فاصلًا إعلانيًا:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

في حال نجاح العملية، ستظهر لك الاستجابة HTTP/1.1 200 OK.

التعرّف على ميزات فواصل الإعلانات المتقدّمة

بعد إنشاء فواصل إعلانية وإدارتها، يمكنك استكشاف الميزات التالية في واجهة برمجة التطبيقات الخاصة بالفواصل الإعلانية في DAI: