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

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

קריאות ל-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 מזינים את פרטי החשבון. לאחר מכן לוחצים על CREATE.

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

מפעילים את EABN API

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

הפעלת DAI API

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

  1. בספריית Google API, חפשו את 'DAI API'.

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

שימוש ב-EABN API

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

אימות

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

צריך לכלול את אסימון האימות שמתקבל ככותרת Auth לכל קריאה ל-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 נוסף, שמכיל את מזהה ה-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)