שימוש ב-DAI Ad Break API

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

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

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

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

• פרויקט ב-Google Cloud שבו השירות admanagervideo.googleapis.com מופעל. מידע נוסף זמין במאמר יצירת פרויקט בענן.
• רשת Google Ad Manager עם אירוע שידור חי ב-Google DAI. מידע נוסף זמין במאמר בנושא הגדרת סטרימינג בשידור חי ל-DAI.

הגדרת גישה ל-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 לפי מפתח הנכס שנוצר על ידי המערכת עבור האירוע, או לפי מפתח הנכס המותאם אישית.

ה-API של הפסקות הפרסום ב-DAI מחזיר רק ישויות 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_SCHEDULED או BREAK_STATE_DECISIONED לכל אירוע שידור חי.

• כדי ליצור ישות 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, לפני שההפסקה למודעה מתחילה להציג מודעות.

זהירות: מחיקת הפסקה לפרסומות במצב BREAK_STATE_DECISIONED עלולה למנוע משרתי מודעות להציג מודעות, מה שיכול להשפיע לרעה על התקצוב ועל הפונקציות של מכסת התדירות בשרתי המודעות. מידע נוסף זמין במאמר בנושא הסבר על מחזור החיים של הפסקות למודעות

.

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

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:

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