Subscriptions: list

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

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

常見用途

要求

HTTP 要求

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

參數

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

參數
必要參數
part string
part 參數會指定一或多個 subscription 資源屬性的半形逗號分隔清單，API 回應會包含這些屬性。

如果參數識別的屬性包含子項屬性，回應中就會包含子項屬性。舉例來說，在 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 要求和回應。