Subscriptions: list

Zwraca zasoby subskrypcji spełniające kryteria żądania do interfejsu API.

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

Typowe przypadki użycia

Prośba

Żądanie HTTP

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

Parametry

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

Parametry
Parametry wymagane
part string
Parametr part określa oddzieloną przecinkami listę właściwości zasobu subscription, które będzie zawierać odpowiedź interfejsu API.

Jeśli parametr wskazuje właściwość zawierającą właściwości podrzędne, w odpowiedzi zostaną uwzględnione właściwości podrzędne. 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 zawierać wszystkie te zagnieżdżone właściwości.

Na poniższej liście znajdziesz nazwy parametrów part, które możesz uwzględnić w wartości parametru:
  • contentDetails
  • id
  • snippet
  • subscriberSnippet
Filtry (określ dokładnie jeden z tych parametrów)
channelId string
Parametr channelId określa identyfikator kanału w YouTube. Zwróci jedynie subskrypcje tego kanału.
id string
Parametr id określa rozdzieloną przecinkami listę identyfikatorów subskrypcji YouTube dla pobieranych zasobów. W zasobie subscription właściwość id określa identyfikator subskrypcji YouTube.
mine boolean
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobrać kanał subskrypcji uwierzytelnionego użytkownika.
myRecentSubscribers boolean
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobierać plik danych o subskrybentach uwierzytelnionego użytkownika w odwrotnej kolejności chronologicznej (malejąco).

Pamiętaj, że maksymalna liczba subskrybentów zwróconych przez ten interfejs API może być ograniczona.
mySubscribers boolean
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby pobierać plik danych z danymi subskrybentów uwierzytelnionego użytkownika w kolejności losowej. Pamiętaj, że maksymalna liczba subskrybentów zwracanych za pomocą tego interfejsu API może być ograniczona.
Parametry opcjonalne
forChannelId string
Parametr forChannelId zawiera listę identyfikatorów kanałów rozdzielonych przecinkami. 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 zbiorze wyników. Akceptowane wartości to od 0 do 50 (włącznie). Wartością domyślną jest 5.
onBehalfOfContentOwner string
Uwaga: ten parametr jest przeznaczony wyłącznie dla dostawców treści w YouTube.

Parametr onBehalfOfContentOwner wskazuje, że dane uwierzytelniające żądanie identyfikują użytkownika YouTube CMS działającego w imieniu właściciela treści określonego w wartości parametru. Jest on przeznaczony dla dostawców treści w YouTube, którzy mają wiele różnych kanałów w YouTube i nimi zarządzają. Dzięki niej właściciele treści mogą jednorazowo uwierzytelnić się i uzyskiwać dostęp do wszystkich swoich filmów oraz danych dotyczących kanałów bez konieczności podawania danych uwierzytelniających dla każdego kanału z osobna. Konto CMS, za pomocą którego użytkownik uwierzytelnia się, musi być powiązane z określonym właścicielem treści YouTube.
onBehalfOfContentOwnerChannel string
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Uwaga: ten parametr jest przeznaczony wyłącznie dla dostawców treści w YouTube.

Parametr onBehalfOfContentOwnerChannel określa identyfikator kanału w YouTube, do którego jest dodawany film. Ten parametr jest wymagany, gdy w żądaniu określona jest wartość parametru onBehalfOfContentOwner i można go używać tylko w połączeniu z tym parametrem. Prośba musi być dodatkowo autoryzowana za pomocą konta CMS połączonego z właścicielem treści określonym w parametrze onBehalfOfContentOwner. Kanał wskazany za pomocą parametru onBehalfOfContentOwnerChannel musi być połączony z właścicielem treści określonym w parametrze onBehalfOfContentOwner.

Ten parametr jest przeznaczony dla partnerów dostarczających treści do YouTube, którzy są właścicielami wielu różnych kanałów YouTube i nimi zarządzają. Pozwala właścicielom treści jednorazowo uwierzytelnić się i wykonywać działania 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:
  • alphabetical – alfabetycznie.
  • relevance – posortowane według trafności.
  • unread – sortuj według kolejności aktywności.
pageToken string
Parametr pageToken wskazuje w zestawie wyników konkretną stronę, która ma zostać zwrócona. W odpowiedzi interfejsu API właściwości nextPageToken i prevPageToken identyfikują inne strony, które można pobrać.

Treść żądania

Nie podawaj treści żądania podczas wywoływania tej metody.

Odpowiedź

Jeśli operacja się uda, metoda zwróci odpowiedź o następującej strukturze:

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

Właściwości

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

Właściwości
kind string
Określa typ zasobu interfejsu API. Wartością będzie youtube#subscriptionListResponse.
etag etag
ETag tego zasobu.
nextPageToken string
Token, który może być używany jako wartość parametru pageToken w celu pobrania następnej strony w zestawie wyników.
prevPageToken string
Token, który może być używany jako wartość parametru pageToken do pobierania poprzedniej strony w zestawie wyników.
pageInfo object
Obiekt pageInfo zawiera informacje o stronicowaniu zbioru wyników.
pageInfo.totalResults integer
Łączna liczba wyników w zestawie.
pageInfo.resultsPerPage integer
Liczba wyników uwzględnionych 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 szczegółów 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 Zgłaszający nie ma dostępu do żądanych subskrypcji.
notFound (404) subscriberNotFound Nie udało się znaleźć subskrybenta wskazanego w żądaniu.

Wypróbuj

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