ใช้ DAI Ad Break API

Google Dynamic Ad Insertion (DAI) Ad Break API ช่วยให้คุณสร้างและจัดการ ข้อมูลเวลาและการกำหนดเป้าหมายโฆษณาของช่วงพักโฆษณาในไลฟ์สดได้

คู่มือนี้ครอบคลุมการใช้ DAI Ad Break API เพื่อสร้าง อัปเดต และลบช่วงพักโฆษณาสำหรับกิจกรรมไลฟ์สด DAI ของ Google

ข้อกำหนดเบื้องต้น

หากต้องการใช้ DAI Ad Break API คุณต้องมีสิ่งต่อไปนี้

ตั้งค่าการเข้าถึง API

หากต้องการเปิดใช้ API ให้ทำตามขั้นตอนต่อไปนี้

  1. สร้างบัญชีบริการ ดูข้อมูลเพิ่มเติมได้ที่สร้างบัญชีบริการ
  2. เพิ่มบัญชีบริการลงในเครือข่าย Ad Manager ของ Google ดูข้อมูลเพิ่มเติมได้ที่เพิ่มผู้ใช้บัญชีบริการสำหรับการเข้าถึง API
  3. แจ้งอีเมลบัญชีบริการและรหัสเครือข่าย Google Ad Manager ให้ผู้จัดการฝ่ายดูแลลูกค้าของ Google ทราบ
  4. เปิดใช้ Google Ad Manager Video API ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ดูข้อมูลเพิ่มเติมได้ที่เปิดใช้ "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 เท่านั้น โดยไม่รวมช่วงพักโฆษณาที่สร้างจากไฟล์ Manifest, คำขอกลุ่มพ็อด หรือคำขอไฟล์ Manifest ของพ็อด

คำขอตัวอย่างต่อไปนี้แสดงรายการเอนทิตี 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 มากกว่า 1 รายการสำหรับกิจกรรมไลฟ์สดรายการเดียว โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อรับการกำหนดค่าขั้นสูง

คำขอตัวอย่างต่อไปนี้จะสร้างช่วงพักโฆษณาที่คาดว่าจะเริ่มในวันที่ 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 เพื่อดึงรายละเอียดของเอนทิตี 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

ดูฟีเจอร์ขั้นสูงของช่วงพักโฆษณา

หลังจากสร้างและจัดการช่วงพักโฆษณาแล้ว ให้สำรวจฟีเจอร์ต่อไปนี้ของ DAI Ad Break API