本頁面由 Cloud Translation API 翻譯而成。

Subscriptions: list

傳回符合 API 要求條件的訂閱資源。

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

常見用途

要求

HTTP 要求

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

參數

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

參數
必要參數
`part`	`string` `part` 參數會指定以逗號分隔的清單，其中包含 API 回應所包含的一或多個 `subscription` 資源屬性。如果參數指定的屬性包含子項資源，則子屬性將納入回應中。舉例來說，在 `subscription` 資源中，`snippet` 屬性包含其他屬性，例如訂閱項目的顯示名稱。如果設定 `part=snippet`，API 回應也會包含這些巢狀屬性。以下清單包含可在參數值中加入的 `part` 名稱： `contentDetails` `id` `snippet` `subscriberSnippet`
篩選器 (請僅指定下列其中一個參數)
`channelId`	`string` `channelId` 參數會指定 YouTube 頻道 ID。API 只會傳回該頻道的訂閱項目。
`id`	`string` `id` 參數可指定擷取的資源的 YouTube 訂閱 ID 清單 (以半形逗號分隔)。在 `subscription` 資源中，`id` 屬性可指定 YouTube 訂閱 ID。
`mine`	`boolean` 這個參數只能在妥善的授權要求中使用。將這個參數的值設為 `true`，即可擷取已驗證使用者的訂閱項目的資訊提供。
`myRecentSubscribers`	`boolean` 這個參數只能在妥善的授權要求中使用。請將這個參數的值設為 `true`，即可按時間先後順序 (由新到舊) 擷取已驗證使用者的訂閱者動態饋給。請注意，透過這個 API 傳回的訂閱者數量上限可能會受到限制。
`mySubscribers`	`boolean` 這個參數只能在妥善的授權要求中使用。將這個參數的值設為 `true` 即可擷取已驗證使用者的訂閱者動態饋給，其順序沒有特定順序。請注意，透過這個 API 傳回的訂閱者數量上限可能會受到限制。
選用參數
`forChannelId`	`string` `forChannelId` 參數會指定以逗號分隔的管道 ID 清單。這樣一來，API 回應就會只包含符合這些頻道的訂閱項目。
`maxResults`	`unsigned integer` `maxResults` 參數會指定要在結果集中傳回的項目數量上限。可接受的值為 `0` 到 `50` (含首尾)。預設值為 `5`。
`onBehalfOfContentOwner`	`string` 注意：這個參數僅適用於 YouTube 內容合作夥伴。 `onBehalfOfContentOwner` 參數表示請求的授權憑證可用來代表在參數值中指定的內容擁有者所擔任的 YouTube CMS 使用者。這個參數適用於擁有和管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要驗證一次即可，就能存取所有影片和頻道資料，而不需要為每個頻道分別提供驗證憑證。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
`onBehalfOfContentOwnerChannel`	`string` 這個參數只能在妥善的授權要求中使用。注意：這個參數僅適用於 YouTube 內容合作夥伴。 `onBehalfOfContentOwnerChannel` 參數會指定影片所屬頻道的 YouTube 頻道 ID。如果要求指定了 `onBehalfOfContentOwner` 參數的值，就必須使用這個參數，而且這個參數只能搭配該參數使用。此外，要求必須使用連結至 `onBehalfOfContentOwner` 參數指定內容擁有者的 CMS 帳戶。最後，`onBehalfOfContentOwnerChannel` 參數值指定的管道必須連結至 `onBehalfOfContentOwner` 參數指定的內容擁有者。這個參數適用於擁有和管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。這樣內容擁有者就能驗證一次，並且能代表參數值指定的頻道執行動作，而不必分別為每個頻道提供驗證憑證。
`order`	`string` `order` 參數會指定在 API 回應中用來排序資源的方法。預設值為 `SUBSCRIPTION_ORDER_RELEVANCE`。可接受的值為： `alphabetical` - 按字母順序排列。 `relevance` – 依關聯性排序。 `unread`：依活動順序排序。
`pageToken`	`string` `pageToken` 參數可指定要傳回結果集中的網頁。在 API 回應中，`nextPageToken` 和 `prevPageToken` 屬性可識別其他可擷取的網頁。

要求主體

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

回應

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

{
  "kind": "youtube#subscriptionListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    subscription Resource
  ]
}

屬性

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

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

錯誤

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

錯誤類型	錯誤詳細資料	說明
`forbidden (403)`	`accountClosed`	系統無法擷取訂閱項目，因為訂閱者的帳戶已關閉。
`forbidden (403)`	`accountSuspended`	系統無法擷取訂閱項目，因為該訂閱者的帳戶已遭停權。
`forbidden (403)`	`subscriptionForbidden`	要求者無法存取您要求的訂閱項目。
`notFound (404)`	`subscriberNotFound`	找不到與要求相關聯的訂閱者。

試試看！

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