LiveChatMessages: streamList

這個方法會建立伺服器串流連線，讓您以低延遲時間接收特定聊天室的即時通訊訊息。這是最有效率的即時通訊訊息接收方式，因為系統會在有新訊息時立即推送至用戶端，您不必輪詢更新。

首次連線時，API 會傳送一系列訊息，內含最近的即時通訊記錄。伺服器會透過開啟的連線，持續傳送新訊息。

每個伺服器回應中的訊息都會依時間排序，由舊到新。每個回覆也包含 nextPageToken。如果用戶端中斷連線，您可以使用這個權杖繼續串流。如要這麼做，請在新的連線要求中，將您收到的最後一個 nextPageToken 做為 pageToken 參數的值。API 隨後會從上次中斷的地方繼續傳送訊息。

示範

如需這個端點的 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。
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。你無法擷取已結束的聊天室訊息。
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 的重新整理率，就會發生這項錯誤，因為這樣會不必要地浪費頻寬。