Subscriptions: list

Zwraca zasoby subskrypcji, które spełniają kryteria żądania do interfejsu API.

Wpływ limitu: wywołanie tej metody ma limit limitu wynoszący 1 jednostkę.

Typowe przypadki użycia

Żądanie

Żądanie HTTP

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

Parametry

W poniższej tabeli podano parametry obsługiwane przez to zapytanie. Wszystkie wymienione parametry są parametrami zapytania.

Parametry
Parametry wymagane
part string
Parametr part określa rozdzieloną przecinkami listę co najmniej jednej właściwości zasobu subscription, która ma być uwzględniona w odpowiedzi interfejsu API.

Jeśli parametr wskazuje właściwość zawierającą właściwości podrzędne, zostaną one uwzględnione w odpowiedzi. Na przykład w zasobie subscription właściwość snippet zawiera inne właściwości, takie jak wyświetlany tytuł subskrypcji. Jeśli ustawisz part=snippet, odpowiedź interfejsu API będzie też zawierać wszystkie te zagnieżdżone właściwości.

Ta lista zawiera nazwy part, które możesz uwzględnić w wartości parametru:
  • contentDetails
  • id
  • snippet
  • subscriberSnippet
Filtry (podaj jeden z tych parametrów)
channelId string
Parametr channelId określa identyfikator kanału YouTube. Interfejs API zwróci tylko subskrypcje tego kanału.
id string
Parametr id określa oddzieloną przecinkami listę identyfikatorów subskrypcji YouTube dla pobieranych zasobów. W zasobie subscription właściwość id określa identyfikator subskrypcji YouTube.
mine boolean
Ten parametr może być używany tylko w poprawnie autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobierać subskrypcje subskrypcji uwierzytelnionego użytkownika.
myRecentSubscribers boolean
Ten parametr może być używany tylko w poprawnie autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobierać kanały subskrybentów uwierzytelnionego użytkownika w odwrotnej kolejności chronologicznej (od najnowszych).

Pamiętaj, że maksymalna liczba subskrybentów zwracanych przez ten interfejs API może być ograniczona.
mySubscribers boolean
Ten parametr może być używany tylko w poprawnie autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobierać kanały subskrybentów uwierzytelnionego użytkownika w określonej kolejności. Pamiętaj, że maksymalna liczba subskrybentów zwróconych przez ten interfejs API może być ograniczona.
Parametry opcjonalne
forChannelId string
Parametr forChannelId określa rozdzieloną przecinkami listę identyfikatorów kanałów. Odpowiedź interfejsu API będzie wtedy zawierać tylko subskrypcje pasujące do tych kanałów.
maxResults unsigned integer
Parametr maxResults określa maksymalną liczbę elementów, które powinny zostać zwrócone w zestawie wyników. Akceptowane wartości to 0–50 (włącznie). Wartością domyślną jest 5.
onBehalfOfContentOwner string
Uwaga: ten parametr jest przeznaczony wyłącznie dla partnerów w zakresie treści w YouTube.

Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające żądania wskazują użytkownika YouTube CMS, który działa w imieniu właściciela treści określonego w wartości parametru. Ten parametr jest przeznaczony dla partnerów w sieci reklamowej YouTube, którzy mają wiele kanałów YouTube i zarządzają nimi. Umożliwia właścicielom treści uwierzytelnianie tylko raz oraz dostęp do wszystkich filmów i kanałów bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna. Konto CMS, za pomocą którego użytkownik się uwierzytelni, musi być połączone z określonym właścicielem treści w YouTube.
onBehalfOfContentOwnerChannel string
Ten parametr może być używany tylko w poprawnie autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony tylko dla dostawców treści w YouTube.

Parametr onBehalfOfContentOwnerChannel określa identyfikator kanału YouTube, do którego jest dodawany film. Ten parametr jest wymagany, gdy żądanie określa wartość parametru onBehalfOfContentOwner i można go używać tylko w połączeniu z tym parametrem. Dodatkowo żądanie musi być autoryzowane za pomocą konta CMS połączonego z właścicielem treści, które jest określone w parametrze onBehalfOfContentOwner. Na koniec kanał, który określa parametr onBehalfOfContentOwnerChannel, musi być powiązany z właścicielem treści, który jest określony przez parametr onBehalfOfContentOwner.

Ten parametr jest przeznaczony dla partnerów w sieci reklamowej YouTube, którzy mają wiele kanałów YouTube i zarządzają nimi. Umożliwia właścicielom treści uwierzytelnianie raz i wykonywanie działań w imieniu kanału określonego w wartości parametru, bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna.
order string
Parametr order określa metodę, która będzie używana do sortowania zasobów w odpowiedzi interfejsu API. Wartość domyślna to SUBSCRIPTION_ORDER_RELEVANCE.

Akceptowane wartości to:
  • alphabetical – sortowanie alfabetycznie,
  • relevance – sortuj według trafności.
  • unread – sortowanie według aktywności.
pageToken string
Parametr pageToken wskazuje konkretną stronę w zestawie wyników, która powinna zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken wskazują inne strony, które można pobrać.

Treść żądania

Podczas wywoływania tej metody nie podawaj treści żądania.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź w następującym formacie:

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

Usługi

Poniższa tabela określa właściwości, które pojawiają się w tym zasobie:

Usługi
kind string
Określa typ zasobu interfejsu API. Wartość będzie wynosić youtube#subscriptionListResponse.
etag etag
Otagowanie tego zasobu.
nextPageToken string
Token, który może zostać użyty jako wartość parametru pageToken, by pobrać następną stronę z zestawu wyników.
prevPageToken string
Token, którego można użyć jako wartości parametru pageToken w celu pobrania poprzedniej strony z zestawu wyników.
pageInfo object
Obiekt pageInfo zawiera informacje o stronicowaniu dla zestawu wyników.
pageInfo.totalResults integer
Łączna liczba wyników w zestawie wyników.
pageInfo.resultsPerPage integer
Liczba wyników zawartych w odpowiedzi interfejsu API.
items[] list
Lista subskrypcji spełniających kryteria żądania.

Błędy

W tabeli poniżej znajdziesz komunikaty o błędach, które interfejs API może zwrócić w odpowiedzi na wywołanie tej metody. Więcej informacji znajdziesz w dokumentacji komunikatów o błędach.

Typ błędu Szczegóły błędu Opis
forbidden (403) accountClosed Nie udało się pobrać subskrypcji, ponieważ konto subskrybenta jest zamknięte.
forbidden (403) accountSuspended Nie udało się pobrać subskrypcji, ponieważ konto subskrybenta jest zawieszone.
forbidden (403) subscriptionForbidden Osoba, która wysłała prośbę, nie ma dostępu do wybranych subskrypcji.
notFound (404) subscriberNotFound Nie udało się znaleźć subskrybenta określonego w żądaniu.

Wypróbuj

Użyj APIs Explorer, aby wywołać ten interfejs API i wyświetlić żądanie oraz odpowiedź interfejsu API.