LiveChatMessages: streamList

Phương thức này thiết lập một kết nối truyền trực tuyến từ máy chủ, cho phép bạn nhận tin nhắn Trò chuyện trong sự kiện phát trực tiếp cho một cuộc trò chuyện cụ thể với độ trễ thấp. Đây là cách hiệu quả nhất để sử dụng tin nhắn trò chuyện trực tiếp, vì cách này sẽ đẩy tin nhắn mới đến ứng dụng của bạn ngay khi có tin nhắn, thay vì yêu cầu bạn thăm dò ý kiến để biết thông tin cập nhật.

Khi bạn kết nối lần đầu, API sẽ gửi một loạt tin nhắn chứa nhật ký trò chuyện gần đây. Khi có tin nhắn mới, máy chủ sẽ tiếp tục gửi tin nhắn đó qua kết nối đang mở.

Tin nhắn trong mỗi phản hồi của máy chủ được sắp xếp từ cũ nhất đến mới nhất. Mỗi phản hồi cũng bao gồm một nextPageToken. Nếu ứng dụng của bạn ngắt kết nối, bạn có thể dùng mã thông báo này để tiếp tục phát trực tiếp. Để làm việc này, hãy cung cấp nextPageToken gần đây nhất mà bạn nhận được làm giá trị cho tham số pageToken trong yêu cầu kết nối mới. Sau đó, API sẽ tiếp tục gửi thông báo từ thời điểm bạn dừng lại.

Tác động đến hạn mức: Mỗi lệnh gọi đến phương thức này sẽ tiêu tốn 5 đơn vị hạn mức.

Bản minh hoạ

Để xem bản minh hoạ Python về điểm cuối này, hãy xem hướng dẫn Phát trực tuyến cuộc trò chuyện trong sự kiện phát trực tiếp.

Yêu cầu

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
liveChatId	string Tham số liveChatId chỉ định mã nhận dạng của cuộc trò chuyện có tin nhắn sẽ được trả về. Mã nhận dạng Trò chuyện trong sự kiện phát trực tiếp liên kết với một chương trình phát sóng sẽ được trả về trong thuộc tính snippet.liveChatId của tài nguyên liveBroadcast.
part	string Tham số part chỉ định các phần tài nguyên liveChatMessage mà phản hồi của API sẽ bao gồm. Các giá trị được hỗ trợ: id, snippet và authorDetails.
Tham số không bắt buộc
hl	string Tham số hl hướng dẫn API truy xuất chuỗi hiển thị đơn vị tiền tệ được bản địa hoá cho một ngôn ngữ ứng dụng cụ thể mà trang web YouTube hỗ trợ. Ví dụ: trong tiếng Anh, đơn vị tiền tệ sẽ được hiển thị là $1.50, nhưng trong tiếng Pháp, đơn vị tiền tệ sẽ được hiển thị là 1,50$. Giá trị tham số phải là mã ngôn ngữ có trong danh sách do phương thức i18nLanguages.list trả về.
maxResults	unsigned integer Tham số maxResults chỉ định số lượng tối đa các thông báo sẽ được trả về trong tập kết quả. Các giá trị được chấp nhận là từ 200 đến 2000, bao gồm cả hai giá trị này. Giá trị mặc định là 500. Yêu cầu ban đầu được thực hiện mà không có mã thông báo tiếp tục sẽ chỉ chứa các sự kiện gần đây nhất. Giá trị này có thể nhỏ hơn maxResults, nếu được cung cấp. API này không truy xuất các sự kiện cũ hơn những sự kiện được trả về theo yêu cầu ban đầu được thực hiện mà không có mã thông báo tiếp tục.
pageToken	string Tham số pageToken xác định một trang cụ thể trong tập kết quả cần được trả về. Trong một phản hồi của API, thuộc tính nextPageToken xác định những trang khác có thể truy xuất.
profileImageSize	unsigned integer Tham số profileImageSize chỉ định kích thước của ảnh hồ sơ người dùng sẽ được trả về trong tập kết quả. Hình ảnh có dạng hình vuông. Giá trị mặc định là 88, nghĩa là ảnh sẽ có kích thước 88px x 88px. Giá trị được chấp nhận nằm trong khoảng từ 16 đến 720.

Nội dung yêu cầu

Đừng cung cấp nội dung yêu cầu khi gọi phương thức này.

Phản hồi

Nếu thành công, phương thức này sẽ trả về một nội dung phản hồi có cấu trúc sau:

