از API پخش تبلیغات DAI استفاده کنید

رابط برنامه‌نویسی کاربردی پخش زنده DAI Ad Break به شما امکان می‌دهد داده‌های زمان‌بندی و هدف‌گیری تبلیغات مربوط به پخش زنده‌های خود را ایجاد، مدیریت کنید.

این راهنما نحوه استفاده از API پخش تبلیغات DAI را برای ایجاد، به‌روزرسانی و حذف یک تبلیغ کوتاه برای یک رویداد پخش زنده Google Dynamic Ads Insertion (DAI) پوشش می‌دهد.

پیش‌نیازها

برای استفاده از API مربوط به تبلیغات DAI، به موارد زیر نیاز دارید:

  • یک پروژه Google Cloud با سرویس admanagervideo.googleapis.com فعال. برای اطلاعات بیشتر، به ایجاد یک پروژه Cloud مراجعه کنید.
  • یک شبکه مدیریت تبلیغات گوگل (Google Ad Manager) با یک رویداد پخش زنده Google DAI. برای اطلاعات بیشتر، به «تنظیم پخش زنده برای DAI» مراجعه کنید.

تنظیم دسترسی API

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

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

احراز هویت با OAuth2

برای تأیید درخواست‌های API خود، مراحل زیر را انجام دهید:

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

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

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

در صورت موفقیت، توکن دسترسی زیر را مشاهده خواهید کرد:

ya29.c.c0ASRK0GYUYU0...

اولین درخواست را مطرح کنید

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

API مربوط به Ad Break مربوط به DAI فقط موجودیت‌های AdBreak را که از طریق API ایجاد می‌شوند، برمی‌گرداند و Ad Breakهای ایجاد شده از مانیفست، درخواست قطعه پاد یا درخواست مانیفست پاد را شامل نمی‌شود.

درخواست مثال زیر، موجودیت‌های 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 برای یک رویداد پخش زنده، برای پیکربندی پیشرفته با مدیر حساب خود تماس بگیرید.

درخواست نمونه زیر یک وقفه تبلیغاتی ایجاد می‌کند که انتظار می‌رود در تاریخ ۳ ژوئن ۲۰۲۵، ساعت ۱۵:۰۰:۰۰ 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 برای بازیابی جزئیات یک موجودیت خاص 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

از متد 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 را مشاهده خواهید کرد.

ویژگی‌های پیشرفته‌ی تبلیغات لحظه‌ای را بیاموزید

پس از ایجاد و مدیریت تبلیغات پراکنده، این ویژگی‌های API تبلیغات پراکنده DAI را بررسی کنید: