CommentThreads: list

傳回符合 API 要求參數的註解串清單。

配額影響:呼叫此方法的配額費用為 1 單位。

常見用途

要求

HTTP 要求

GET https://www.googleapis.com/youtube/v3/commentThreads

參數

下表列出這項查詢支援的參數。上方列出的所有參數都是查詢參數。

參數
必要參數
part string
part 參數指定以逗號分隔的一或多個清單,其中包含 API 回應將包含的 commentThread 資源屬性。

以下清單包含可包含在參數值中的 part 名稱:
  • id
  • replies
  • snippet
篩選器 (請僅指定下列其中一個參數)
allThreadsRelatedToChannelId string
allThreadsRelatedToChannelId 參數會指示 API 傳回與指定頻道相關聯的所有註解執行緒。包含頻道或留言的影片留言。
channelId string
channelId 參數會指示 API 傳回含有指定頻道留言的註解串。(回覆中不會包含頻道上傳的影片)。
id string
id 參數可指定應擷取資源的註解執行緒 ID 清單 (以半形逗號分隔)。
videoId string
videoId 參數會指示 API 傳回與指定影片 ID 相關聯的註解執行緒。
選用參數
maxResults unsigned integer
maxResults 參數會指定要在結果集中傳回的項目數量上限。

注意:這個參數無法與 id 參數搭配使用。可接受的值為 1100 (含首尾)。預設值為 20
moderationStatus string
這個參數只能在妥善的授權要求中使用。設定這個參數,即可將傳回的註解執行緒限制在特定審核狀態。

注意:這個參數無法與 id 參數搭配使用。預設值為 published

可接受的值為:
  • heldForReview - 擷取等待管理員審核的留言串。如果頂層留言或該則留言的其中至少一則回覆尚待審核,您就可以在回應中加入留言串。
  • likelySpam – 擷取已分類為垃圾留言的會話串。如果頂層留言或該留言有至少一則回覆疑似垃圾內容,您可以在回覆中加入留言串。
  • published:擷取已發布留言的對話串。此為預設值。假如該則留言的頂層留言已發布,你可在回應中加入註解串。
order string
order 參數會指定 API 回應應按照何種順序列出註解執行緒。有效值為:
  • time - 留言串會按時間排序。此為預設行為。
  • relevance - 留言串會依據關聯性排序。
注意:這個參數無法與 id 參數搭配使用。
pageToken string
pageToken 參數可指定要傳回結果集中的網頁。在 API 回應中,nextPageToken 屬性可識別可供擷取的結果的下一頁。

注意:這個參數無法與 id 參數搭配使用。
searchTerms string
searchTerms 參數會指示 API 將 API 回應限制為只包含含有指定搜尋字詞的註解。

注意:這個參數無法與 id 參數搭配使用。
textFormat string
請將這個參數的值設為 htmlplainText,指示 API 傳回使用者以 HTML 格式或純文字格式留下的註解。預設值為 html

可接受的值為:
  • html — 以 HTML 格式傳回註解。這是預設值。
  • plainText — 以純文字格式傳回註解。

要求主體

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

回應

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

{
  "kind": "youtube#commentThreadListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    commentThread Resource
  ]
}

屬性

下表定義此資源中顯示的屬性:

屬性
kind string
識別 API 資源類型。這個值會是 youtube#commentThreadListResponse
etag etag
這項資源的 Etag。
nextPageToken string
這個符記可用做 pageToken 參數的值,以擷取結果集的下一頁。
pageInfo object
pageInfo 物件會封裝結果集的分頁資訊。
pageInfo.totalResults integer
結果集中的結果總數。
pageInfo.resultsPerPage integer
API 回應中包含的結果數量。
items[] list
符合要求條件的註解串清單。

錯誤

下表說明 API 在回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息說明文件。

錯誤類型 錯誤詳細資料 說明
badRequest (400) operationNotSupported 這個 ID 篩選器只能和 Google+ 留言功能相容。
badRequest (400) processingFailure API 伺服器無法成功處理要求。雖然這可能是暫時性錯誤,但通常表示要求的輸入內容無效。檢查要求主體中的 commentThread 資源結構,確認資源有效。
forbidden (403) commentsDisabled videoId 參數識別的影片已停用留言功能。
forbidden (403) forbidden 權限不足,無法擷取一或多個要求的註解執行緒。要求可能未獲適當授權。
notFound (404) channelNotFound 找不到以 channelIdallThreadsRelatedToChannelId 參數識別的頻道。
notFound (404) commentThreadNotFound 找不到指定的指定會話串。檢查要求的 id 參數值是否正確。
notFound (404) videoNotFound 找不到以 videoId 參數識別的影片。

試試看!

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