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 pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults	integer 結果集中的結果總數。
pageInfo.resultsPerPage	integer API 回應中包含的結果數量。
items[]	list 訊息清單。清單中的每個項目都是 liveChatMessage 資源。
activePollItem	object 訊息中的投票資料。每個意見調查都是 liveChatMessage 資源，類型為 pollEvent，代表有效意見調查。每個聊天室只能有一項意見調查。

錯誤

下表列出 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. 無法擷取已結束 Live 對話的訊息。
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 正在積極設法解決這個問題。

使用網站流量連線時：

錯誤類型	錯誤詳情	說明
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 的重新整理頻率，就會發生這項錯誤，不必要地浪費頻寬。