Wdrożenie: filmy

Poniższe przykłady pokazują, jak używać interfejsu YouTube Data API (wersja 3) do wykonywania funkcji związanych z filmami.

Pobieranie filmów przesłanych na kanał

Ten przykład pokazuje, jak pobrać filmy przesłane na konkretny kanał. Przykład obejmuje 2 etapy:

Ten przykład pokazuje, jak pobrać listę najpopularniejszych filmów w YouTube, które są wybierane za pomocą algorytmu łączącego wiele różnych sygnałów w celu określenia ogólnej popularności.

Aby pobrać listę najpopularniejszych filmów, wywołaj metodę videos.list i ustaw wartość parametru chart na mostPopular. Wykres mostPopular obejmuje zyskujące popularność teledyski, filmy i filmy o grach.

Następnie możesz opcjonalnie ustawić te parametry:

  • regionCode: informuje interfejs API, aby zwrócił listę filmów z określonego regionu. Wartość parametru to kod kraju w formacie ISO 3166-1 alfa-2. Aby pobrać listę kodów regionów obsługiwanych przez YouTube, możesz użyć metody i18nRegions.list.
  • videoCategoryId: identyfikuje kategorię filmu, dla której mają zostać pobrane najpopularniejsze filmy. Aby pobrać listę identyfikatorów kategorii obsługiwanych przez YouTube, możesz użyć metody videoCategories.list.

Na przykład to żądanie pobiera najpopularniejsze filmy o sporcie w Hiszpanii:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

Pobieranie zbiorczych statystyk filmów

Ten przykład pokazuje, jak pobrać statystyki listy filmów za pomocą metody videos.batchGetStats.

Aby użyć tej metody, ustaw parametr id żądania na listę identyfikatorów filmów w YouTube rozdzielonych przecinkami, dla których chcesz pobrać statystyki. Ustaw wartość parametru part na listę rozdzielonych przecinkami części zasobu videoStat, które mają zostać uwzględnione w odpowiedzi. Obsługiwane części to snippet, statistics, contentDetails i id.

Aby użyć tej metody w przypadku filmów niepublicznych, wymagane jest uwierzytelnienie, ale w przypadku filmów publicznych nie jest ono konieczne. Jeśli żądanie pobiera dane dotyczące filmów niepublicznych, musi być odpowiednio autoryzowane.

Poniższe żądanie pobiera statystyki filmów o identyfikatorach VIDEO_ID_1 i VIDEO_ID_2:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

Przesyłanie filmów

Ponieważ narzędzie APIs Explorer nie obsługuje przesyłania plików, ten opis nie zawiera linku do wykonywalnego przykładu. Te materiały pomogą Ci zmodyfikować aplikację, aby mogła przesyłać filmy za pomocą interfejsu API w wersji 3:

  • Dokumentacja metody videos.insert interfejsu API zawiera kilka przykładów kodu, które pokazują, jak przesyłać filmy w różnych językach programowania.

  • Przewodnik dotyczący przesyłania z możliwością wznowienia opisuje sekwencję żądań HTTP, których aplikacja używa do przesyłania filmów za pomocą procesu przesyłania z możliwością wznowienia. Przewodnik jest przeznaczony głównie dla programistów, którzy nie mogą korzystać z bibliotek klienta interfejsu API Google, z których niektóre zapewniają natywną obsługę przesyłania z możliwością wznowienia.

  • Przykład w JavaScript dotyczący przesyłania filmu używa CORS (współdzielenia zasobów między serwerami z różnych domen), aby pokazać, jak przesłać plik wideo za pomocą strony internetowej. Biblioteka przesyłania CORS, której używa interfejs API w wersji 3, naturalnie obsługuje przesyłanie z możliwością wznowienia. Ponadto przykład pokazuje, jak sprawdzić stan przesłanego filmu, pobierając część processingDetails zasobu video, oraz jak obsługiwać zmiany stanu przesłanego filmu.

Sprawdzanie stanu przesłanego filmu

