LiveBroadcasts: cuepoint

แทรกจุดเริ่มโฆษณาในการถ่ายทอดสด จุดเริ่มโฆษณาอาจทริกเกอร์ช่วงพักโฆษณา

หมายเหตุ: วิธีนี้ใช้แทนวิธีการของ liveCuepoints.insert ซึ่งคําขอที่ได้รับอนุญาตต้องได้รับอนุญาตจากบัญชีที่เชื่อมโยงกับเจ้าของเนื้อหาบน YouTube วิธีการนี้ไม่มีข้อกําหนดการให้สิทธิ์ที่เหมือนกัน

ส่งคำขอ

คำขอ HTTP

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/cuepoint

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

คําขอนี้ต้องมีการให้สิทธิ์ที่มีขอบเขตต่อไปนี้อย่างน้อย 1 ขอบเขต (อ่านเพิ่มเติมเกี่ยวกับการตรวจสอบสิทธิ์และการให้สิทธิ์)

ขอบเขต
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

พารามิเตอร์

ตารางต่อไปนี้จะแสดงพารามิเตอร์ที่คําค้นหานี้รองรับ พารามิเตอร์ทั้งหมดที่แสดงคือพารามิเตอร์การค้นหา

พารามิเตอร์
พารามิเตอร์ที่จําเป็น
id string
พารามิเตอร์ id จะระบุการออกอากาศที่กําลังแทรกจุดเริ่มโฆษณา การออกอากาศต้องสตรีมอยู่ขณะแทรกจุดเริ่มโฆษณา
พารามิเตอร์ที่ไม่บังคับ
onBehalfOfContentOwner string
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตเท่านั้น
หมายเหตุ: พารามิเตอร์นี้มีไว้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube ต่างๆ มากมายโดยเฉพาะ ซึ่งจะช่วยให้เจ้าของเนื้อหาตรวจสอบสิทธิ์ได้ 1 ครั้ง และดําเนินการในนามของช่องที่ระบุในค่าพารามิเตอร์ โดยไม่ต้องระบุข้อมูลเข้าสู่ระบบที่แตกต่างกันสําหรับแต่ละช่อง บัญชีที่ผู้ใช้ตรวจสอบสิทธิ์ด้วยต้องลิงก์กับเจ้าของเนื้อหาใน YouTube ที่ระบุ
พารามิเตอร์ onBehalfOfContentOwner ระบุว่าข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคําขอระบุผู้ใช้ YouTube ที่ทําหน้าที่ในนามของเจ้าของเนื้อหา YouTube ที่ระบุไว้ในค่าพารามิเตอร์ พารามิเตอร์นี้มีให้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube ต่างๆ มากมาย
onBehalfOfContentOwnerChannel string
พารามิเตอร์นี้ใช้ได้เฉพาะในคําขอที่ได้รับอนุญาตเท่านั้น
หมายเหตุ: พารามิเตอร์นี้มีไว้สําหรับพาร์ทเนอร์เนื้อหาของ YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube ต่างๆ มากมายโดยเฉพาะ ซึ่งจะช่วยให้เจ้าของเนื้อหาตรวจสอบสิทธิ์ 1 ครั้งและดําเนินการในนามของช่องที่ระบุในค่าพารามิเตอร์ได้โดยไม่ต้องระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ของช่องแต่ละช่องแยกกัน
พารามิเตอร์ onBehalfOfContentOwnerChannel ระบุรหัสช่อง YouTube ของช่องที่เชื่อมโยงกับการออกอากาศที่จุดเริ่มแทรก จําเป็นต้องใช้พารามิเตอร์นี้เมื่อคําขอระบุค่าสําหรับพารามิเตอร์ onBehalfOfContentOwner และใช้ร่วมกับพารามิเตอร์นั้นได้เท่านั้น ข้อกําหนดต่อไปนี้มีผลด้วย
  • คําขอต้องได้รับการอนุมัติโดยบัญชีผู้ใช้ที่ลิงก์กับเจ้าของเนื้อหาที่พารามิเตอร์ onBehalfOfContentOwner ระบุไว้
  • ช่องที่ค่าพารามิเตอร์ onBehalfOfContentOwnerChannel ระบุไว้ต้องลิงก์กับเจ้าของเนื้อหาที่พารามิเตอร์ onBehalfOfContentOwner ระบุไว้

