Trang này được dịch bởi Cloud Translation API.

LiveBroadcasts: cuepoint

Chèn điểm dừng vào chương trình phát sóng trực tiếp. Điểm dừng có thể kích hoạt điểm chèn quảng cáo.

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

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 ủy quyền với ít nhất một trong các phạm vi sau (đọc thêm về xác thực và ủy quyền).

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 liệt kê các tham số mà truy vấn này hỗ trợ. Tất 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 chương trình phát sóng sẽ chèn điểm dừng. Chương trình phát phải đang phát trực tiếp khi chèn điểm dừng.
Tham số không bắt buộc
`onBehalfOfContentOwner`	`string` Thông số này chỉ được dùng trong một yêu cầu được uỷ quyền đúng cách. Lưu ý: Tham số này chỉ dành cho các đối tác nội dung của YouTube sở hữu và quản lý nhiều kênh YouTube. Tính năng này cho phép chủ sở hữu nội dung xác thực một lần và thay mặt kênh được chỉ định trong giá trị tham số mà không phải cung cấp thông tin xác thực khác nhau cho từng kênh. 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 trên YouTube đã chỉ định. Thông số `onBehalfOfContentOwner` cho biết thông tin đăng nhập ủy quyền của yêu cầu xác định người dùng YouTube đang hành động thay mặt cho Chủ sở hữu nội dung YouTube được chỉ định trong giá trị thông số. Thông số này dành cho các đối tác nội dung YouTube sở hữu và quản lý nhiều kênh YouTube khác nhau.
`onBehalfOfContentOwnerChannel`	`string` Thông số này chỉ được dùng trong một yêu cầu được uỷ quyền đúng cách. Lưu ý: Tham số này chỉ dành cho các đối tác nội dung của YouTube sở hữu và quản lý nhiều kênh YouTube. Tính năng này cho phép chủ sở hữu nội dung xác thực một lần và thay mặt kênh được chỉ định trong giá trị tham số mà không phải cung cấp thông tin xác thực cho từng kênh. Thông số `onBehalfOfContentOwnerChannel` chỉ định mã nhận dạng kênh YouTube của kênh liên kết với chương trình phát đang chèn điểm dừng. Bạn phải sử dụng thông số này khi yêu cầu chỉ định giá trị cho thông số `onBehalfOfContentOwner` và chỉ có thể sử dụng cùng với thông số đó. Các yêu cầu sau đây cũng được áp dụng: Yêu cầu này 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ị tham số `onBehalfOfContentOwnerChannel` chỉ định phải được liên kết với chủ sở hữu nội dung mà tham 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 phần nội dung yêu cầu, trường cueType là trường 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 sau:

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` Một giá trị mà YouTube chỉ định để xác định điểm dừng duy nhất. Xin lưu ý rằng giá trị này khác với thông số `id` (bắt buộc) giúp xác định chương trình phát sóng. Giá trị này có thể bị bỏ qua khi gửi yêu cầu chèn một điểm dừng. Giá trị sẽ được điền sẵn trong phản hồi API.
`insertionOffsetTimeMs`	`long` Giá trị thuộc tính xác định thời gian chênh lệch (tính bằng mili giây) khi chèn điểm dừng. Giá trị này được đo từ đầu luồng theo dõi và giá trị mặc định của luồng này là `0`, cho biết cần chèn điểm dừng sớm nhất có thể. Bạn không nên chỉ định giá trị cho thông số này nếu chương trình phát sóng của bạn không có luồng theo dõi. Mặc dù được tính bằng mili giây nhưng giá trị thực tế chỉ là giá trị gần đúng và YouTube sẽ chèn điểm dừng gần nhất có thể vào thời điểm đó. Giá trị khác 0 cho trường này chỉ được hỗ trợ nếu luồng phát bị trễ. Nếu luồng chương trình phát của bạn không bị trì hoãn thì `0` là giá trị hợp lệ duy nhất. Hãy xem hướng dẫn Bắt đầu để biết thêm thông tin. Lưu ý: Nếu chương trình phát sóng của bạn có giai đoạn kiểm thử, thì hệ số đo mức chênh lệch sẽ được đo lường từ thời điểm bắt đầu giai đoạn kiểm thử. API sẽ trả về lỗi nếu một yêu cầu cố gắng chèn một điểm dừng 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 đồng hồ treo tường mà tại đó điểm dừng sẽ được chèn vào. Giá trị là một số nguyên biểu thị dấu thời gian bắt đầu của hệ thống (tính bằng mili giây). API trả về lỗi nếu yêu cầu cố gắng chèn một điểm dừng có chức năng 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 dừng, 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 điểm dừng. Giá trị thuộc tính phải được đặt 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 được chèn vào nội dung phản hồi.

Lỗi

Bảng sau đây xác định các thông báo lỗi mà API có thể trả về để phản hồi lệnh gọi phương thức này. Tài liệu về thông báo lỗi Xác định tất cả các lỗi mà API phát trực tiếp có thể trả về.

Loại lỗi	Chi tiết lỗi	Nội dung mô tả
`insufficientPermissions (403)`	`insufficientLivePermissions`	Yêu cầu này không được phép chèn điểm dừng vào chương trình phát sóng trực tiếp.
`insufficientPermissions (403)`	`liveStreamingNotEnabled`	Người dùng đã cho phép gửi yêu cầu không được phép phát video trực tiếp trên YouTube. Người dùng có thể tìm thêm thông tin tại https://support.google.com/youtube/answer/2474026 và https://www.youtube.com/features.
`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`	Tham 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 dừng.
`required (400)`	`cueTypeRequired`	Bạn phải chỉ định trường `cueType` bắt buộc trong phần nội dung của yêu cầu API.
`notFound (404)`	`liveBroadcastNotFound`	Thông báo truyền phát 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 số `insertionOffsetTimeMs` và `walltimeMs`. Việc đặt cả hai giá trị sẽ gây ra lỗi. Nếu bạn không đặt một trong hai giá trị, YouTube sẽ sử dụng thời gian `insertionOffsetTimeMs` mặc định (`0`), nghĩa là điểm dừng 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 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ị này phải là số nguyên đại diện cho một 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ụ không khả dụng. Hãy thử gửi lại yêu cầu sau vài phút.

Hãy dùng thử!

Hãy sử dụng APIs Explorer để gọi API này cũng như xem yêu cầu và phản hồi của API đó.