Ten przykład pokazuje, jak sprawdzić stan przesłanego filmu. Przesłany film będzie od razu widoczny w kanale przesłanych filmów uwierzytelnionego użytkownika. Film nie będzie jednak widoczny w YouTube, dopóki nie zostanie przetworzony.

  • Krok 1. Prześlij film

    Wywołaj metodę videos.insert, aby przesłać film. Jeśli żądanie się powiedzie, odpowiedź interfejsu API będzie zawierać zasób video, który identyfikuje unikalny identyfikator przesłanego filmu.

  • Krok 2. Sprawdź stan filmu

    Wywołaj metodę videos.list, aby sprawdzić stan filmu. Ustaw wartość parametru id na identyfikator filmu uzyskany w kroku 1. Ustaw wartość parametru part na processingDetails.

    Jeśli żądanie zostanie obsłużone, odpowiedź interfejsu API będzie zawierać zasób video. Sprawdź wartość właściwości processingDetails.processingStatus, aby określić, czy YouTube nadal przetwarza film. Gdy YouTube zakończy przetwarzanie filmu, wartość właściwości zmieni się na inną niż processing, np. succeeded lub failed.

    Treść żądania to zasób video, w którym właściwość id określa identyfikator filmu, który usuwasz. W tym przykładzie zasób zawiera też obiekt recordingDetails.

    Poniższe żądanie sprawdza stan filmu. Aby zrealizować żądanie w narzędziu APIs Explorer, musisz ustawić wartość właściwości id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID

Uwaga: Twoja aplikacja może okresowo wysyłać zapytania do interfejsu API, aby sprawdzać stan nowo przesłanego filmu. Gdy film zostanie przetworzony, aplikacja może utworzyć biuletyn lub wykonać inną czynność zależną od stanu filmu.

Aktualizowanie filmu

Ten przykład pokazuje, jak zaktualizować film, aby dodać informacje o czasie i miejscu jego nagrania. Przykład obejmuje te kroki:

  • Krok 1. Pobierz identyfikator filmu

    Wykonaj czynności opisane powyżej, aby pobrać przesłane filmy na kanał aktualnie uwierzytelnionego użytkownika. Listę można wykorzystać do wyświetlania listy filmów, używając identyfikatora każdego filmu jako klucza.

    Uwaga: istnieje wiele innych sposobów uzyskania identyfikatorów filmów, np. pobieranie wyników wyszukiwania lub wyświetlanie listy elementów na playliście. Ponieważ jednak film może być aktualizowany tylko przez jego właściciela, pierwszym krokiem w tym procesie jest prawdopodobnie pobranie listy filmów należących do użytkownika autoryzującego żądanie do interfejsu API.

  • Krok 2. Zaktualizuj film

    Wywołaj metodę videos.update, aby zaktualizować konkretny film. Ustaw wartość parametru part na recordingDetails. (Wartość parametru zależy od tego, które pola metadanych filmu są aktualizowane).

    Treść żądania to zasób video, w którym właściwość id określa identyfikator filmu, który aktualizujesz. W tym przykładzie zasób zawiera też obiekt recordingDetails.

    Poniższy przykładowy zasób wskazuje, że film został nagrany 30 października 2013 r. w Bostonie:

    {
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}

    Aby zrealizować żądanie w narzędziu APIs Explorer, musisz ustawić wartość właściwości id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

Dostęp marki z inicjatywy twórcy umożliwia właścicielowi filmu udostępnienie dostępu do niego kanałowi marki. Wymaga to części brandPartner.

Ustanawianie dostępu (klawisz Insert)

Aby ustanowić dostęp podczas przesyłania filmu, dodaj brandPartner do parametru part i podaj obiekt brandPartner w treści żądania. Aby zidentyfikować kanał firmowy, musisz określić channelId (zewnętrzny identyfikator kanału zaczynający się od „UC”) lub channelHandle (zaczynający się od „@”).

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

W odpowiedzi zostanie zwrócony tylko rozpoznany channelId.

Aktualizowanie lub usuwanie dostępu (aktualizowanie)

Aby zaktualizować dostęp do innego kanału firmowego lub usunąć dostęp, wywołaj metodę videos.update z parametrem part ustawionym na brandPartner.

Aby zastąpić dostęp, podaj nowy channelId lub channelHandle w treści żądania:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