เนื้อหาของคำขอ

ระบุทรัพยากร cuepoint ในส่วนเนื้อหาของคําขอ โครงสร้าง JSON ต่อไปนี้แสดงรูปแบบทรัพยากร cuepoint

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
ในเนื้อหาของคําขอ ต้องกรอกข้อมูลในช่อง cueType และต้องตั้งค่าเป็น cueTypeAd และยังกําหนดค่าสําหรับพร็อพเพอร์ตี้เหล่านี้ได้
  • durationSecs
  • insertionOffsetTimeMs (ต้องไม่ตั้งค่าหากตั้งค่า walltimeMs ไว้)
  • walltimeMs (ต้องไม่ตั้งค่าหากตั้งค่า insertionOffsetTimeMs ไว้)

พร็อพเพอร์ตี้

ตารางต่อไปนี้กําหนดพร็อพเพอร์ตี้ที่ปรากฏในทรัพยากรนี้

พร็อพเพอร์ตี้
id string
ค่าที่ YouTube กําหนดเพื่อระบุจุดเริ่มโฆษณาโดยไม่ซ้ํากัน โปรดทราบว่าค่านี้แตกต่างจากพารามิเตอร์ id ที่จําเป็น ซึ่งจะระบุการออกอากาศ คุณละเว้นค่านี้ได้เมื่อส่งคําขอเพื่อแทรกจุดเริ่มโฆษณา ค่าจะปรากฏในการตอบสนอง API
insertionOffsetTimeMs long
ค่าพร็อพเพอร์ตี้จะระบุการชดเชยเวลาเป็นมิลลิวินาที ซึ่งเป็นเวลาที่ควรแทรกจุดเริ่มโฆษณา ค่านี้จะวัดจากจุดเริ่มต้นของสตรีมจอภาพ โดยมีค่าเริ่มต้นเป็น 0 ซึ่งบ่งชี้ว่าควรแทรกจุดเริ่มโฆษณาโดยเร็วที่สุด คุณไม่ควรระบุค่าสําหรับพารามิเตอร์นี้ หากการออกอากาศไม่มีสตรีมจอภาพ

แม้จะวัดเป็นมิลลิวินาที แต่จริงๆ แล้วค่านี้เป็นค่าโดยประมาณ และ YouTube จะแทรกจุดเริ่มโฆษณาให้ใกล้เคียงที่สุดกับช่วงเวลานั้น

ค่าที่ไม่ใช่ 0 ของช่องนี้จะรองรับเฉพาะเมื่อการออกอากาศสตรีมออกอากาศ หากสตรีมออกอากาศไม่ล่าช้า 0 จะเป็นค่าที่ถูกต้องเพียงรายการเดียว โปรดดูรายละเอียดเพิ่มเติมในคู่มือการเริ่มต้นใช้งาน

หมายเหตุ: หากการออกอากาศมีระยะการทดสอบ ระบบจะวัดออฟเซ็ตจากช่วงที่ระยะทดสอบเริ่มต้น

API จะแสดงข้อผิดพลาดหากคําขอพยายามแทรกจุดเริ่มโฆษณาที่ระบุค่าสําหรับพร็อพเพอร์ตี้นี้และสําหรับพร็อพเพอร์ตี้ walltimeMs
walltimeMs integer
ค่าพร็อพเพอร์ตี้จะระบุเวลาของนาฬิกาที่จะแทรกจุดเริ่มโฆษณา ค่านี้เป็นจํานวนเต็มซึ่งแทนการประทับเวลา Epoch (เป็นมิลลิวินาที)

