LiveChatMessages: list

列出特定對話的聊天室訊息。

在初次擷取即時通訊訊息時,API 會傳回部分或全部的即時通訊記錄 (取決於記錄長度)。回應中的訊息會由舊到新排序。
  • 回應中的 nextPageToken 會提供權杖,這個權杖會在下一個要求中識別 API 用戶端應擷取的下一組結果。
  • pollingIntervalMillis 屬性表示 API 用戶端在要求其他結果前應等待多久。
當您要求其他結果時,請將 pageToken 參數設為 nextPageToken 值,且 API 伺服器會傳回額外的即時通訊訊息 (如果有的話)。在這個結果集中,訊息會依最舊到最新排序。

常見用途

要求

HTTP 要求

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

參數

下表列出這個查詢支援的參數。這裡列出的所有參數都是查詢參數。

參數
必要參數
liveChatId string
liveChatId 參數會指定即時通訊的 ID,這個即時通訊的內容會回傳給他們。與廣播相關聯的即時通訊 ID 會在 liveBroadcast 資源的 snippet.liveChatId 屬性中傳回。
part string
part 參數會指定 API 回應將包含的 liveChatMessage 資源部分。支援的值為 idsnippetauthorDetails
選用參數
hl string
hl 參數會指示 API 針對 YouTube 網站支援的應用程式語言,擷取本地化的幣別顯示字串。舉例來說,英文會以 $1.50 顯示,但在法文中會顯示為 1,50$

參數值必須是 i18nLanguages.list 方法所傳回清單中的語言代碼。
maxResults unsigned integer
maxResults 參數會指定結果集中應傳回的訊息數量上限。可接受的值為 2002000 (含頭尾)。預設值為 500
pageToken string
pageToken 參數會指定結果集中應傳回的特定網頁。在 API 回應中,nextPageToken 屬性會識別其他可擷取的網頁。
profileImageSize unsigned integer
profileImageSize 參數會指定結果集中應傳回的使用者個人資料相片大小。圖片為正方形。預設值為 88,表示圖片應為 88 像素 x 88 像素。可接受的值介於 16720 之間 (含頭尾)。

要求主體

呼叫此方法時,不要提供要求主體。

回應

如果成功的話,這個方法會傳回回應內文,其結構如下:

{
  "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 要求和回應。