Early ad break notification

การใช้ API การแจ้งเตือนช่วงพักโฆษณาล่วงหน้า

หมายเหตุ: API นี้ยังอยู่ในรุ่นเบต้า โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าหากต้องการขอสิทธิ์เข้าถึงโปรแกรม EABN

API การแจ้งเตือนช่วงพักโฆษณาตอนต้น (EABN) ช่วยให้คุณแจ้ง Google Ad Manager เกี่ยวกับช่วงพักโฆษณาที่กำลังจะมาถึงด้วยข้อมูลเมตาก่อนเริ่มช่วงพักโฆษณา คุณส่งคำขอการแจ้งเตือนก่อนช่วงพักโฆษณาได้สูงสุด 1 ชั่วโมง คำแนะนำนี้จะอธิบายวิธีเปิดใช้และใช้ EABN API รวมถึงตัวอย่างคำขอและการตอบกลับ

ข้อควรระวัง: คำขอ EABN จะเปลี่ยนแปลงไม่ได้ ดังนั้นเมื่อสร้างช่วงพักแล้ว จะแก้ไขไม่ได้ คำขอเพื่อสร้างช่วงพักโฆษณาที่ตามมาสำหรับเหตุการณ์เดียวกันจะถูกปฏิเสธจนกว่าช่วงพักโฆษณาจะปรากฏในไฟล์ Manifest ของเหตุการณ์นั้น

การเรียก EABN API ต้องมีข้อมูลต่อไปนี้

  • ตัวระบุของสตรีมแบบสดที่เกี่ยวข้องซึ่งกำลังสร้างช่วงพักโฆษณา ตัวระบุนี้อาจมีลักษณะอย่างใดอย่างหนึ่งต่อไปนี้
  • "คีย์เนื้อหา" ของสตรีมแบบสด
  • "คีย์เนื้อหาที่กำหนดเอง" ของสตรีมแบบสด ซึ่งจะช่วยให้คุณจัดการพื้นที่คีย์ของคุณเองโดยระบุสตริงตัวระบุของคุณเอง
  • "รหัสแหล่งที่มาของเนื้อหา" และ "Content ID" ของสตรีมแบบสด

หมายเหตุ: คุณต้องเปิดใช้งานเพื่อใช้ตัวระบุประเภทนี้ โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อสอบถามข้อมูลเพิ่มเติม

  • ระยะเวลาที่คาดไว้ของช่วงพักโฆษณาถัดไป ระยะเวลาต้องใกล้เคียงกับความยาวจริงของช่วงพักโฆษณามากที่สุด

นอกจากช่องที่ต้องกรอกเหล่านี้แล้ว คุณยังส่งพารามิเตอร์การกำหนดเป้าหมายที่กำหนดเอง ชื่อของเทมเพลตพ็อดโฆษณาที่จะใช้ หรือข้อมูลคิวออก SCTE35 ได้ด้วย (หากมี)

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

หากต้องการใช้ EABN API คุณต้องสร้างบัญชีบริการและเพิ่มบัญชีในเครือข่าย Google Ad Manager

การสร้างบัญชีบริการ

หากต้องการสร้างบัญชีบริการสำหรับเรียกใช้ EABN API ให้ทำตามขั้นตอนต่อไปนี้ - หากคุณมีบัญชี Google Cloud ให้ใช้โมดูล IAM เพื่อสร้างบัญชีบริการ ดูข้อมูลเพิ่มเติมได้ที่การสร้างและจัดการบัญชีบริการ - หากคุณไม่มีบัญชี Google Cloud ให้ทำตามขั้นตอนต่อไปนี้เพื่อสร้างบัญชีจากคอนโซล Google API

  1. สร้างโปรเจ็กต์ใหม่หรือเลือกโปรเจ็กต์ที่มีอยู่
  2. คลิกจัดการบัญชีบริการในหน้าข้อมูลเข้าสู่ระบบ
  3. ในหน้าบัญชีบริการ ให้คลิกสร้างบัญชีบริการ
  4. ป้อนรายละเอียดบัญชีในหน้าสร้างบัญชีบริการ จากนั้นคลิกสร้าง

เมื่อคุณสร้างบัญชีบริการแล้ว ให้คัดลอกคีย์ JSON ของบัญชีซึ่งใช้สำหรับการตรวจสอบสิทธิ์

กำลังเพิ่มบัญชีบริการลงในเครือข่าย Google Ad Manager

หากต้องการเพิ่มบัญชีบริการในเครือข่ายของคุณ ให้ทำตามขั้นตอนในหัวข้อเพิ่มผู้ใช้บัญชีบริการสำหรับการเข้าถึง API

การเปิดใช้ API

เมื่อสร้างบัญชีบริการแล้ว ให้ข้อมูลต่อไปนี้แก่ผู้จัดการฝ่ายดูแลลูกค้าเพื่อเปิดใช้ API สําหรับบัญชีของคุณ

  • อีเมลบัญชี Google Cloud ของคุณ
  • บัญชีบริการของคุณ
  • รหัสเครือข่ายของเครือข่าย Google Ad Manager

หลังจากที่ผู้จัดการฝ่ายดูแลลูกค้าเปิดใช้ API แล้ว ให้ทำตามขั้นตอนต่อไปนี้เพื่อเปิดใช้ API

  1. ในไลบรารี Google API ให้ค้นหา "Google Ad Manager Video API"
  2. คลิกเปิดใช้

หมายเหตุ: หาก API ไม่ปรากฏในผลการค้นหา ให้ติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อยืนยันว่าบัญชีของคุณเปิดใช้สำหรับ DAI API

