LiveBroadcasts: cuepoint

Chèn điểm tín hiệu vào sự kiện phát trực tiếp. Điểm tín hiệu có thể kích hoạt một điểm chèn quảng cáo.

Lưu ý: Phương thức này thay thế phương thức liveCuepoints.insert. Phương thức này yêu cầu các yêu cầu phải được một tài khoản liên kết với một Chủ sở hữu nội dung trên YouTube uỷ quyền. Phương thức này không có yêu cầu uỷ quyền giống như vậy.

Yêu cầu

Yêu cầu HTTP

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

Ủy quyền

Yêu cầu này yêu cầu uỷ quyền với ít nhất một trong các phạm vi sau. Để đọc thêm về việc xác thực và uỷ quyền, hãy xem bài viết Triển khai quy trình xác thực OAuth 2.0.

Phạm vi
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtubepartner

Thông số

Bảng sau đây liệt kê các tham số mà truy vấn này hỗ trợ. Tất cả các tham số được liệt kê đều là tham số truy vấn.

Thông số
Tham số bắt buộc
id string
Tham số id xác định thông báo truyền tin mà điểm tín hiệu đang được chèn vào. Chương trình phát sóng phải đang phát trực tiếp khi chèn điểm tín hiệu.
Thông số tuỳ chọn
onBehalfOfContentOwner string
Bạn chỉ có thể sử dụng thông số này trong một yêu cầu được uỷ quyền hợp lệ.
Lưu ý: Thông số này chỉ dành riêng cho những đối tác nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube. Mã này cho phép chủ sở hữu nội dung xác thực một lần và thay mặt cho kênh được chỉ định trong giá trị tham số thực hiện các hành động mà không cần cung cấp thông tin xác thực khác nhau cho từng kênh riêng biệt. Tài khoản mà người dùng xác thực phải được liên kết với chủ sở hữu nội dung YouTube được chỉ định.
Thông số onBehalfOfContentOwner cho biết rằng thông tin xác thực uỷ quyền của yêu cầu xác định một người dùng YouTube đang thay mặt cho Chủ sở hữu nội dung trên YouTube được chỉ định trong giá trị thông số. Tham số này dành cho các đối tác nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube.
onBehalfOfContentOwnerChannel string
Bạn chỉ có thể sử dụng thông số này trong một yêu cầu được uỷ quyền hợp lệ.
Lưu ý: Thông số này chỉ dành riêng cho những đối tác nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube. Mã này cho phép chủ sở hữu nội dung xác thực một lần và thay mặt cho kênh được chỉ định trong giá trị tham số thực hiện các hành động mà không cần cung cấp thông tin xác thực cho từng kênh riêng lẻ.
Thông số onBehalfOfContentOwnerChannel chỉ định mã nhận dạng kênh YouTube của kênh được liên kết với chương trình phát sóng mà điểm tín hiệu sẽ được chèn vào. Tham số này là bắt buộc khi một yêu cầu chỉ định giá trị cho tham số onBehalfOfContentOwner và bạn chỉ có thể sử dụng tham số này cùng với tham số đó. Các yêu cầu sau đây cũng được áp dụng:
  • Yêu cầu phải được uỷ quyền bằng một tài khoản người dùng được liên kết với chủ sở hữu nội dung mà tham số onBehalfOfContentOwner chỉ định.
  • Kênh mà giá trị thông số onBehalfOfContentOwnerChannel chỉ định phải được liên kết với chủ sở hữu nội dung mà thông số onBehalfOfContentOwner chỉ định.

Nội dung yêu cầu

Cung cấp tài nguyên cuepoint trong phần nội dung yêu cầu. Cấu trúc JSON sau đây cho thấy định dạng của tài nguyên cuepoint:

{
    "id": string,
    "insertionOffsetTimeMs": long,
    "walltimeMs": datetime,
    "durationSecs": unsigned integer,
    "cueType": string
  }
 Trong nội dung yêu cầu, trường cueType là bắt buộc và phải được đặt thành cueTypeAd. Bạn cũng có thể đặt giá trị cho các thuộc tính này:
  • durationSecs
  • insertionOffsetTimeMs (không được đặt nếu đã đặt walltimeMs)
  • walltimeMs (không được đặt nếu đã đặt insertionOffsetTimeMs)

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
id string
Giá trị mà YouTube gán để nhận dạng duy nhất điểm đánh dấu. Xin lưu ý rằng giá trị này khác với tham số id bắt buộc, tham số này xác định thông báo truyền tin. Bạn có thể bỏ qua giá trị này khi gửi yêu cầu chèn điểm tín hiệu. Giá trị này sẽ được điền vào phản hồi API.
insertionOffsetTimeMs long
Giá trị thuộc tính xác định độ lệch thời gian, tính bằng mili giây, khi cần chèn điểm tín hiệu. Giá trị này được đo từ đầu luồng màn hình và giá trị mặc định của giá trị này là 0, cho biết rằng điểm tín hiệu nên được chèn càng sớm càng tốt. Bạn không nên chỉ định giá trị cho thông số này nếu thông báo truyền tin của bạn không có luồng giám sát.

