Videos: list

API リクエストのパラメータに一致する動画のリストを返します。 今すぐ試すまたは例を見る

リクエスト

HTTP リクエスト

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

パラメータ

下記の表は、このクエリでサポートされているパラメータの一覧です。このリストのパラメータはすべてクエリ パラメータです。

パラメータ
必須パラメータ
part string
part パラメータには、API レスポンスに含まれる 1 つまたは複数の video リソース プロパティをカンマ区切りリストの形式で指定します。パラメータ値に指定できる part 名は、idsnippetcontentDetailsfileDetailsliveStreamingDetailsplayerprocessingDetailsrecordingDetailsstatisticsstatussuggestionstopicDetails などです。

このパラメータに子プロパティを持つプロパティが指定されている場合、その子プロパティもレスポンスに含まれます。たとえば、video リソースで、snippet プロパティに channelIdtitledescriptiontagscategoryId などのプロパティが含まれているとします。この場合、part=snippet と設定すると、API レスポンスにはこれらのプロパティすべてが含まれることになります。
フィルタ(以下のパラメータのいずれか 1 つのみを指定します)
chart string
chart パラメータには、取得するグラフを指定します。

以下の値を指定できます。
id string
id パラメータには、取得するリソースの YouTube 動画 ID をカンマ区切りリストの形式で指定します。video リソースの場合、id プロパティには動画の ID を指定します。
myRating string
このパラメータは、適切に承認されたリクエストでのみ使用できます。認証されたユーザーの高評価(like)または低評価(dislike)の動画のみを返すようにするには、このパラメータ値を like または dislike に設定します。

以下の値を指定できます。
  • dislike – 認証されたユーザーが低く評価した動画のみを返します。
  • like – 認証されたユーザーが高く評価した動画のみを返します。
省略可能なパラメータ
maxResults unsigned integer
maxResults パラメータには、結果セットで返されるアイテムの最大数を指定します。

注: このパラメータは myRating パラメータと組み合わせて使用できますが、id と一緒に使用することはできません。1 以上 50 以下の値を指定できます。デフォルト値は 5 です。
onBehalfOfContentOwner string
このパラメータは、適切に承認されたリクエストでのみ使用できます。注: このパラメータは、YouTube コンテンツ パートナー専用です。

onBehalfOfContentOwner パラメータは、リクエストの承認用認証情報が、パラメータ値で指定されたコンテンツ所有者の代理人である YouTube CMS ユーザーのものであることを示します。このパラメータは、さまざまな YouTube チャンネルを所有、管理している YouTube コンテンツ パートナーを対象にしています。このパラメータを使用すると、コンテンツ所有者は一度認証されれば、すべての動画やチャンネル データにアクセスできるようになります。チャンネルごとに認証情報を指定する必要はありません。ユーザー認証に使用する CMS アカウントは、指定された YouTube コンテンツ所有者にリンクされていなければなりません。
pageToken string
pageToken パラメータには、返される結果セットに含める特定のページを指定します。API レスポンスでは、nextPageToken および prevPageToken プロパティは取得可能な他のページを表します。

注: このパラメータは myRating パラメータと組み合わせて使用できますが、id と一緒に使用することはできません。
regionCode string
regionCode パラメータでは、指定された地域で使用できる動画グラフを選択するように API に指示します。このパラメータを使用する場合は、グラフも設定する必要があります。このパラメータの値は ISO 3166-1 alpha-2 の国コードです。
videoCategoryId string
videoCategoryId パラメータには、グラフを取得する動画のカテゴリを指定します。このパラメータは、必ず chart パラメータと組み合わせて使用しなければなりません。デフォルトでは、グラフは特定のカテゴリに制限されていません。デフォルト値は 0 です。

リクエストの本文

このメソッドを呼び出す場合は、リクエストの本文を指定しないでください。

レスポンス

成功すると、このメソッドは次の構造を持つレスポンスの本文を返します。

{
  "kind": "youtube#videoListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    動画リソース
  ]
}

プロパティ

次の表は、このリソースで使用されているプロパティの定義を示したものです。

プロパティ
kind string
API リソースのタイプ。値は youtube#videoListResponse です。
etag etag
このリソースの Etag。
nextPageToken string
結果セットの次のページを取得するために、pageToken パラメータの値として使用できるトークン。
prevPageToken string
結果セットの前のページを取得するために、pageToken パラメータの値として使用できるトークン。
pageInfo object
pageInfo オブジェクトは、結果セットのページング情報をカプセル化します。
pageInfo.totalResults integer
結果セット内の結果の総数。
pageInfo.resultsPerPage integer
API レスポンスに含まれる結果の数。
items[] list
リクエスト条件と一致する動画のリスト。

注: 以下のコード サンプルは、サポートされているプログラミング言語すべてについて表したものではありません。サポートされている言語の一覧については、クライアント ライブラリのドキュメントを参照してください。

PHP

この例では、PHP クライアント ライブラリを使用しています。

<?php