การใช้ API

คุณเรียกใช้ EABN API ได้โดยใช้คำขอ JSON/REST

การให้สิทธิ์

หากต้องการเรียกใช้ EABN API ที่ได้รับอนุญาต คุณต้องสร้างข้อมูลเข้าสู่ระบบของบัญชีบริการ OAuth2 โดยใช้คีย์ JSON จากบัญชีบริการและขอบเขต https://www.googleapis.com/auth/video-ads รับข้อมูลเพิ่มเติมได้ที่การใช้ OAuth 2.0 สำหรับแอปพลิเคชันระหว่างเซิร์ฟเวอร์กับเซิร์ฟเวอร์

คุณต้องระบุโทเค็นการให้สิทธิ์ที่ได้เป็นส่วนหัวการตรวจสอบสิทธิ์สำหรับการเรียก EABN API แต่ละครั้ง

การส่งการแจ้งเตือนช่วงพักโฆษณาล่วงหน้า

หากต้องการส่งการแจ้งเตือนช่วงพักโฆษณาล่วงหน้า ให้ส่งคำขอ POST ไปยัง URL ของ EABN ที่ถูกต้อง 1 ใน 3 รายการ ทั้งนี้ขึ้นอยู่กับวิธีที่คุณต้องการระบุสตรีมแบบสด ส่วนต่อไปนี้จะอธิบายความแตกต่างของ URL และแสดงตัวอย่างคำขอและคำตอบ

URL

การแจ้งเตือนช่วงพักโฆษณาล่วงหน้ามี URL ที่ถูกต้อง 3 รายการ คุณสามารถใช้ทั้ง 3 ประเภทเพื่อสร้างช่วงพักโฆษณา (POST) หรือรับรายการช่วงพักโฆษณาที่กำหนด (GET)

หากต้องการใช้คีย์เนื้อหาของสตรีมแบบสด ให้ใช้รายการต่อไปนี้

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

หากต้องการใช้คีย์เนื้อหาที่กำหนดเองของสตรีมแบบสด ให้ใช้รายการต่อไปนี้

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

หากต้องการใช้รหัสแหล่งที่มาของเนื้อหาและ Content ID ให้ใช้รูปแบบต่อไปนี้

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

สำหรับพารามิเตอร์ทั้งหมด ให้ทำดังนี้

  • network_code คือรหัสเครือข่ายของเครือข่าย Google Ad Manager ของคุณ
  • asset_key คือคีย์เนื้อหาที่แสดงในหน้ารายละเอียดของสตรีมแบบสด
  • custom_asset_key คือคีย์เนื้อหาที่กำหนดเองของสตรีมแบบสด
  • content_source_id แสดงรหัสแหล่งที่มาของเนื้อหาใน Google Ad Manager
  • content_id แสดงรหัสของเนื้อหาใน Google Ad Manager

หมายเหตุ: คู่ content_source_id/content_id ที่ระบุต้องเชื่อมโยงกับสตรีมแบบสดใน Google Ad Manager

เนื้อหาของคำขอ - ใช้เพื่อสร้างช่วงพักโฆษณา (POST) เท่านั้น

ออบเจ็กต์

expectedDuration

 ต้องระบุ ระยะเวลาของช่วงพักโฆษณานี้โดยใช้รูปแบบระยะเวลามาตรฐานของ Google (xx.xxxs โดยที่ xx.xxx คือจำนวนวินาที)

customParams

 ไม่บังคับ คู่คีย์-ค่าที่จะรวมไว้ในคำขอโฆษณาสำหรับช่วงพักโฆษณานี้สำหรับการกำหนดเป้าหมายตามเกณฑ์ที่กำหนดเองใน AM360 โดยแยกตาม

=

และเข้าร่วมโดย

&

.
ตัวอย่าง:

key=value&key2=value2,value3


ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดเป้าหมายได้ที่จัดเตรียมพารามิเตอร์การกำหนดเป้าหมายไปยังสตรีมของคุณ

podTemplateName

 ไม่บังคับ ชื่อเทมเพลตพ็อดโฆษณา

scte35CueOut

 ไม่บังคับ ข้อมูลที่เข้ารหัสฐาน 64 จากข้อความสุดท้าย SCTE-35 อาจมี

splice_insert()

หรือ

time_signal()

คำสั่ง
ตัวอย่าง:

  • time_signal():

    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==

  • splice_insert():

    /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=

ตัวอย่างคำขอ

สร้างช่วงพักโฆษณา
POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}
เนื้อหาการตอบกลับ

เนื้อหาการตอบกลับประกอบด้วยพารามิเตอร์ทั้งหมดที่ส่งในออบเจ็กต์ adBreak รวมถึงช่อง name เพิ่มเติม ซึ่งมีรหัสมาตรฐานทั่วทั้ง Google ของช่วงพักโฆษณาที่สร้างขึ้น ฟิลด์นี้จะแสดงในรูปแบบต่อไปนี้

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
ตัวอย่างการตอบกลับ
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}
แสดงรายการช่วงพักโฆษณาที่กำหนด
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
เนื้อหาการตอบกลับ

เนื้อหาการตอบกลับประกอบด้วยช่วงพักโฆษณาที่มีช่อง breakState เพิ่มสำหรับช่วงพักโฆษณาแต่ละช่วงที่กำหนดให้กับสตรีม ช่อง breakState รองรับค่าต่อไปนี้

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
ตัวอย่างการตอบกลับ
HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}