CommentThreads: list

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

配額影響：呼叫這個方法會產生 1 個單位的配額費用。

常見用途

要求

HTTP 要求

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

參數

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

參數
必要參數
part string
part 參數會指定一或多個 commentThread 資源屬性，並以逗號分隔，API 回應會包含這些屬性。

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

注意：不支援搭配 id 參數使用這項參數。可接受的值為 1 至 100 (含)。預設值為 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
將這個參數的值設為 html 或 plainText，指示 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 找不到 allThreadsRelatedToChannelId 參數指定的頻道。
notFound (404) commentThreadNotFound 找不到一或多個指定的留言串。檢查要求中 id 參數的值，確認是否正確。
notFound (404) videoNotFound 找不到 videoId 參數指定的影片。

試試看！

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