שימוש ב-DAI Ad Break API

‫Google Dynamic Ad Insertion (DAI) Ad Break API מאפשר לכם ליצור ולנהל את התזמון ואת נתוני טירגוט המודעות של הפסקות למודעה בשידורים החיים שלכם.

במדריך הזה מוסבר איך להשתמש ב-API של הפסקות למודעות ב-DAI כדי ליצור, לעדכן ולמחוק הפסקה למודעה באירוע שידור חי ב-DAI של Google.

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

כדי להשתמש ב-DAI Ad Break API, אתם צריכים:

הגדרת גישה ל-API

כדי להפעיל את ה-API, מבצעים את השלבים הבאים:

  1. יוצרים חשבון שירות. מידע נוסף מופיע במאמר יצירת חשבון שירות.
  2. מוסיפים את חשבון השירות לרשת Google Ad Manager. מידע נוסף זמין במאמר בנושא הוספת משתמש לחשבון שירות לצורך גישה ל-API.
  3. צריך לספק לנציג של חשבון Google שמטפל בך את כתובת האימייל של חשבון השירות ואת הקוד של רשת Google Ad Manager.
  4. מפעילים את Google Ad Manager Video API בפרויקט בענן ב-Google Cloud. מידע נוסף מופיע במאמר הפעלה של 'ממשקי API ושירותים' באפליקציה.

אימות באמצעות OAuth2

כדי לתת הרשאה לבקשות API, פועלים לפי השלבים הבאים:

  1. יוצרים את אסימון הגישה עם ההיקף https://www.googleapis.com/auth/video-ads.
  2. בכל בקשה, צריך לכלול את אסימון הגישה ל-API כערך של Authorizationכותרת HTTPBearer. מידע נוסף מופיע במאמר קריאה לממשקי Google API.

בדוגמה הבאה נוצר אסימון OAuth עם היקף DAI Ad Break API:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

אם הפעולה בוצעה בהצלחה, יוצג טוקן הגישה הבא:

ya29.c.c0ASRK0GYUYU0...

שליחת הבקשה הראשונה

כדי לאחזר הפסקות פרסומות לאירוע בשידור חי, משתמשים בשיטה GET כדי להציג רשימה של כל הישויות AdBreak לפי מפתח הנכס שנוצר על ידי המערכת עבור האירוע, או לפי מפתח הנכס המותאם אישית.

‫DAI Ad Break API מחזיר רק ישויות AdBreak שנוצרו דרך ה-API, לא כולל הפסקות למודעה שנוצרו מתוך מניפסט, בקשה לפלח של רצף מודעות או בקשה למניפסט של רצף מודעות.

בדוגמה הבאה מוצגת בקשה לרשימת ישויות AdBreak לפי ערך assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

אם הפעולה בוצעה ללא שגיאות, תופיע תגובת ה-JSON הבאה:

{
 "adBreaks": []
}

כשיוצרים עוד ישויות AdBreak דרך ה-API ומבקשים את הרשימה, מקבלים את תגובת ה-JSON הבאה:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_SCHEDULED"
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate",
      "breakState": "BREAK_STATE_COMPLETE"
    },
    ...
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

יצירה של ישות AdBreak

כדי לעדכן את Google DAI על הפסקת פרסום קרובה באירוע בשידור חי, משתמשים בשיטה POST.

  • כדי ליצור ישות AdBreak חדשה, צריך לחכות שהקודמת תעבור למצב BREAK_STATE_COMPLETE.
  • אפשרות אחרת היא למחוק את הישות AdBreak בהמתנה כדי ליצור ישות חדשה.
  • כדי ליצור יותר מישות אחת של AdBreak לאירוע שידור חי יחיד, צריך לפנות למנהל החשבון כדי לקבל עזרה בהגדרות מתקדמות.

בדוגמה הבאה, הבקשה יוצרת הפסקת פרסום שאמורה להתחיל ב-3 ביוני 2025 בשעה 15:00:00 UTC:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

אם הפעולה בוצעה ללא שגיאות, תופיע תגובת ה-JSON הבאה:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

התוצאה מכילה את מזהה ההפסקה למודעות שנדרש לאחזור, לשינוי או למחיקה של ההפסקה למודעות. בדוגמה לתשובה, מזהה ההפסקה למודעה שנוצר הוא bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

אחזור של ישות AdBreak

משתמשים ב-GET method כדי לאחזר את הפרטים של ישות AdBreak ספציפית, כולל מטא-נתונים של מצב ההפסקה למודעות ותזמון.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

אם הפעולה בוצעה ללא שגיאות, תופיע תגובת ה-JSON הבאה:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

עדכון של ישות AdBreak

כדי לשנות הפסקה למודעה עתידית לפני שההחלטה לגבי המודעה מתחילה, משתמשים בשיטה PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

אם הפעולה בוצעה ללא שגיאות, תופיע תגובת ה-JSON הבאה:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate",
  "breakState": "BREAK_STATE_SCHEDULED"
}

מחיקה של ישות AdBreak

משתמשים ב-method‏ DELETE כדי לבטל את ההחלטה לגבי מודעה בהפסקה למודעה שנוצרה באמצעות API, לפני שההפסקה למודעה מתחילה להציג מודעות.

בדוגמה הבאה מוצגת בקשה למחיקת הפסקה למודעה:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

אם הפעולה בוצעה ללא שגיאות, תופיע התגובה HTTP/1.1 200 OK.

מידע על תכונות מתקדמות של הפסקות למודעות

אחרי שיוצרים ומנהלים הפסקות למודעות, אפשר להשתמש בתכונות הבאות של DAI Ad Break API: