Early ad break notification

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

ملاحظة: لا تزال واجهة برمجة التطبيقات هذه في مرحلة الإصدار التجريبي. يُرجى التواصل مع مدير حسابك إذا أردت طلب الوصول إلى برنامج EABN.

تتيح لك واجهة برمجة التطبيقات الخاصة بميزة "الإشعار قبل الفاصل الإعلاني (EABN)" إعلام "مدير إعلانات Google" بالفاصل الإعلاني القادم ببياناته الوصفية قبل بدء الفاصل الإعلاني. يمكنك إرسال طلب إشعار قبل ساعة واحدة كحدّ أقصى من الفاصل الإعلاني. يشرح هذا الدليل طريقة تفعيل واجهة EABN API واستخدامها وعيّنات الطلبات والاستجابة.

تنبيه: طلبات EABN غير قابلة للتغيير، لذلك بعد إنشاء فاصل إعلاني، لا يمكن تعديله. ويتم رفض الطلبات اللاحقة لإنشاء فواصل إعلانية للحدث نفسه إلى أن يظهر الفاصل في بيان الحدث.

يجب أن تتضمّن الطلبات التي يتم إجراؤها إلى واجهة برمجة التطبيقات EABN API المعلومات التالية:

• معرّف البث المباشر المقابل الذي سيتم إنشاء الفاصل الإعلاني عليه. ويمكن أن يكون هذا المعرّف واحدًا مما يلي:
• "مفتاح مادة العرض" للبث المباشر
• "مفتاح مادة العرض المخصّص" للبث المباشر الذي يتيح لك إدارة مساحة المفتاح الخاص بك من خلال تحديد سلسلة المعرّف الخاصة بك
• "معرّف مصدر المحتوى" و"Content ID" للبث المباشر

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

• المدة المتوقّعة للفاصل الإعلاني التالي. ويجب أن تكون المدّة قريبة قدر الإمكان من مدة الفاصل الإعلاني الفعلي.

بالإضافة إلى هذه الحقول المطلوبة، يمكنك أيضًا إرسال مَعلمات استهداف مخصّصة، أو اسم نموذج مجموعة الإعلانات المتسلسلة المطلوب تطبيقها، أو بيانات رمز الخروج SCTE35، إن توفّرت.

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

لاستخدام واجهة برمجة التطبيقات EABN، يجب إنشاء حساب خدمة وإضافة الحساب إلى شبكة "مدير إعلانات Google".

إنشاء حساب خدمة

لإنشاء حساب خدمة لطلب واجهة برمجة التطبيقات EABN، أكمِل الخطوات التالية: إذا كان لديك حساب على Google Cloud، استخدِم وحدة "إدارة الهوية وإمكانية الوصول" لإنشاء حساب خدمة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء حسابات الخدمة وإدارتها. - إذا لم يكن لديك حساب على Google Cloud، أكمِل الخطوات التالية لإنشاء حساب من وحدة التحكم في واجهة Google API:

1. أنشِئ مشروعًا جديدًا أو اختَر مشروعًا حاليًا.
2. في صفحة بيانات الاعتماد، انقر على إدارة حسابات الخدمة.
3. في صفحة حسابات الخدمة، انقر على إنشاء حساب الخدمة.
4. في صفحة إنشاء حساب خدمة، أدخِل تفاصيل الحساب. بعد ذلك، انقر على إنشاء.

بعد إنشاء حساب الخدمة، انسخ مفتاح JSON للحساب الذي يُستخدم للمصادقة.

إضافة حساب الخدمة إلى شبكة "مدير إعلانات Google"

لإضافة حساب الخدمة إلى شبكتك، أكمِل الخطوات الواردة في مقالة إضافة مستخدم حساب خدمة للوصول إلى واجهة برمجة التطبيقات.

تفعيل واجهة برمجة التطبيقات

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

• عنوان البريد الإلكتروني لحسابك على Google Cloud
• حساب الخدمة
• رمز الشبكة لشبكة "مدير إعلانات Google".

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

1. في مكتبة Google API، ابحث عن "Google Ad Manager Video API".
2. انقر على تفعيل.

