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

عند استخدام منصة DAI في Google، قد تحتاج إلى تقديم بيانات استهداف الفاصل الإعلاني القادم الخطي أو القادم في مجموعة بث. الفاصل الإعلاني المبكر تتيح لك واجهة برمجة التطبيقات Notification (EABN) تنفيذ استهداف الفواصل الإعلانية باستخدام أزواج المفتاح/القيمة، والتي توفر قابلية التوسع لاتخاذ قرارات بشأن الإعلانات في الأعداد الكبيرة جداول البيانات.

يجب أن تتضمّن الطلبات التي يتم إجراؤها إلى EABN API مفتاح مادة العرض المطلوب استهدافه لمدة الفاصل التالي. يجب أن تكون المدة أقرب إلى الإعلان الفعلي. طول الفاصل قدر الإمكان. إذا كانت المدة المتوقعة للإرسال أقصر من والفاصل الإعلاني المقدّم نوع تعبئة الفواصل الإعلانية التي تحتوي على إعلانات غير مكتملة ويتم استخدام (القيم الافتراضية على عنصر حاجب فارغ) خلال بقية الفاصل. إذا كانت المدة المتوقّعة المُرسَلة أطول من الفاصل الإعلاني المحدَّد، لذا قد النهاية قبل اكتمال الإعلان.

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

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

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

للوصول إلى واجهة برمجة التطبيقات EABN، يجب أن يكون لديك حساب على خدمة Google.

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

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

تفعيل واجهة EABN API

بعد إنشاء حساب الخدمة، اطلب من مدير الحساب تفعيل الميزة. واجهة برمجة تطبيقات EABN لهذا الحساب.

تفعيل DAI API

بعد تفعيل واجهة EABN API لحساب الخدمة، فعِّل واجهة برمجة التطبيقات DAI API. في الحساب:

  1. في مكتبة Google API، ابحث عن "DAI API".

  2. اختَر DAI API وفعِّلها.

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

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

المصادقة

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

يجب أن يتضمن رمز المصادقة المميز الناتج كعنوان مصادقة لكل واجهة برمجة تطبيقات EABN.

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

لإرسال إشعار فاصل إعلاني مبكر، أرسِل طلب POST باستخدام ما يلي: عنوان URL ونص الطلب:

POST dai.googleapis.com/v1/adBreaks

نص الطلب

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

عنوان الاستجابة

HTTP/1.1 200 OK

نص الاستجابة

يحتوي نص الاستجابة على جميع المعلَمات المرسَلة في الكائن adBreak، بالإضافة إلى حقل daiBreakId إضافي يحتوي على إدراج DAI الداخلي. المعرّف للفاصل الإعلاني الذي تمّ إنشاؤه ضمن البث.

مثال

الطلب

POST /v1/adBreaks HTTP/1.1
Content-Type: application/json

{
  "adBreak": {
    "assetKey": "asset1",
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "custParams": "param1=value1&param2=value2",
    "ptpln": "podtemplate"
  }
}

الرد

HTTP/1.1 200 OK

{
  "assetKey": "asset1",
  "expectedDuration": "30s",
  "custParams": "param1=value1&param2=value2",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "ptpln": "podtemplate",
  "daiBreakId": 1
}

نموذج من التنفيذ (بايثون)

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

from absl import app

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

SERVICE_ACCOUNT_KEY_FILE = "~/eabn_key.json"
ASSET_KEY = "asset1"

SCOPES = ['https://www.googleapis.com/auth/video-ads']
EABN_API_URL = 'https://dai.googleapis.com/v1/adBreaks'


def main():
  credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_KEY_FILE, scopes=SCOPES)

  authed_session = AuthorizedSession(credentials)

  data = {
      'assetKey': ASSET_KEY,
      'expectedDuration': '120s',
      'custParams': 'param1=value1&param2=value2',
      'scte35CueOut': '/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==',
  }

  r = authed_session.post(EABN_API_URL, json={'adBreak': data})
  print(r.status_code)
  print(r.headers)
  print(r.text)

if __name__ == '__main__':
  app.run(main)