LiveBroadcasts: cuepoint

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

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

ส่งคำขอ

คำขอ HTTP

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

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

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

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

พารามิเตอร์

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

พารามิเตอร์
พารามิเตอร์ที่จำเป็น
id string
พารามิเตอร์ id จะระบุการออกอากาศที่จะแทรก Cue Point การออกอากาศต้องกำลังสตรีมอยู่เมื่อแทรกจุดเริ่มต้น
พารามิเตอร์ที่ไม่บังคับ
onBehalfOfContentOwner string
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้องเท่านั้น
หมายเหตุ: พารามิเตอร์นี้มีไว้สำหรับพาร์ทเนอร์เนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่องโดยเฉพาะ ซึ่งช่วยให้เจ้าของเนื้อหาตรวจสอบสิทธิ์เพียงครั้งเดียวและดําเนินการในนามของช่องที่ระบุไว้ในค่าพารามิเตอร์ได้โดยไม่ต้องระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่แตกต่างกันสําหรับแต่ละช่อง บัญชีที่ผู้ใช้ใช้ตรวจสอบสิทธิ์ต้องลิงก์กับเจ้าของเนื้อหา YouTube ที่ระบุ
พารามิเตอร์ onBehalfOfContentOwner ระบุว่าข้อมูลเข้าสู่ระบบการให้สิทธิ์ของคำขอระบุผู้ใช้ YouTube ที่ดำเนินการในนามของเจ้าของเนื้อหา YouTube ที่ระบุไว้ในค่าพารามิเตอร์ พารามิเตอร์นี้มีไว้สำหรับพาร์ทเนอร์เนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่อง
onBehalfOfContentOwnerChannel string
พารามิเตอร์นี้ใช้ได้เฉพาะในคำขอที่ได้รับอนุญาตอย่างถูกต้องเท่านั้น
หมายเหตุ: พารามิเตอร์นี้มีไว้สำหรับพาร์ทเนอร์เนื้อหา YouTube ที่เป็นเจ้าของและจัดการช่อง YouTube หลายช่องโดยเฉพาะ ซึ่งช่วยให้เจ้าของเนื้อหาตรวจสอบสิทธิ์ได้เพียงครั้งเดียวและดําเนินการในนามของช่องที่ระบุไว้ในค่าพารามิเตอร์ได้โดยไม่ต้องระบุข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์สําหรับแต่ละช่องแยกกัน
พารามิเตอร์ 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 ที่ต้องระบุ ซึ่งระบุการออกอากาศ คุณละเว้นค่านี้ได้เมื่อส่งคําขอแทรก Cue Point ระบบจะป้อนค่าในการตอบกลับของ API
insertionOffsetTimeMs long
ค่าพร็อพเพอร์ตี้ระบุการเลื่อนเวลาเป็นมิลลิวินาทีเมื่อควรแทรกจุดเริ่มโฆษณา ค่าจะวัดจากจุดเริ่มต้นของสตรีมการตรวจสอบ และค่าเริ่มต้นคือ 0 ซึ่งบ่งบอกว่าควรแทรกจุดเริ่มต้นเล่นโดยเร็วที่สุด คุณไม่ควรระบุค่าสำหรับพารามิเตอร์นี้หากสตรีมของคุณไม่มีสตรีมตรวจสอบ

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

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

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

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

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

คำตอบ

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

ข้อผิดพลาด

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

ประเภทข้อผิดพลาด รายละเอียดข้อผิดพลาด คำอธิบาย
insufficientPermissions (403) insufficientLivePermissions คำขอไม่ได้รับอนุญาตให้แทรกจุดเริ่มต้นในรายการถ่ายทอดสด
insufficientPermissions (403) liveStreamingNotEnabled ผู้ใช้ที่อนุญาตให้ส่งคำขอนี้ไม่มีสิทธิ์สตรีมวิดีโอสดบน YouTube ผู้ใช้ดูข้อมูลเพิ่มเติมได้ในส่วนเริ่มต้นใช้งานสตรีมมิงแบบสดและการมีสิทธิ์ใช้ฟีเจอร์
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 ค่าต้องเป็นจํานวนเต็มที่แสดงการประทับเวลาของยุค (เป็นมิลลิวินาที)
backendError (5xx) serviceUnavailable บริการไม่พร้อมให้บริการ โปรดลองส่งคำขออีกครั้งในอีกสักครู่

ลองใช้งาน

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