Mặc dù được đo bằng mili giây, nhưng giá trị này thực sự là giá trị ước chừng và YouTube sẽ chèn điểm tín hiệu gần nhất có thể với thời điểm đó.

Chỉ hỗ trợ các giá trị khác 0 cho trường này nếu luồng truyền tin bị trễ. Nếu luồng truyền tin của bạn không bị trễ, thì 0 là giá trị hợp lệ duy nhất. Để biết thêm thông tin, hãy xem phần Bắt đầu.

Lưu ý: Nếu thông báo truyền tin của bạn có giai đoạn thử nghiệm, thì độ lệch sẽ được đo từ thời điểm bắt đầu giai đoạn thử nghiệm.

API sẽ trả về lỗi nếu một yêu cầu cố gắng chèn một điểm tín hiệu chỉ định giá trị cho thuộc tính này và cho thuộc tính walltimeMs.
walltimeMs integer
Giá trị thuộc tính chỉ định thời gian theo đồng hồ thực tế mà bạn nên chèn điểm tín hiệu. Giá trị này là một số nguyên đại diện cho dấu thời gian theo hệ thống (tính bằng mili giây).

API sẽ trả về lỗi nếu một yêu cầu cố gắng chèn một điểm tín hiệu chỉ định giá trị cho thuộc tính này và cho thuộc tính insertionOffsetTimeMs.
durationSecs unsigned integer
Thời lượng của điểm tín hiệu, tính bằng giây. Giá trị phải là một số nguyên dương. Giá trị mặc định là 30.
cueType string
Loại của điểm tín hiệu. Bạn phải đặt giá trị thuộc tính thành cueTypeAd.

Phản hồi

Nếu thành công, phương thức này sẽ trả về tài nguyên cuepoint đã chèn trong phần nội dung phản hồi.

Lỗi

Bảng sau đây xác định thông báo lỗi mà API có thể trả về để phản hồi lệnh gọi đến phương thức này. Để biết thêm thông tin chi tiết, hãy xem phần API phát trực tiếp trên YouTube – Lỗi.

Loại lỗi Thông tin chi tiết về lỗi Mô tả
insufficientPermissions (403) insufficientLivePermissions Yêu cầu này không được phép chèn điểm tín hiệu trong chương trình phát trực tiếp.
insufficientPermissions (403) liveStreamingNotEnabled Người dùng đã cho phép yêu cầu này không được phép phát trực tiếp video trên YouTube. Người dùng có thể tìm thêm thông tin tại bài viết Bắt đầu phát trực tiếp và Tiêu chí sử dụng tính năng.
rateLimitExceeded (403) userRequestsExceedRateLimit Người dùng đã gửi quá nhiều yêu cầu trong một khung thời gian nhất định.
required (400) idRequired Thông số id bắt buộc phải xác định chương trình phát sóng mà bạn muốn chèn điểm tín hiệu.
required (400) cueTypeRequired Bạn phải chỉ định trường cueType bắt buộc trong phần nội dung yêu cầu API.
notFound (404) liveBroadcastNotFound Thông báo truyền tin do tham số id chỉ định không tồn tại.
invalidValue (400) conflictingTimeFields Bạn chỉ có thể chỉ định một trong hai insertionOffsetTimeMs và walltimeMs. Việc đặt cả hai giá trị sẽ gây ra lỗi. Nếu bạn không đặt giá trị nào, YouTube sẽ sử dụng thời gian insertionOffsetTimeMs mặc định (0). Điều này có nghĩa là điểm đánh dấu sẽ được chèn sớm nhất có thể.
invalidValue (400) invalidInsertionOffsetTimeMs Tài nguyên cuepoint đã chỉ định một giá trị không hợp lệ cho thuộc tính insertionOffsetTimeMs. Giá trị phải là 0 hoặc một số nguyên dương.
invalidValue (400) invalidWalltimeMs Tài nguyên cuepoint đã chỉ định một giá trị không hợp lệ cho thuộc tính walltimeMs. Giá trị phải là một số nguyên đại diện cho dấu thời gian bắt đầu của hệ thống (tính bằng mili giây).
backendError (5xx) serviceUnavailable Dịch vụ này hiện không hoạt động. Hãy thử lại yêu cầu của bạn sau vài phút.

Hãy dùng thử!

Sử dụng APIs Explorer để gọi API này và xem yêu cầu và phản hồi API.