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

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

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

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

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

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

للوصول إلى EABN API، يجب أن يكون لديك حساب على خدمة Google.

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

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

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

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

تفعيل DAI API

بعد تفعيل EABN API لحساب الخدمة، فعِّل DAI API على الحساب:

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

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

استخدام EABN API

يمكنك استدعاء واجهة برمجة تطبيقات 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.xxx حيث يشير 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
}

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

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)