このページは Cloud Translation API によって翻訳されました。

サンプルの API リクエスト

このページでは、YouTube Data API へのサンプルリクエストを示します。YouTube Data API を使用して、動画、チャンネル、再生リストなどの YouTube リソースを取得、操作します。各サンプルは Google APIs Explorer にリンクしてデータを入力するため、サンプルを実行してレスポンスを確認できます。

YouTube Data API を使用したコンテンツのアップロードについて詳しくは、再開可能なアップロードをご覧ください。

概要

わかりやすくするために、このページのサンプルでは各リクエストの特徴的な要素を示しており、Data API リクエストを処理するホストのベース URL（https://www.googleapis.com/youtube/v3）を省略しています。サンプルのコンテキスト以外でリクエストを行うには、完全な URL を含める必要があります。

たとえば、このページに表示されているサンプルリクエストは次のとおりです。

GET {base-URL}/channels?part=contentDetails
                       &mine=true

このリクエストの完全な URL は次のとおりです。

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

いくつかのリクエストでは、チャンネル登録者のリストなど、YouTube チャンネルの所有者のみがアクセスできるデータを取得します。このリクエストを行うには、チャンネル所有者が Google APIs Explorer に YouTube Data API リクエストを代理で実行する権利をチャンネル所有者に付与する必要があります。（非公開チャンネルデータへのアクセスの承認について詳しくは、OAuth 2.0 認証の実装をご覧ください）。API Explorer にリンクしたら、[Authorize requests using OAuth 2.0] ボタンをクリックします。このステップでは、API Explorer がオーナーに代わってリクエストを行うことを承認します。認可の範囲も選択します。これにより、API Explorer が実行できるリクエストの種類が決まります。

各リクエストに対するレスポンスは、YouTube リソースの JSON 表現です。リクエストの part パラメータは、リソースのどの部分をレスポンスに含めるかを指定します。このパラメータは、レスポンスに含めるべき 1 つ以上のトップレベル（ネストされていない）リソースプロパティを識別します。たとえば、動画リソースには次のような要素があります。

snippet
contentDetails
プレーヤー
statistics
status

これらのパーツはすべて、ネストされたプロパティを含むオブジェクトであり、API サーバーが取得する（または取得しない）メタデータフィールドのグループと考えることができます。そのため、part パラメータでは、アプリが実際に使用するリソースコンポーネントを選択する必要があります。詳しくは、YouTube Data API のスタートガイドをご覧ください。

チャンネル情報を取得する

このリクエストは、channels.list メソッドを使用して、認証されたユーザーに属するチャンネルの詳細を取得します。

GET {base_URL}/channels?part=contentDetails
                       &mine=true

このリクエストに対するレスポンスには、チャンネル ID と、認証されたユーザーのチャンネルの contentDetails が含まれます。contentDetails には、チャンネルに関連付けられているシステムが生成した複数の再生リストが含まれます。後続のリクエストの多くは、チャンネル ID または再生リスト ID のいずれかを必要とするため、それらを記録することが重要です。

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

アップロードした動画とシステムが生成した再生リスト

アップロードされたすべての動画は、チャンネルに関連付けられた再生リストに追加されます。アップロード済みの動画のリストを取得するには、「uploads」というキーワードを検索します。上記のチャンネル情報のレスポンスで返された再生リスト。playlistItems.list メソッドを使用して再生リスト内の動画を取得します。

Google APIs Explorer で次のサンプルリクエストを実行する前に、{UPLOADS_PLAYLIST_ID} を前のリクエストの再生リスト ID に置き換えてください。

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

返された各アイテムの "id" 値は、その playlistItem ID です。再生リストアイテムの動画 ID は、contentDetails 部分の videoId です。

上記のリクエストを使用して、チャンネル情報レスポンスの対応する再生リスト ID を置き換えて、ユーザーのお気に入り、高評価、再生履歴、後で見るリストを取得できます。

ユーザーが作成した再生リスト

このリクエストでは、playlists.list メソッドを使用して、認証されたチャンネルに関連付けられた再生リストを取得します。なお、このリクエストでは、チャンネル情報（アップロード、watchHistory など）に含まれるシステム生成の再生リストは取得されません。ユーザーが作成した再生リストのみを取得します。

GET {base_URL}/playlists?part=snippet
                        &mine=true

再生リスト ID を取得したら、前のセクションで示したリクエストを使用して再生リストからアイテムを取得できます。

チャンネルの公開再生リストに関する情報は、認証なしでリクエストできます。未認証のリクエストを送信する場合は、リクエストを行うアプリケーションの一意の API キーを指定する key 引数を含める必要があります。たとえば、GoogleDevelopers チャンネルに関連付けられた再生リストを取得します。

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

サブスクリプションを取得する

subscription リソースは、YouTube ユーザー（チャンネル登録者）とチャンネルとの関係を定義します。subscriptions.list メソッドは、リクエストに含めたパラメータに応じて、特定のチャンネルの登録者や特定ユーザーの登録者を取得します。

