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
訊息中的投票資料。每項意見調查都是 liveChatMessage 資源，類型為 pollEvent，代表進行中的意見調查。每個聊天室只能有一項意見調查。

錯誤

下表列出 API 可能在呼叫這個方法時傳回的錯誤訊息。詳情請參閱錯誤訊息說明文件。

錯誤類型 錯誤詳情 說明
forbidden (403) forbidden 您沒有必要權限，無法擷取指定聊天室的訊息。
forbidden (403) liveChatDisabled 指定直播未啟用聊天室。
forbidden (403) liveChatEnded 指定的聊天室已不再直播。
notFound (404) liveChatNotFound 找不到你要擷取的聊天室。請檢查要求 liveChatId 參數的值，確保正確無誤。
rateLimitExceeded rateLimitExceeded 您在傳送上一個要求後，很快就傳送了這個要求。如果傳送 API 要求擷取訊息的頻率高於 YouTube 的重新整理頻率，就會發生這項錯誤，不必要地浪費頻寬。

試試看！

使用 APIs Explorer 呼叫這個 API，並查看 API 要求和回應。