PlaylistItems

playlistItem リソースは、再生リストに含まれている動画などの別のリソースを識別します。また playlistItem リソースには、特に、含まれているリソースが再生リストでどのように使用されるかに関連する、リソースについての詳細が含まれています。

YouTube は再生リストを使って、次に示すようなチャンネルごとの動画の特別なコレクションを識別します。

  • アップロード動画
  • お気に入りの動画
  • 高く評価された動画
  • 再生履歴
  • 後で見る
具体的には、これらのリストは、個人、グループ、または会社の動画、再生リスト、および他の YouTube 情報のコレクションで、チャンネルに関連付けられています。

特定のチャンネルに対するこのような各リストの再生リスト ID は channel resource から取得できます。ID の取得後は、 playlistItems.list メソッドを使って対応するリストを取得できます。また、playlistItems.insert メソッドや playlistItems.delete メソッドを呼び出すことで、これらのリストにアイテムを追加したり、削除したりできます。たとえば、ユーザーがお気に入りに動画を追加した場合は、そのユーザーのチャンネルのお気に入り動画の再生リストにその動画を挿入します。

メソッド

この API では、playlistItems リソースについて以下のメソッドがサポートされています。

list
API リクエストのパラメータに一致する、再生リストのアイテムのコレクションを返します。指定した再生リストのアイテムをすべて取得したり、一意の ID を指定して再生リストのアイテムを 1 つまたは複数取得したりできます。 今すぐ試す
insert
再生リストにリソースを追加します。 今すぐ試す
update
再生リストのアイテムを変更します。たとえば、再生リスト内のアイテムの位置を更新できます。 今すぐ試す
delete
再生リストのアイテムを削除します。 今すぐ試す

リソース表現

下記の JSON の構造体は、playlistItems リソースの形式を示したものです。

{
  "kind": "youtube#playlistItem",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "playlistId": string,
    "position": unsigned integer,
    "resourceId": {
      "kind": string,
      "videoId": string,
    }
  },
  "contentDetails": {
    "videoId": string,
    "startAt": string,
    "endAt": string,
    "note": string
  },
  "status": {
    "privacyStatus": string
  }
}

プロパティ

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

プロパティ
kind string
API リソースのタイプ。値は youtube#playlistItem です。
etag etag
このリソースの Etag。
id string
再生リストのアイテムを一意に識別するために YouTube によって使用される ID。
snippet object
snippet オブジェクトには、再生リストのアイテムに関する基本情報(タイトル、再生リスト内の位置など)が格納されます。
snippet.publishedAt datetime
アイテムが再生リストに追加された日時。値は ISO 8601YYYY-MM-DDThh:mm:ss.sZ)形式で指定します。
snippet.channelId string
アイテムを再生リストに追加したユーザーを一意に識別するために YouTube によって使用される ID。
snippet.title string
アイテムのタイトル。
snippet.description string
アイテムの説明。
snippet.thumbnails object
再生リストのアイテムに関連付けられているサムネイル画像のマップ。マップ内の各オブジェクトでは、キーはサムネイル画像の名前で、値はサムネイルに関するその他の情報を含むオブジェクトになります。
snippet.thumbnails.(key) object
有効なキー値は次のとおりです:
  • default – デフォルトのサムネイル画像。動画(または、再生リストのアイテムや検索結果など、動画を参照するリソース)のデフォルト サムネイルは幅 120px、高さ 90px です。チャンネルのデフォルト サムネイルは幅 88px、高さ 88px です。
  • medium – やや解像度の高いバージョンのサムネイル画像。動画(または動画を参照するリソース)の場合、この画像は幅 320px、高さ 180px です。チャンネルの場合、この画像は幅 240px、高さ 240px です。
  • high – 高解像度バージョンのサムネイル画像。動画(または動画を参照するリソース)の場合、この画像は幅 480px、高さ 360px です。チャンネルの場合、この画像は幅 800px、高さ 800px です。
snippet.thumbnails.(key).url string
画像の URL。
snippet.thumbnails.(key).width unsigned integer
画像の幅。
snippet.thumbnails.(key).height unsigned integer
画像の高さ。
snippet.channelTitle string
再生リストのアイテムが属するチャンネルのチャンネル タイトル。
snippet.playlistId string
対象のアイテムが含まれる再生リストを一意に識別するために YouTube により使用される ID。
snippet.position unsigned integer
アイテムが再生リストに表示される順序。ゼロベースのインデックス値で、最初のアイテムの位置は 0、2 番目のアイテムの位置は 1 というように続きます。
snippet.resourceId object
id オブジェクトには、再生リストにアイテムとして含まれるリソースを一意に識別するために使用できる情報がされます。
snippet.resourceId.kind string
参照されるリソースの種類。
snippet.resourceId.videoId string
このプロパティは snippet.resourceId.kind プロパティの値が youtube#video の場合に使用され、再生リスト内の動画を一意に識別するために YouTubeによって使用される ID が値になります。
contentDetails object
アイテムが YouTube 動画の場合、contentDetails オブジェクトがリソースに含まれます。このオブジェクトには、動画に関するその他の情報が格納されます。
contentDetails.videoId string
動画を一意に識別するために YouTube によって使用される ID。video リソースを取得するには、API リクエストでこの値を id クエリ パラメータに設定します。
contentDetails.startAt string
動画の再生を開始する位置。動画の冒頭からの経過時間(秒単位)で表します(再生リストを使って動画が再生されている場合は、再生リストの所有者が開始位置と停止位置を指定できます)。デフォルト値は 0 です。
contentDetails.endAt string
動画の再生を停止する位置。動画の冒頭からの経過時間(秒単位)で表します(再生リストを使って動画が再生されている場合は、再生リストの所有者が開始位置と停止位置を指定できます)。デフォルトでは、video.endTime が動画の終了位置となります。
contentDetails.note string
このアイテムについてユーザーが作成した注記。
status object
status オブジェクトには、再生リストのアイテムのプライバシー ステータスに関する情報が格納されます。
status.privacyStatus string
再生リストのアイテムのプライバシー ステータス。再生リストのアイテムが表す動画をアップロードしたチャンネルについて、videos.insert メソッドまたは videos.update メソッドを使用してこの値を設定できます。