Google is committed to advancing racial equity for Black communities. See how.

下方互換性ガイドライン

YouTube Data API のリクエストには、そのリクエストを YouTube で処理する際に使用すべき API のバージョンを指定できます。リクエストに API バージョンを指定しない場合は、そのリクエストの処理に YouTube でサポートされている最も古い API バージョンが使用されます。現在サポートされている最も古いバージョンは 1 です。API のバージョン番号には、次のような特徴があります:

  • YouTube では、特定の API バージョンへのアップデートをリリースしても、新規のバージョン番号は割り当てないことがあります。このようなアップデートには、下方互換性があり、オプションの API 機能、バグの修正などが含まれます。

  • API バージョン番号が大きくなる場合は、そのリリースにそれまでの API バージョンとは互換性のない変更が含まれることを意味します。

このドキュメントでは、特定の API バージョンへのアップデート(上の箇条書きの 1 つ目)について、その下方互換性ガイドラインを定義します。このガイドラインでは、タイプの異なる API 機能を以下のように区別して扱うことにします:

  • このガイドラインでは、API リクエストの処理に使用する API バージョンを変えていない場合でも変更される可能性のある API 機能を特定します。コードを記述する際は、このような変更が中断なしで処理されるようにする必要があります。たとえば、YouTube によって API レスポンスに新しい XML タグが追加された場合、コードではそれらのタグを無視しなければなりません。

  • このガイドラインでは、特定の API バージョンの更新時には変更されないことになっている API 機能についても定義しています。言い換えると、このタイプの機能が変更されるときは必ず新しい API バージョンがリリースされるため、そのような機能変更に合わせてコードを修正する必要はありません。

このドキュメントについて

このドキュメントは以下のセクションで構成されています:

  • API リクエストでは、HTTP リクエスト ヘッダー、API リクエスト パラメータ、XML 要素名(API リクエスト内で使用する名前)、および不正な形式の API リクエストに関わる下方互換性ガイドラインを定義します。

  • API レスポンスでは、XML 要素名(API レスポンスで使用する名前)と、API レスポンス内での XML タグおよび属性の順序に関わる下方互換性ガイドラインを定義します。

  • ベスト プラクティスでは、YouTube API をクライアント アプリケーションに統合する際の推奨事項について簡単に説明します。

API リクエスト

変更されないことになっている機能

  • 既存のリクエスト パラメータ。

  • 列挙値を保持するパラメータの既存のパラメータ値、またはそれらのパラメータ値の意味。

  • API の POST(挿入)リクエストまたは PUT(更新)リクエスト内で使用される XML 要素の名前。

  • API リクエストのタイプごとに必須の HTTP リクエスト ヘッダーのセット。つまり、必須の HTTP リクエスト ヘッダーが新たに追加されたり、省略可能だった既存のリクエスト ヘッダーが必須に変更されたりすることはないということです。

  • リクエスト内のサポートされていないパラメータを無視する動作。ただし、API リクエスト内で strict パラメータ(無効なリクエスト パラメータを含む API リクエストが YouTube によって拒否されるようにするためのパラメータ)が使用されている場合を除きます。

変更される可能性のある機能

  • 省略可能なリクエスト パラメータが追加されることがあります。

  • 列挙値のセットを保持する既存のパラメータに新しい値が追加されることがあります。

  • YouTube は、有効なパラメータに無効なパラメータ値が設定されているリクエストを拒否できます。その結果、解析が不十分だったため受け付けられていた不正な形式のリクエストが、解析ロジックの訂正によって拒否されるようになる場合があります。

  • 省略可能な HTTP リクエスト ヘッダーが追加されることがあります。

  • リソースの挿入時や更新時に保持(格納)される情報が変更されることがあります。ただし、そのような変更によって、対応する API リクエストの構文に影響が及んだり、構文の変更が必要になったりすることはありません。

  • ブラウジング可能なカテゴリのセット、または新しくアップロードする動画を分類できるカテゴリのセットが変更されることがあります。

  • 文書化されていない機能は、予告なく削除または変更されることがあります。

API レスポンス

変更されないことになっている機能

  • 既存の XML タグ名。

  • Media RSS 仕様で定義されいてる要素がフィード エントリ内に複数回出現する場合、それらの要素の順序は Media RSS 仕様に従って決定されます。たとえば、複数の <media:thumbnail> タグが含まれている場合は重要度によって順序付けされます。

  • <category> タグの term 属性の値。この属性の値によって、フィードまたはフィード エントリ内に記述されている項目のタイプを特定できます。<feed> または <entry> タグ内では、エントリによって特定される一意のリソースを <id> タグで指定し、エントリによって記述されるリソースの種類を <category> で指定します。この <category> タグの scheme 属性の値は http://schemas.google.com/g/2005#kind で、term 属性の値によってフィード エントリに記述されているもの(動画、再生リストのリンク、登録チャンネル、コンタクト、または他のエンティティ タイプ)を特定できます。

変更される可能性のある機能

  • API レスポンスに新しい XML タグが追加されることがあります。

  • 既存の XML タグに新しい属性が追加されることがあります。

  • 既存の API タグが別の値で繰り返されることがあります。たとえば、type の値が異なる新しい <media:restriction> タグが追加されたり、schemerole の値が異なる新しい <media:credit> タグが追加されたりする場合があります。

  • API レスポンス内の XML タグおよび属性の順序が変更されることがあります。

  • API レスポンスから省略可能な子タグが削除されることがあります。

  • 文書化されていない機能は、予告なく削除または変更されることがあります。