ملاحظة: إذا لم تظهر واجهة برمجة التطبيقات في نتائج البحث، تواصَل مع مدير حسابك للتأكّد من أنّه تم تفعيل واجهة برمجة التطبيقات DAI API في حسابك.

استخدام واجهة برمجة التطبيقات

يمكنك استدعاء واجهة برمجة التطبيقات EABN باستخدام طلبات JSON/REST.

التفويض

لإجراء مكالمات معتمَدة إلى واجهة برمجة التطبيقات EABN، يجب إنشاء بيانات اعتماد لحساب خدمة OAuth2 باستخدام مفتاح JSON من حساب الخدمة والنطاق https://www.googleapis.com/auth/video-ads. لمزيد من المعلومات، يُرجى الاطّلاع على استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم.

يجب تضمين رمز التفويض المميز الناتج كعنوان مصادقة لكل استدعاء لواجهة EABN API.

إرسال إشعار بالفاصل الإعلاني المبكر

لإرسال إشعار فاصل إعلاني مبكر، أرسِل طلب POST إلى أحد عناوين URL الثلاثة الصالحة لـ EABN، بناءً على الطريقة التي تفضّلها لتحديد البث المباشر. توضّح الأقسام التالية الفروق بين عناوين URL وتقدِّم أمثلة على الطلبات والردّ.

عناوين URL

هناك ثلاثة عناوين URL صالحة لإشعار الفاصل الإعلاني المبكر. يمكنك استخدام الأنواع الثلاثة لإنشاء فاصل إعلاني (POST) أو الحصول على قائمة الفواصل الإعلانية التي تم تعيينها (GET).

لاستخدام مفتاح مادة العرض لبث مباشر، استخدِم:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

لاستخدام مفتاح مادة العرض المخصّص للبث المباشر، يجب:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

لاستخدام أسلوب Content ID وContent ID، يجب:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

بالنسبة إلى جميع المعلمات:

• يمثل network_code رمز الشبكة لشبكتك على "مدير إعلانات Google".
• يمثّل asset_key مفتاح مادة العرض الذي يظهر في صفحة تفاصيل البث المباشر.
• يمثّل custom_asset_key مفتاح مادة العرض المخصّص للبث المباشر.
• يمثّل content_source_id معرّف مصدر المحتوى في "مدير إعلانات Google".
• يمثل content_id معرّف جزء من المحتوى في "مدير إعلانات Google".

ملاحظة: يجب ربط زوج content_source_id/content_id المحدّد ببث مباشر في "مدير إعلانات Google".

نص الطلب - يُستخدم فقط لإنشاء فاصل إعلاني (POST)

الكائن
expectedDuration	مطلوب	مدة هذا الفاصل الإعلاني، باستخدام تنسيق المدة العادية في Google (xx.xxxs يكون xx.xxx هو عدد الثواني).
customParams	اختياري	أزواج المفتاح/القيمة التي سيتم تضمينها في طلبات الإعلان لهذا الفاصل لاستهداف المعايير المخصّصة في AM360، مفصولةً حسب = وينضمان & . مثال: key=value&key2=value2,value3 لمزيد من المعلومات عن الاستهداف، اطّلِع على توفير مَعلمات استهداف لمصدر البيانات.
podTemplateName	اختياري	اسم نموذج مجموعة الإعلانات المتسلسلة
scte35CueOut	اختياري	بيانات بترميز Base-64 من إشارة scte35. يمكن أن تتضمن splice_insert() أو time_signal() الأمر. أمثلة: time_signal(): /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg== splice_insert(): /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

أمثلة على الطلبات

إنشاء فاصل إعلاني

POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}

نص الاستجابة

يحتوي نص الاستجابة على جميع المَعلمات المُرسَلة في العنصر adBreak، بالإضافة إلى حقل name إضافي يحتوي على رقم التعريف العادي على مستوى Google للفاصل الإعلاني الذي تم إنشاؤه. يتم عرض هذا الحقل بالتنسيق التالي:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}

مثال على إجابة

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}

تم تعيين الفواصل الإعلانية في القائمة

GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …

نص الاستجابة

يتضمّن نص الاستجابة الفواصل الإعلانية مع حقل breakState إضافي لكل فاصل إعلاني مخصّص للبث. يمكن إدخال القيم التالية في حقل breakState:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE

مثال على إجابة

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}