ממשק API להתראות על הפסקות למודעות ב-DAI

כשאתם משתמשים בפלטפורמת DAI של Google, כדאי לספק נתוני טירגוט ההפסקה הבאה למודעות בשידור חי/ליניארית. ההפסקה המוקדמת למודעות ממשק API של Notification (EABN) מאפשר להטמיע טירגוט ספציפי להפסקה באמצעות צמדי מפתח/ערך, שמאפשרים מדרגיות לקבלת החלטות לגבי מודעות בנפח גבוה בסטרימינג.

קריאות ל-EABN API חייבות לכלול את מפתח הנכס לצורך טירגוט ואת הערכים הצפויים משך ההפסקה הבאה. משך הזמן צריך להיות קרוב ככל האפשר למודעה עצמה את האורך המקסימלי של ההפסקה. אם משך הזמן הצפוי שנשלח קצר יותר מספק הפסקה למודעות, סוג המילוי של ההפסקה למודעות למילוי חוסרים (ברירת המחדל היא 'לוח ריק') משמש את שארית ההפסקה. אם משך הזמן הצפוי שנשלח ארוך יותר מההפסקה למודעות שצוינה. ההפסקה למודעות עשויה להיות מסתיים לפני שהמודעה הושלמה.

בנוסף לשדות החובה האלה אפשר גם לשלוח טירגוט בהתאמה אישית שם של תבנית של רצף מודעות להחלה, או נתוני SCTE35 Cue Out, אם זמינים.

דרישות מוקדמות

יצירה של חשבון שירות

כדי לגשת ל-EABN API, נדרש חשבון שירות ב-Google.

• אם יש לכם חשבון Google Cloud, אתם יכולים להשתמש במודול IAM כדי ליצור חשבון שירות. מידע נוסף זמין במאמר הבא: יצירה וניהול של חשבונות שירות
• אם אין לך חשבון Google Cloud, יש לך אפשרות ליצור חשבון שירות. מה-Google API Console, באמצעות השלבים הבאים:
  1. יוצרים פרויקט חדש או בוחרים פרויקט קיים.
  2. בדף Credentials, לוחצים על Manage service accounts.
  3. בדף Service accounts (חשבונות שירות), לוחצים על יצירת חשבון שירות.
  4. בדף Create service account, מזינים את פרטי החשבון. לאחר מכן לוחצים על יצירה.

אחרי שיוצרים חשבון שירות, מעתיקים את קובץ ה-JSON של החשבון מפתח, שישמש לאימות.

הפעלת EABN API

אחרי שיוצרים את חשבון השירות, צריך לבקש ממנהל החשבון להפעיל אותו ל-EABN API לחשבון הזה.

הפעלת DAI API

אחרי שמפעילים את EABN API בחשבון השירות, מפעילים את DAI API בחשבון:

1. בספריית Google API: מחפשים 'DAI API'.

2. בוחרים את ממשק DAI API ומפעילים אותו.

שימוש ב-EABN API

אפשר לשלוח קריאה ל-API של EABN באמצעות בקשות JSON/REST.

אימות

כדי לבצע קריאות מאומתות ל-EABN API, צריך ליצור שירות OAuth2 את פרטי הכניסה של החשבון באמצעות מפתח JSON מחשבון השירות שלכם, וההיקף https://www.googleapis.com/auth/video-ads מידע נוסף זמין במאמר הבא: שימוש ב-OAuth 2.0 לאפליקציות משרת לשרת.

חובה לכלול את אסימון האימות שיתקבל ככותרת אימות לכל אחד מהם ל-EABN API.

שליחת התראה על הפסקה מוקדמת למודעה

כדי לשלוח התראה על הפסקה מוקדמת למודעה, צריך לשלוח בקשת POST באמצעות: כתובת ה-URL וגוף הבקשה:

POST dai.googleapis.com/v1/adBreaks

גוף הבקשה

אובייקט
adBreak	חובה	אובייקט wrapper של מאפיינים של 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 נוסף, שמכיל את הטמעת המודעות הדינמיות הפנימית המזהה של ההפסקה למודעה שנוצרה בתוך הזרם.

דוגמה

בקשה

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)