ベスト プラクティス

  • エントリを特定するときは <id> タグの値を使用します。

  • エントリを取得するときは self リンクを使用します。

  • エントリを編集または更新するときは edit リンクを使用します。

  • YouTube で動画を一意に特定するために使用する値を取得するときは、その動画エントリの <yt:videoid> タグの値を使用します。リンクから動画 ID を解析しないようにしてください。

  • フィード間を移動するときは、<link><content>、および <gd:feedLink> タグ内に指定されている URL を使用します。YouTube で特定のフィードを確実に取得するためには、以下に示す限られたフィード URL を使用して URL を作成する必要があります。これらのフィード URL の他に独自のフィード URL を作成しないようにしてください。独自のフィード URL は、突然機能しなくなる可能性があります。

    • /feeds/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • /feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME(詳しくは リファレンス ガイドをご覧ください)
  • YouTube で動画を一意に特定するために使用する値を取得するときは、その動画エントリの <yt:videoid> タグの値を使用します。リンクから動画 ID を解析しないようにしてください。

  • API レスポンス内の URL から数字や英数字の識別情報を解析しようとしないでください。API レスポンスには、動画 ID(<yt:videoid>)やユーザー名(<name> および <media:credit>).)など、YouTube ウェブサイト上のリソースにリンクしている識別情報専用のタグが含まれています。

  • API リクエストを挿入(POST)または更新(PUT)情報に送信する場合は、そのリクエストに対する XML レスポンスを使用して、リクエスト内のどのタグ値が実際に YouTube によって格納されたかを特定します。API リクエストの下方互換性ガイドラインで説明したとおり、リソースの挿入時や更新時に保持(格納)される情報は YouTube の判断で変更されることがあるため、リクエスト内のタグの一部が無視される可能性があります。

  • ユーザーがアプリケーションを通じてフィード エントリを更新できる場合は、XML フィードの取得時にそのフィード エントリに関係のある認識されないタグおよび属性を格納します。ユーザーがリソースを更新した場合に、更新リクエスト内の認識されないタグおよび属性が格納されるようアプリケーションを設計する必要があります。こうすることで、リソースの更新プロセスにおいて、新しい API 機能に関係のある情報が誤って削除されるのを防ぐことができます。

    次にベスト プラクティスの例を示します:

    1. アプリケーションで、ユーザーが動画の説明を更新できるようにします。
    2. アプリケーションで、API を使用して動画エントリを取得しますが、エントリ内のタグの 1 つが認識されないようにします。
    3. ユーザーが動画の説明を変更するようにします。
    4. アプリケーションから API に完全な動画エントリを送り返すことを必須にします。エントリには、手順 2 で認識されなかったタグを含める必要があります。そうしないと、その値が削除される可能性があります。

  • タグの値を表示する前に、そのタグが存在し、null 以外の値が保持されていることを確認します。

  • 既に説明しましたが、YouTube の判断によって、列挙値のセットを保持する既存のタグまたは属性に新しい値が追加されることがあります。規則では、列挙値のセットを保持する XML 要素の値をコード内で解析し、それぞれの値に適した処理を定義する必要があります。要素に列挙される可能性のある値が 1 つだけであっても、このようにコーディングすることをおすすめします。

    たとえば、<media:credit> タグは動画の所有者を示します。このタグの role 属性の値として文書化されているのは uploader のみで、この動画が YouTube パートナーによってアップロードされたものであることを示します。このベスト プラクティスでは、動画所有者として該当するユーザーを特定する前に、このタグの role 属性が実際に uploader であることを確認する必要があります(こうしておくことで、YouTube が別のタイプのクレジット(たとえば director )を追加した場合でも、コードの修正なしで正しい動画所有者を特定できます)。

    • タグに列挙値のセットが保持されており、アプリケーションでそのタグの値を認識しない場合は、そのタグが出現する <entry> 全体を無視する必要があります。

    • scheme 属性の値が http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat になっている <category> タグの term 属性を認識しない場合は、登録チャンネル フィード エントリを無視します。このようなタグは、そのエントリが表す登録チャンネルのタイプを示します。アプリケーションでその登録チャンネル タイプを認識しない場合は、そのエントリに関する情報を表示すべきではありません。

    • その他の属性に列挙値のセットが保持されており、アプリケーションでその属性を認識しない場合は、その属性が出現するタグを無視する必要があります。

  • いつ yt:error メッセージが生成されてもいいようにコーディングします。API の処理でエラーが発生したときに、エラーを特定してユーザーに情報を伝えるメッセージを表示する必要があります。

  • 動画を分類するための新しいカテゴリは、YouTube の判断によって随時追加されます。また、既存のカテゴリの更新や廃止も随時行われます。現時点でのカテゴリ ファイルを取得するには http://gdata.youtube.com/schemas/2007/categories.cat にアクセスします。

    • アプリケーションで、ユーザーがカテゴリ別に動画をブラウジングしたり動画をアップロードしたりできるようにする場合は、最新のカテゴリ ファイルを毎週取得します。

    • アプリケーションでユーザーがカテゴリ別に動画をブラウジングできるようにする場合は、カテゴリ検索に対する API からのレスポンスとして空のフィードが返されたときにも最新のカテゴリ ファイルを取得します。

    • アプリケーションでユーザーが動画をアップロードできるようにする場合は、動画をアップロードする前にも最新のカテゴリ ファイルを取得し、アップロードする動画に関連付けられているカテゴリがまだ割り当て可能であることを確認します。詳しくは、リファレンス ガイドをご覧ください(なお、割り当てできないカテゴリに動画を割り当てると、<code> タグの値として deprecated が設定された エラー メッセージが返されます)。

  • フィード内のエントリから見た前のページや次のページへのページ間のリンクを特定するときは、API レスポンス内の <link> タグを使用します。詳しくは、リファレンス ガイドの検索結果のページ指定をご覧ください。