LiveChatMessages: list

列出特定聊天中的实时聊天消息。

当您首次请求检索聊天消息时，API 会返回部分或全部聊天记录，具体取决于该记录的长度。响应中的消息会按时间从旧到新排序。
  • 响应中的 nextPageToken 提供了一个令牌，您可以在后续请求中使用该令牌来标识 API 客户端应检索的下一组结果。
  • pollingIntervalMillis 属性表示 API 客户端在请求更多结果之前应等待的时间。
当您请求更多结果时，您可以将 pageToken 参数设置为 nextPageToken 值，API 服务器会返回更多聊天消息（如果有）。同样，在该结果集中，消息会按时间从旧到新排序。

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

常见应用场景

请求

HTTP 请求

GET https://www.googleapis.com/youtube/v3/liveChat/messages

参数

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

参数
必需参数
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 参数值的令牌，用于检索结果集中的下一页。
pollingIntervalMillis unsigned integer
客户端在再次轮询新实时聊天消息之前应等待的时间（以毫秒为单位）。
offlineAt datetime
底层直播下线的日期和时间。仅当直播已下线时，此属性才会显示。该值采用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。
pageInfo object
pageInfo 对象用于封装结果集的分页信息。
pageInfo.totalResults integer
结果集中的结果总数。
pageInfo.resultsPerPage integer
API 响应中包含的结果数。
items[] list
消息列表。列表中的每一项都是一个 liveChatMessage 资源。
activePollItem object
消息中的投票数据。每个投票都是一个类型为 pollEvent 的 liveChatMessage 资源，表示一个有效投票。每个聊天只能有一个投票。

错误

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

错误类型 错误详情 说明
forbidden (403) forbidden 您没有检索指定实时聊天消息所需的权限。
forbidden (403) liveChatDisabled 指定广播未启用实时聊天功能。
forbidden (403) liveChatEnded 指定的实时聊天已结束。
notFound (404) liveChatNotFound 您尝试检索的实时聊天不存在。请检查请求的 liveChatId 参数的值，确保其正确无误。
rateLimitExceeded rateLimitExceeded 请求是在上一个请求之后过快发送的。当检索消息的 API 请求的发送频率高于 YouTube 的刷新频率时，就会发生此错误，这会不必要地浪费带宽。

试试看！

使用 APIs Explorer 调用此 API，并查看 API 请求和响应。