/**
 * This sample adds new tags to a YouTube video by:
 *
 * 1. Retrieving the video resource by calling the "youtube.videos.list" method
 *    and setting the "id" parameter
 * 2. Appending new tags to the video resource's snippet.tags[] list
 * 3. Updating the video resource by calling the youtube.videos.update method.
 *
 * @author Ibrahim Ulukaya
*/

// Call set_include_path() as needed to point to your client library.
require_once 'Google/Client.php';
require_once 'Google/Service/YouTube.php';
session_start();

/*
 * You can acquire an OAuth 2.0 client ID and client secret from the
 * Google Developers Console <https://console.developers.google.com/>
 * For more information about using OAuth 2.0 to access Google APIs, please see:
 * <https://developers.google.com/youtube/v3/guides/authentication>
 * Please ensure that you have enabled the YouTube Data API for your project.
 */
$OAUTH2_CLIENT_ID = 'REPLACE_ME';
$OAUTH2_CLIENT_SECRET = 'REPLACE_ME';

$client = new Google_Client();
$client->setClientId($OAUTH2_CLIENT_ID);
$client->setClientSecret($OAUTH2_CLIENT_SECRET);
$client->setScopes('https://www.googleapis.com/auth/youtube');
$redirect = filter_var('http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'],
    FILTER_SANITIZE_URL);
$client->setRedirectUri($redirect);

// Define an object that will be used to make all API requests.
$youtube = new Google_Service_YouTube($client);

if (isset($_GET['code'])) {
  if (strval($_SESSION['state']) !== strval($_GET['state'])) {
    die('The session state did not match.');
  }

  $client->authenticate($_GET['code']);
  $_SESSION['token'] = $client->getAccessToken();
  header('Location: ' . $redirect);
}

if (isset($_SESSION['token'])) {
  $client->setAccessToken($_SESSION['token']);
}

// Check to ensure that the access token was successfully acquired.
if ($client->getAccessToken()) {
  try{

    // REPLACE this value with the video ID of the video being updated.
    $videoId = "VIDEO_ID";

    // Call the API's videos.list method to retrieve the video resource.
    $listResponse = $youtube->videos->listVideos("snippet",
        array('id' => $videoId));

    // If $listResponse is empty, the specified video was not found.
    if (empty($listResponse)) {
      $htmlBody .= sprintf('<h3>Can\'t find a video with video id: %s</h3>', $videoId);
    } else {
      // Since the request specified a video ID, the response only
      // contains one video resource.
      $video = $listResponse[0];
      $videoSnippet = $video['snippet'];
      $tags = $videoSnippet['tags'];

      // Preserve any tags already associated with the video. If the video does
      // not have any tags, create a new list. Replace the values "tag1" and
      // "tag2" with the new tags you want to associate with the video.
      if (is_null($tags)) {
        $tags = array("tag1", "tag2");
      } else {
        array_push($tags, "tag1", "tag2");
      }

      // Set the tags array for the video snippet
      $videoSnippet['tags'] = $tags;

      // Update the video resource by calling the videos.update() method.
      $updateResponse = $youtube->videos->update("snippet", $video);

      $responseTags = $updateResponse['snippet']['tags'];


    $htmlBody .= "<h3>Video Updated</h3><ul>";
    $htmlBody .= sprintf('<li>Tags "%s" and "%s" added for video %s (%s) </li>',
        array_pop($responseTags), array_pop($responseTags),
        $videoId, $video['snippet']['title']);

    $htmlBody .= '</ul>';
  }
    } catch (Google_Service_Exception $e) {
      $htmlBody .= sprintf('<p>A service error occurred: <code>%s</code></p>',
          htmlspecialchars($e->getMessage()));
    } catch (Google_Exception $e) {
      $htmlBody .= sprintf('<p>An client error occurred: <code>%s</code></p>',
          htmlspecialchars($e->getMessage()));
    }

    $_SESSION['token'] = $client->getAccessToken();
    } else {
      // If the user hasn't authorized the app, initiate the OAuth flow
      $state = mt_rand();
      $client->setState($state);
      $_SESSION['state'] = $state;

      $authUrl = $client->createAuthUrl();
      $htmlBody = <<<END
  <h3>Authorization Required</h3>
  <p>You need to <a href="$authUrl">authorize access</a> before proceeding.<p>
END;
    }
    ?>

    <!doctype html>
    <html>
    <head>
    <title>Video Updated</title>
    </head>
    <body>
      <?=$htmlBody?>
    </body>
    </html>

エラー

次の表は、このメソッドを呼び出したときに API からレスポンスとして返される可能性のあるエラー メッセージの一覧です。詳細については、エラー メッセージのドキュメントを参照してください。

エラー タイプ エラーの詳細 説明
badRequest videoChartNotFound リクエストされた動画チャートはサポートされていないか、使用できません。
forbidden forbidden リクエストは、ユーザー評価情報にアクセスできません。このエラーは、リクエストが適切に認証されていないために myRating パラメータを使用できない場合に発生することがあります。

実際に試してみる

API Explorer を使用し、ライブ データに対してこのメソッドを呼び出して、API リクエストとレスポンスを確認してください。