{
  "kind": "youtube#liveChatMessageListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pollingIntervalMillis": unsigned integer,
  "offlineAt": datetime,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    liveChatMessage Resource
  ],
  "activePollItem": liveChatMessage Resource
}

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
kind	string Xác định loại tài nguyên API. Giá trị sẽ là youtube#liveChatMessageListResponse.
etag	etag Etag của tài nguyên này.
nextPageToken	string Mã thông báo có thể dùng làm giá trị của tham số pageToken để truy xuất trang tiếp theo trong tập kết quả.
offlineAt	datetime Ngày và giờ mà sự kiện phát trực tiếp cơ bản ngừng phát. Thuộc tính này chỉ xuất hiện nếu sự kiện phát trực tiếp đã ngoại tuyến. Giá trị được chỉ định theo định dạng ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
pageInfo	object Đối tượng pageInfo đóng gói thông tin phân trang cho tập hợp kết quả.
pageInfo.totalResults	integer Tổng số kết quả trong tập kết quả.
pageInfo.resultsPerPage	integer Số lượng kết quả có trong phản hồi của API.
items[]	list Danh sách tin nhắn. Mỗi mục trong danh sách là một tài nguyên liveChatMessage.
activePollItem	object Dữ liệu của cuộc thăm dò ý kiến trong tin nhắn. Mỗi cuộc thăm dò ý kiến là một tài nguyên liveChatMessage có loại pollEvent, đại diện cho một cuộc thăm dò ý kiến đang hoạt động. Mỗi cuộc trò chuyện chỉ có thể có một cuộc thăm dò ý kiến.

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 một lệnh gọi đến phương thức này. Hãy xem tài liệu về thông báo lỗi để biết thêm thông tin chi tiết.

Khi sử dụng gRPC để kết nối:

Mã lỗi gRPC	Thông tin chi tiết về lỗi	Mô tả
PERMISSION_DENIED (7)	The caller does not have permission	Bạn không có các quyền cần thiết để truy xuất tin nhắn cho cuộc trò chuyện trực tiếp được chỉ định.
INVALID_ARGUMENT (3)	Request contains an invalid argument	Không phân tích cú pháp được các tham số đã cung cấp. Hãy đảm bảo liveChatId và các tham số khác có định dạng chính xác.
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_DISABLED. Tính năng trò chuyện trực tiếp được chỉ định đã bị tắt.
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_ENDED. Bạn không thể truy xuất tin nhắn cho cuộc trò chuyện qua Live đã kết thúc.
NOT_FOUND (5)	Requested entity was not found	Không tìm thấy cuộc trò chuyện qua Live mà bạn đang cố gắng truy xuất. Hãy kiểm tra giá trị của tham số liveChatId trong yêu cầu để đảm bảo giá trị đó chính xác.
RESOURCE_EXHAUSTED (8)	Resource has been exhausted (e.g. check quota)	Yêu cầu được gửi quá nhanh sau yêu cầu trước đó. Lỗi này xảy ra khi các yêu cầu API để truy xuất thông báo được gửi thường xuyên hơn tốc độ làm mới của YouTube, điều này gây lãng phí băng thông một cách không cần thiết.

* Do hạn chế của gRPC, bạn không thể phân biệt dựa trên mã lỗi giữa trường hợp LIVE_CHAT_DISABLED và trường hợp LIVE_CHAT_ENDED. YouTube đang tích cực tìm giải pháp để giải quyết vấn đề này.

Khi sử dụng lưu lượng truy cập trang web để kết nối:

Loại lỗi	Thông tin chi tiết về lỗi	Mô tả
HttpStatus.FORBIDDEN (403)	forbidden	Bạn không có các quyền cần thiết để truy xuất tin nhắn cho cuộc trò chuyện trực tiếp được chỉ định.
HttpStatus.BAD_REQUEST (400)	Reason for invalid request, e.g. pageTokenInvalid	Không phân tích được các tham số đã cung cấp. Hãy đảm bảo liveChatId và các tham số khác có định dạng chính xác.
HttpStatus.FORBIDDEN (403)	liveChatDisabled	LIVE_CHAT_DISABLED. Cuộc trò chuyện qua Live được chỉ định đã bị tắt.
HttpStatus.FORBIDDEN (403)	liveChatEnded	LIVE_CHAT_ENDED. Bạn không thể truy xuất tin nhắn cho cuộc trò chuyện qua Live đã kết thúc.
HttpStatus.NOT_FOUND (404)	liveChatNotFound	Không tìm thấy cuộc trò chuyện qua Live mà bạn đang cố gắng truy xuất. Hãy kiểm tra giá trị của tham số liveChatId trong yêu cầu để đảm bảo giá trị đó chính xác.
HttpStatus.FORBIDDEN (403)	rateLimitExceeded	Yêu cầu được gửi quá nhanh sau yêu cầu trước đó. Lỗi này xảy ra khi các yêu cầu API để truy xuất tin nhắn được gửi thường xuyên hơn tốc độ làm mới của YouTube, gây lãng phí băng thông không cần thiết.