チャンネルの登録者数

このリクエストは、認証されたチャンネルの登録者のリストを取得します。

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

ユーザーの登録

チャンネル登録者を一覧表示するのと同じメソッド（subscriptions.list）を使用して、ユーザーが登録しているチャンネルの一覧を表示できます。このリクエストは、mine パラメータを使用して、認証されたユーザーが登録している YouTube チャンネルのリストを取得します。

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

ユーザーアクティビティを取得する

activity リソースには、特定のチャンネルやユーザーが YouTube で行った操作（動画のアップロード、チャンネルへの登録など）に関する情報が含まれます。activities.list メソッドは、リクエストの条件に一致するチャンネルまたはユーザーに関連付けられたアクションを取得します。たとえば、特定のチャンネル、ユーザーの登録チャンネル、ユーザーのカスタム YouTube ホームページに関連付けられたアクションを取得できます。

特定の期間のアクティビティ

このリクエストは、認証されたユーザーが 2013 年 4 月に行ったすべてのアクションを取得します。

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

ホームページのアクティビティ

このリクエストは、認証されたユーザーの YouTube ホームページに表示されるカスタムアクティビティフィードを取得します。

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

YouTube 動画やチャンネルの視聴の統計情報、人気指標、ユーザー属性情報を取得するには、YouTube Analytics API を使用します。サンプル API リクエストのページでは、YouTube アナリティクスから一般的なレポートを取得する方法を示しています。

検索

search.list メソッドを使用すると、指定した条件に一致する YouTube 動画、チャンネル、再生リストを検索できます。動画のプロパティ、キーワード、トピック（またはそれらの組み合わせ）に基づいて検索し、作成日、再生回数、評価などの要素に基づいて検索結果を並べ替えることができます。

他の YouTube Data API リクエストと同様に、search.list メソッドは YouTube リソースの JSON 表現を返します。ただし、他の YouTube リソースとは異なり、検索結果は一意の ID を持つ永続的なオブジェクトではありません。

多くのリクエストは一般公開されているコンテンツを検索するため、認証は必要ありません。以下のサンプルのうち、最初のサンプルだけが「my」であることを明確に要求しているため、認証が必要です。できます。未認証のリクエストを送信する場合は、アプリケーションに固有の API キーを指定する key 引数を含める必要があります。

再生回数の多い動画

このリクエストは、認証されたユーザーの動画をすべて取得し、視聴回数の降順で一覧表示します。

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

埋め込み可能な高解像度の動画

このリクエストは、特定のプロパティを持つ動画、つまり他のサイトに埋め込める高解像度の動画を検索します。結果は評価の降順で表示されます。

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

特定のテーマに関する動画

このリクエストは、YouTube Data API に関する字幕を含む動画のキーワード検索を実行します。

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

トピックベースの検索

特定のトピックに関する動画を検索するより高度な方法は、キーワードではなく Freebase トピックを使用することです。YouTube チャンネルと動画のリソースには、そのリソースに関連付けられている Freebase トピック ID のリストを含む topicDetails オブジェクトが含まれます。Freebase トピックは、現実世界のコンセプトや事物のあらゆる側面を表すため、トピック検索はキーワード検索よりもインテリジェントです。

Freebase トピックを使用して検索するには、まず Freebase API を使用してトピック ID を取得する必要があります。このリクエストは、トピック ID が /m/05z1_ の Python 用の Freebase トピックに関連付けられている動画を返します。

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

再生リストまたはチャンネルの検索

検索できるのは動画だけではありません。再生リストやチャンネルを検索することもできます。このリクエストは、キーワード「サッカー」に一致する再生リストを取得します。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

サッカーのチャンネルを探す場合は、type パラメータを変更します。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

すべてのサッカー関連コンテンツ（チャンネル、再生リスト、動画）が見たいときは、ユニバーサル検索を利用できます。type パラメータを省略すると、リクエストはすべてのタイプのコンテンツを取得します。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

リソースの作成と更新

これまでに見てきたリクエストはすべて、HTTP GET メソッドを使用して YouTube データを取得します。YouTube Data API には、HTTP POST を使用して動画、再生リスト、チャンネルなどの YouTube リソースを作成または更新するメソッドもあります。次のリクエストの例を以下に示します。

POST メソッドには、作成または更新されるリソースの JSON 表現である Request body が含まれます。Google APIs Explorer でインタラクティブツールを使用して JSON 表現を作成できます。

サブスクリプションを作成する

このリクエストにより、認証されたユーザーが Google Developers チャンネルに登録されます。つまり、サブスクリプションリソースを作成します。

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

再生リストを作成する

このリクエストにより、新しい公開再生リストが作成されます。

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

動画を再生リストに追加する

再生リストが作成できたので、再生リストに動画を追加しましょう。このリクエストにより、再生リスト（'position': 0）の先頭に動画が追加されます。

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }