LiveChatMessages: streamList

此方法会建立服务器流式传输连接，让您能够以低延迟接收特定聊天的实时聊天消息。这是使用实时聊天消息的最有效方式，因为它可以将新消息推送到您的客户端，而不是要求您轮询更新。

首次连接时，API 会发送一系列包含近期聊天记录的消息。发布新消息后，服务器将继续通过打开的连接发送这些消息。

每个服务器响应中的消息都按从旧到新的顺序排列。每个响应还包含一个 nextPageToken。如果您的客户端断开连接，您可以使用此令牌恢复流。为此，请在新的连接请求中提供您收到的最后一个 nextPageToken 作为 pageToken 参数的值。然后，API 将从您上次中断的位置继续发送消息。

配额影响： 调用此方法的配额费用为 5 个单位。

演示

如需查看此端点的 Python 演示，请参阅流式传输实时聊天指南。

请求

参数

下表列出了此查询支持的参数。列出的所有参数都是查询参数。

参数
必需参数
liveChatId	string liveChatId 参数用于指定要返回其消息的聊天的 ID。与广播关联的实时聊天 ID 在 liveBroadcast 资源的 snippet.liveChatId 属性中返回。
part	string part 参数用于指定 API 响应将包含的 liveChatMessage 资源部分。支持的值包括 id、snippet 和 authorDetails。
可选参数
hl	string hl 参数用于指示 API 检索 YouTube 网站支持的特定 应用语言的本地化货币显示字符串。例如，在英语中，货币将显示为 $1.50，但在法语中，货币将显示为 1,50$。 参数值必须是 i18nLanguages.list 方法返回的列表中的语言代码。
maxResults	unsigned integer maxResults 参数用于指定结果集中应返回的消息数量上限。可接受的值为 200 到 2000（含这两个值）。默认值为 500。 在没有续页令牌的情况下发出的初始请求将仅包含最近的事件。如果提供了，则此值可能会小于 maxResults。 API 不会检索比在没有续页令牌的情况下发出的初始请求返回的事件更早的事件。
pageToken	string pageToken 参数用于标识结果集中应返回的特定页面。在 API 响应中，nextPageToken 属性用于标识可以检索的其他页面。
profileImageSize	unsigned integer profileImageSize 参数用于指定结果集中应返回的 用户个人资料照片 的大小。图片为正方形。默认值为 88，表示图片的大小为 88 像素 x 88 像素。可接受的值介于 16 到 720（含这两个值）之间。

请求正文

调用此方法时，请勿提供请求正文。

响应

如果成功，此方法将返回采用以下结构的响应正文：

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

属性

下表定义了此资源中显示的属性：

属性
kind	string 标识 API 资源的类型。该值将为 youtube#liveChatMessageListResponse。
etag	etag 此资源的 ETag。
nextPageToken	string 可用作 pageToken 参数值的令牌，用于检索结果集中的下一页。
offlineAt	datetime 底层直播下线的日期和时间。仅当直播已下线时，此属性才会显示。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
pageInfo	object The pageInfo 对象封装了结果集的分页信息。
pageInfo.totalResults	integer 结果集中的结果总数。
pageInfo.resultsPerPage	integer API 响应中包含的结果数。
items[]	list 消息列表。列表中的每个项都是 liveChatMessage 资源。
activePollItem	object 消息中的投票数据。每个投票都是类型为 pollEvent 的 liveChatMessage 资源，表示一个有效投票。每个聊天只能有一个投票。

错误

下表列出了 API 在响应对此方法的调用时可能会返回的出错提示。如需了解详情，请参阅出错提示文档。

使用 gRPC 进行连接时：

gRPC 错误代码	错误详情	说明
PERMISSION_DENIED (7)	The caller does not have permission	您没有检索指定实时聊天消息所需的权限。
INVALID_ARGUMENT (3)	Request contains an invalid argument	无法解析提供的参数。请确保 liveChatId 和其他参数的格式正确。
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_DISABLED。指定的实时聊天已停用。
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_ENDED。您无法检索已结束的实时聊天的消息。
NOT_FOUND (5)	Requested entity was not found	您尝试检索的实时聊天无法找到。请检查请求的 liveChatId 参数的值，确保其正确无误。
RESOURCE_EXHAUSTED (8)	Resource has been exhausted (e.g. check quota)	在发送上一个请求后，您发送此请求的速度过快。当检索消息的 API 请求的发送频率高于 YouTube 的刷新率时，就会发生此错误，这会不必要地浪费带宽。

* 由于 gRPC 存在限制，因此无法根据错误代码区分 LIVE_CHAT_DISABLED 情况和 LIVE_CHAT_ENDED 情况。YouTube 正在积极开发解决方案来解决此问题。

使用 Web 流量进行连接时：

错误类型	错误详情	说明
HttpStatus.FORBIDDEN (403)	forbidden	您没有检索指定实时聊天消息所需的权限。
HttpStatus.BAD_REQUEST (400)	Reason for invalid request, e.g. pageTokenInvalid	无法解析提供的参数。请确保 liveChatId 和其他参数的格式正确。
HttpStatus.FORBIDDEN (403)	liveChatDisabled	LIVE_CHAT_DISABLED。指定的实时聊天已停用。
HttpStatus.FORBIDDEN (403)	liveChatEnded	LIVE_CHAT_ENDED。您无法检索已结束的实时聊天的消息。
HttpStatus.NOT_FOUND (404)	liveChatNotFound	您尝试检索的实时聊天无法找到。请检查请求的 liveChatId 参数的值，确保其正确无误。
HttpStatus.FORBIDDEN (403)	rateLimitExceeded	在发送上一个请求后，您发送此请求的速度过快。当检索消息的 API 请求的发送频率高于 YouTube 的刷新率时，就会发生此错误，这会不必要地浪费带宽。