API จะแสดงข้อผิดพลาดหากคําขอพยายามแทรกจุดเริ่มโฆษณาที่ระบุค่าสําหรับพร็อพเพอร์ตี้นี้และสําหรับพร็อพเพอร์ตี้ insertionOffsetTimeMs
durationSecs unsigned integer
ระยะเวลาของจุดเริ่มโฆษณาเป็นวินาที ค่าต้องเป็นจำนวนเต็มบวก ค่าเริ่มต้นคือ 30
cueType string
ประเภทของจุดเริ่มโฆษณา ต้องตั้งค่าพร็อพเพอร์ตี้เป็น cueTypeAd

คำตอบ

หากสําเร็จ เมธอดนี้จะแสดงทรัพยากร cuepoint ที่แทรกในส่วนเนื้อหาการตอบกลับ

ข้อผิดพลาด

ตารางต่อไปนี้ระบุข้อความแสดงข้อผิดพลาดที่ API อาจส่งคืนเพื่อตอบสนองต่อการเรียกใช้เมธอดนี้ เอกสารข้อความแสดงข้อผิดพลาดจะระบุข้อผิดพลาดทั้งหมดที่ API สตรีมมิงแบบสดสามารถแสดงผลได้

ประเภทข้อผิดพลาด รายละเอียดข้อผิดพลาด คำอธิบาย
insufficientPermissions (403) insufficientLivePermissions คําขอนี้ไม่ได้รับอนุญาตให้แทรกจุดเริ่มโฆษณาในการถ่ายทอดสด
insufficientPermissions (403) liveStreamingNotEnabled ผู้ใช้ที่ให้สิทธิ์คําขอไม่ได้เปิดใช้สตรีมวิดีโอสดบน YouTube ผู้ใช้สามารถดูข้อมูลเพิ่มเติมได้ที่ https://support.google.com/youtube/answer/2474026 และ https://www.youtube.com/features
rateLimitExceeded (403) userRequestsExceedRateLimit ผู้ใช้ส่งคําขอจํานวนมากเกินไปภายในระยะเวลาที่กําหนด
required (400) idRequired พารามิเตอร์ id ที่จําเป็นต้องระบุการออกอากาศที่คุณต้องการแทรกจุดเริ่มโฆษณา
required (400) cueTypeRequired ต้องระบุช่อง cueType ที่จําเป็นในส่วนเนื้อหาของคําขอ API
notFound (404) liveBroadcastNotFound ไม่มีการออกอากาศที่ระบุโดยพารามิเตอร์ id
invalidValue (400) conflictingTimeFields ระบุ insertionOffsetTimeMs และ walltimeMs ได้เพียงรายการเดียว เกิดข้อผิดพลาดขณะตั้งค่าทั้ง 2 ค่า หากไม่ได้กําหนดค่าอย่างใดอย่างหนึ่ง YouTube จะใช้ค่าเริ่มต้น insertionOffsetTimeMs (0) ซึ่งหมายความว่าจะมีการแทรกจุดเริ่มโฆษณาโดยเร็วที่สุด
invalidValue (400) invalidInsertionOffsetTimeMs ทรัพยากร cuepoint ระบุค่าที่ไม่ถูกต้องสําหรับพร็อพเพอร์ตี้ insertionOffsetTimeMs ค่าต้องเป็น 0 หรือจํานวนเต็มบวก
invalidValue (400) invalidWalltimeMs ทรัพยากร cuepoint ระบุค่าที่ไม่ถูกต้องสําหรับพร็อพเพอร์ตี้ walltimeMs ค่าต้องเป็นจํานวนเต็มที่แทนการประทับเวลา Epoch (เป็นมิลลิวินาที)
backendError (5xx) serviceUnavailable ไม่สามารถใช้บริการได้ โปรดลองส่งคําขออีกครั้งในอีกสักครู่

ลองใช้เลย

ใช้ APIs Explorer เพื่อเรียกใช้ API นี้และดูคําขอ API และการตอบกลับ