Channels: list

Uwaga: wartość właściwości statistics.subscriberCount zasobu channel została zaktualizowana, aby uwzględnić zmianę zasad YouTube, która wpływa na sposób wyświetlania liczby subskrybentów. Więcej informacji znajdziesz w historii zmian lub w Centrum pomocy YouTube.

Zwraca zbiór zawierający 0 lub więcej zasobów channel, które spełniają kryteria żądania.

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/channels

Upoważnienie

Żądanie, które pobiera część auditDetails zasobu channel, musi zawierać token autoryzacji zawierający zakres https://www.googleapis.com/auth/youtubepartner-channel-audit. Dodatkowo każdy token korzystający z tego zakresu musi zostać unieważniony, gdy sieć wielokanałowa zdecyduje się zaakceptować lub odrzucić kanał albo w ciągu 2 tygodni od daty jego wystawienia.

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 channel, 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 channel właściwość contentDetails zawiera inne właściwości, takie jak uploads. Jeśli więc ustawisz właściwość part=contentDetails, 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:
  • auditDetails
  • brandingSettings
  • contentDetails
  • contentOwnerDetails
  • id
  • localizations
  • snippet
  • statistics
  • status
  • topicDetails
Filtry (określ dokładnie jeden z tych parametrów)
categoryId string
Ten parametr został wycofany. Parametr categoryId określał kategorię przewodnika YouTube i można go użyć, aby przesłać zgłoszenie dotyczące kanałów w YouTube powiązanych z tą kategorią.
forHandle string
Parametr forHandle określa nick YouTube, a tym samym wysyła żądanie do kanału powiązanego z tym nickem. Wartość parametru może być na początku symbolem @. Aby na przykład pobrać zasób kanału „Google for Developers”, ustaw wartość parametru forHandle na GoogleDevelopers lub @GoogleDevelopers.
forUsername string
Parametr forUsername określa nazwę użytkownika YouTube, a tym samym wysyła żądanie dotyczące kanału powiązanego z tą nazwą.
id string
Parametr id zawiera rozdzieloną przecinkami listę identyfikatorów kanałów w YouTube dla pobieranych zasobów. W zasobie channel właściwość id określa identyfikator kanału w YouTube.
managedByMe boolean
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.

Ustaw jego wartość na true, aby interfejs API zwracał tylko kanały zarządzane przez właściciela treści określone w parametrze onBehalfOfContentOwner. Użytkownik musi być uwierzytelniony jako konto CMS połączone z określonym właścicielem treści i musi zostać podany onBehalfOfContentOwner.
mine boolean
Tego parametru można używać tylko w prawidłowo autoryzowanym żądaniu. Ustaw wartość tego parametru na true, aby interfejs API zwracał tylko kanały należące do uwierzytelnionego użytkownika.
Parametry opcjonalne
hl string
Parametr hl informuje interfejs API, aby pobierał zlokalizowane metadane zasobów dla określonego języka aplikacji obsługiwanego przez witrynę YouTube. Wartość parametru musi być kodem języka znajdującym się na liście zwracanej przez metodę i18nLanguages.list.

Jeśli w danym języku dostępne są zlokalizowane szczegóły zasobów, obiekt snippet.localized zasobu będzie zawierał te wartości. Jeśli jednak zlokalizowane szczegóły nie są dostępne, obiekt snippet.localized będzie zawierał szczegóły zasobu w domyślnym języku zasobu.
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
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 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.
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#channelListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    channel 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#channelListResponse.
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 zbiorze wyników. Pamiętaj, że ta właściwość nie jest uwzględniona w odpowiedzi interfejsu API, jeśli odpowiednie żądanie do interfejsu API ustawiło parametr managedByMe na true.
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 kanałów 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
badRequest (400) invalidCriteria Można określić maksymalnie jeden z tych filtrów:id, categoryId, mine, managedByMe, forHandle, forUsername. W przypadku uwierzytelniania właściciela treści za pomocą parametru onBehalfOfContentOwner można określić tylko id lub managedByMe.
forbidden (403) channelForbidden Kanał określony przez parametr id nie obsługuje żądania lub żądanie nie jest prawidłowo autoryzowane.
notFound (404) categoryNotFound Nie udało się znaleźć kategorii określonej przez parametr categoryId. Aby pobrać listę prawidłowych wartości, użyj metody guideCategories.list.
notFound (404) channelNotFound Nie udało się znaleźć kanału określonego w parametrze id.

Wypróbuj

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