استفاده از DAI Ad Break API

میانای Google Dynamic Ad Insertion (DAI) Ad Break API به شما امکان می‌دهد داده‌های زمان‌بندی و هدف‌یابی آگهی را برای وقفه‌های آگهی در جاری‌سازی‌های زنده خود ایجاد و مدیریت کنید.

این راهنما استفاده از «میانای برنامه‌سازی کاربردی وقفه آگهی DAI» برای ایجاد، به‌روزرسانی، و حذف وقفه آگهی برای رویداد جاری‌سازی زنده Google DAI را پوشش می‌دهد.

پیش‌نیازها

برای استفاده از «میانای برنامه‌سازی کاربردی وقفه آگهی DAI»، به موارد زیر نیاز دارید:

• پروژه Google Cloud با سرویس admanagervideo.googleapis.com فعال. برای اطلاعات بیشتر، ایجاد پروژه Cloud را ببینید.
• شبکه Google Ad Manager با رویداد جاری‌سازی زنده Google DAI. برای اطلاعات بیشتر، به راه‌اندازی جاری‌سازی زنده برای DAI مراجعه کنید.

راه‌اندازی دسترسی میانای برنامه‌سازی کاربردی

برای فعال کردن API، مراحل زیر را تکمیل کنید:

1. حساب سرویس ایجاد کنید. برای اطلاعات بیشتر، ایجاد حساب سرویس را ببینید.
2. حساب سرویس را به شبکه Google Ad Manager خود اضافه کنید. برای اطلاعات بیشتر، افزودن کاربر حساب خدمات برای دسترسی به API را ببینید.
3. نشانی ایمیل حساب سرویس و کد شبکه Google Ad Manager خود را به مدیر حساب Google خود ارائه دهید.
4. «میانای برنامه‌سازی کاربردی ویدیو Google Ad Manager» را در پروژه Google Cloud خود فعال کنید. برای اطلاعات بیشتر، فعال کردن «میاناهای برنامه‌سازی کاربردی و سرویس‌ها» برای برنامه را ببینید.

اصالت‌سنجی با OAuth2

برای مجاز کردن درخواست‌های «میانای برنامه‌سازی کاربردی»، مراحل زیر را انجام دهید:

1. کد دسترسی را با محدوده https://www.googleapis.com/auth/video-ads تولید کنید.
2. در هر درخواست، کد دسترسی به API را به‌عنوان مقدار Authorization سرایند HTTP Bearer اضافه کنید. برای اطلاعات بیشتر، به فراخوانی میاناهای برنامه‌سازی کاربردی Google مراجعه کنید.

مثال زیر یک کد OAuth با محدوده DAI Ad Break API تولید می‌کند:

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

اگر موفقیت‌آمیز باشد، کد دسترسی زیر را می‌بینید:

ya29.c.c0ASRK0GYUYU0...

اولین درخواست را انجام دهید

برای بازیابی وقفه‌های آگهی برای یک رویداد جاری‌سازی زنده، از روش GET برای فهرست کردن همه AdBreak نهادها براساس کلید دارایی تولیدشده توسط سیستم رویداد یا کلید دارایی سفارشی استفاده کنید.

«میانای برنامه‌سازی کاربردی وقفه آگهی DAI» فقط AdBreak نهاد را که ازطریق میانای برنامه‌سازی کاربردی ایجاد شده‌اند برمی‌گرداند، و وقفه‌های آگهی ایجادشده از مانیفست، درخواست بخش واحد آگهی، یا درخواست مانیفست واحد آگهی را برنمی‌گرداند.

درخواست نمونه زیر 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"
}

ایجاد نهاد «وقفه آگهی»

برای اطلاع دادن به Google DAI درباره یک وقفه آگهی آتی برای یک رویداد جاری‌سازی زنده، از روش POST استفاده کنید.

• برای ایجاد نهاد AdBreak جدید، باید منتظر بمانید تا نهاد قبلی به حالت BREAK_STATE_COMPLETE انتقال یابد.
• یا می‌توانید نهاد AdBreak معلقه را حذف کنید تا بتوانید نهاد جدیدی ایجاد کنید.
• برای ایجاد بیش از یک نهاد AdBreak برای یک رویداد جاری‌سازی زنده، برای پیکربندی پیشرفته با مدیر حسابتان تماس بگیرید.

درخواست نمونه زیر یک وقفه آگهی ایجاد می‌کند که انتظار می‌رود در تاریخ ۳ ژوئن ۲۰۲۵ ساعت ۱۵:۰۰:۰۰ به وقت ساعت هماهنگ جهانی شروع شود:

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 است.

بازیابی نهاد «وقفه آگهی»

از روش GET برای بازیابی جزئیات یک نهاد 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"
}

به‌روزرسانی کردن نهاد «وقفه آگهی»

برای اصلاح وقفه آگهی آتی قبل‌از شروع تصمیم آگهی، از روش 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"
}

حذف کردن نهاد «وقفه آگهی»

از روش 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» را کاوش کنید:

• برای ملغی کردن پارامترهای برچسب آگهی برای یک وقفه آگهی، یا ادغام با سیستم‌های آگهی طرف سوم، به استفاده از پارامترهای وقفه آگهی مراجعه کنید.
• برای جلوگیری از خطاهای بازپخش مربوط به آگهی، به مدیریت مدت زمان وقفه آگهی و بخش مراجعه کنید.