استخدام DAI Ad Break API

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

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

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

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

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

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

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

• لإلغاء معلَمات علامات الإعلانات لفاصل إعلاني أو الدمج مع أنظمة إعلانات تابعة لجهات خارجية، يُرجى الاطّلاع على استخدام معلَمات الفواصل الإعلانية.
• لمنع أخطاء التشغيل المرتبطة بالإعلانات، يُرجى الاطّلاع على مقالة إدارة مدة الفواصل الإعلانية ومدة المقاطع.