Aby usunąć dostęp, wyślij żądanie z parametrem part ustawionym na brandPartner, ale z pustym obiektem brandPartner w treści żądania:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

Przesyłanie niestandardowej miniatury i ustawianie jej dla filmu

Aby przesłać niestandardową miniaturę i ustawić ją dla filmu, możesz użyć metody thumbnails.set interfejsu API w wersji 3. W żądaniu wartość parametru videoId identyfikuje film, dla którego będzie używana miniatura.

Tego zapytania nie można przetestować za pomocą narzędzia APIs Explorer, ponieważ nie obsługuje ono przesyłania plików multimedialnych, co jest wymagane w przypadku tej metody.

Powiązane przykłady kodu: PHP, Python

Usuwanie filmów

Ten przykład pokazuje, jak usunąć film. Przykład obejmuje te kroki:

  • Krok 1. Pobierz identyfikator filmu

    Wykonaj czynności opisane powyżej, aby pobrać przesłane filmy na kanał aktualnie uwierzytelnionego użytkownika. Listę można wykorzystać do wyświetlania listy filmów, używając identyfikatora każdego filmu jako klucza.

    Uwaga: istnieje wiele innych sposobów uzyskania identyfikatorów filmów, np. pobieranie wyników wyszukiwania lub wyświetlanie listy elementów na playliście. Ponieważ jednak film może być usuwany tylko przez jego właściciela, pierwszym krokiem w tym procesie jest prawdopodobnie pobranie listy filmów należących do użytkownika autoryzującego żądanie do interfejsu API.

  • Krok 2. Usuń film

    Wywołaj metodę videos.delete, aby usunąć konkretny film. W żądaniu parametr id określa identyfikator filmu, który usuwasz. Żądanie musi być autoryzowane za pomocą protokołu OAuth 2.0. Jeśli testujesz to zapytanie w narzędziu APIs Explorer, musisz zastąpić wartość parametru id prawidłowym identyfikatorem filmu.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID

Zgłaszanie obraźliwego filmu

Ten przykład pokazuje, jak zgłosić film zawierający nieodpowiednie treści. Przykład obejmuje te kroki:

  • Krok 1. Pobierz identyfikatory wyjaśniające, dlaczego film jest zgłaszany

    Wyślij autoryzowane żądanie do metody videoAbuseReportReasons.list, aby pobrać listę prawidłowych powodów oznaczania filmu. Przykładowy zasób videoAbuseReportReason poniżej zawiera informacje o oznaczaniu filmu zawierającego spam lub treści wprowadzające w błąd.

    {
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

    Jak widać w zasobie, ten powód jest powiązany z listą powodów dodatkowych. Oznaczając film jako zawierający spam, musisz podać identyfikator powodu i zdecydowanie zalecamy podanie też powodu dodatkowego.

  • Krok 2. Zgłoś film jako zawierający nieodpowiednie treści

    Aby zgłosić film, wyślij autoryzowane żądanie do metody videos.reportAbuse. Treść żądania to obiekt JSON, który identyfikuje zarówno oznaczany film, jak i powód jego oznaczenia. Jak wspomnieliśmy w kroku 1, w przypadku niektórych typów powodów obsługiwany jest powód dodatkowy, którego podanie jest zdecydowanie zalecane.

    Właściwość videoId obiektu JSON identyfikuje oznaczany film.

    Przykładowy obiekt JSON poniżej oznacza film jako zawierający spam lub treści wprowadzające w błąd, a konkretnie jako używający wprowadzającej w błąd miniatury. Jak widać w przykładowym obiekcie JSON powyżej, identyfikator treści Spam lub wprowadzające w błąd to S. Identyfikator Wprowadzającej w błąd miniatury to 28.

    {
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}

    Żądanie videos.reportAbuse musi być autoryzowane za pomocą protokołu OAuth 2.0. Link poniżej wczytuje obiekt JSON powyżej w narzędziu APIs Explorer. Aby przetestować zapytanie, musisz zastąpić wartość właściwości videoId prawidłowym identyfikatorem filmu. Pamiętaj, że przesłanie tego żądania spowoduje oznaczenie filmu.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse