استخدام DAI Ad Break API

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

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

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

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

• مشروع على Google Cloud تم تفعيل خدمة admanagervideo.googleapis.com فيه لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء مشروع على السحابة الإلكترونية.
• شبكة "مدير إعلانات Google" تتضمّن حدث بث مباشر باستخدام "إعلانات البث المباشر من Google" لمزيد من المعلومات، يُرجى الاطّلاع على إعداد بث مباشر باستخدام ميزة "إدخال الإعلانات الديناميكي".

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

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

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_SCHEDULED أو BREAK_STATE_DECISIONED في كل مرة لكل حدث بث مباشر.

• لإنشاء عنصر 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 لإلغاء قرار الإعلان لفاصل إعلاني تم إنشاؤه من خلال واجهة برمجة التطبيقات قبل بدء عرض الفاصل الإعلاني.

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

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

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:

• لتحسين معدّل التعبئة والدمج مع أنظمة الإعلانات التابعة لجهات خارجية، اطّلِع على إتاحة استخدام علامات الإعلانات الديناميكية.
• إدارة مدة الفاصل الإعلاني ومدة المقطع