REST API を使用してレコメンデーションを統合する

Google TV Video Discovery REST API を使用すると、パートナーはバックエンド サーバーから Google TV デバイスと Android TV デバイスに、パーソナライズされていないおすすめ候補を送信できます。バックエンドから候補を送信することで、ユーザーがパートナーのアプリを開かなくても、パートナーのカタログとライブ番組のおすすめをこれらのデバイスで最新の状態に保つことができます。

パートナーは候補をレコメンデーション フィードに送信します。Google は、パートナーごとに各フィードを作成し、フィードが表示される国または地域とテレビデバイスの言語を構成します。フィードには、映画、テレビ番組、ライブテレビ番組を含めることができます。

ユーザーのデバイスからパーソナライズされたおすすめ表示を公開する場合は、Engage SDK を使用してデバイス上のレコメンデーションを統合するをご覧ください。

前提条件

REST API と統合する前に、次のものが揃っていることを確認してください。

  • API リクエストを行う Google Cloud プロジェクト。
  • 組織に関連付けられている Google Workspace アカウント。
  • パートナー ID とおすすめフィード ID。オンボーディング中に Google TV パートナー担当者から提供されます。これらの ID の使用方法については、レコメンデーション フィードをご覧ください。

アクセス権を取得

Google TV Video Discovery REST API へのアクセスは、登録済みの Google TV メディア パートナーに限定されています。各呼び出し元は、サーバー上で 1 つのパートナー ID にマッピングされた Google Cloud サービス アカウントを使用して認証されます。

API アクセスをリクエストして構成する手順は次のとおりです。

  1. Google Workspace アカウントを作成します。Google Workspace サポートページの手順に沿って、組織のアカウントを設定します。
  2. Google Workspace のお客様 ID を確認します。お客様 ID を確認するの手順に沿って、お客様 ID(C0123abcd など)を確認します。
  3. Google Cloud プロジェクトとサービス アカウントを作成する。Google Workspace 組織の Google Cloud コンソールで、バックエンド サーバー用の Google Cloud プロジェクトとサービス アカウントを作成します。
  4. パートナー オンボーディングをリクエストします。Google Workspace のお客様 ID、Google Cloud プロジェクト ID、サービス アカウントのメールアドレス(または一意の数値 ID)を、候補を送信する国または地域、テレビデバイスの言語とともに、Google TV パートナー担当者に提供します。Google Workspace の組織、プロジェクト、サービス アカウントをパートナー ID にマッピングすると、Google TV パートナー担当者から通知が届き、パートナー用に作成されたおすすめフィード ID が提供されます。
  5. API を有効にして認証情報を生成します。担当者がアクセス権の付与を確認したら、Google Cloud プロジェクトで Google TV Video Discovery API(tvvideodiscovery.googleapis.com)を有効にし、サービス アカウントの OAuth 2.0 認証情報を生成します。
  6. リクエストを認証する。次の OAuth スコープを使用して OAuth 2.0 アクセス トークンをリクエストし、呼び出しごとに Authorization: Bearer HTTP ヘッダーでトークンを渡します。

    https://www.googleapis.com/auth/tvvideodiscovery
    

レート上限

replaceCandidates へのリクエストには、プロジェクトごとのレート制限とリクエストごとのペイロード上限が適用されます。

上限 値
Google Cloud プロジェクトごとの 1 分あたりのリクエスト数 5
Google Cloud プロジェクトごとの 1 日あたりのリクエスト数 100
1 リクエストあたり RecommendationCandidate 個のアイテム 1 ~ 25

ステージング フィードへのリクエストは、対応する本番環境の商品フィードへのリクエストと同じ割り当てにカウントされます。

レコメンデーション フィード

API は、おすすめ候補をおすすめフィードに整理します。フィードは、次の形式のリソース名で識別されます。

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

パートナー

{partner} は、オンボーディング中に Google が割り当てるパートナー ID です。認証に使用するサービス アカウントは、1 つのパートナー ID にマッピングされます。他のパートナーを指定するリクエストは 403 PERMISSION_DENIED で失敗します。

フィード ID

{recommendationsFeed} は、オンボーディング中に Google が作成するフィード ID です。API を使用してフィードを作成することはできません。

各フィードは、フィードの作成時に Google が構成するオーディエンスをターゲットにします。

  • 国または地域: フィードの候補が表示される場所。
  • テレビデバイスの言語: ターゲット ユーザーがテレビデバイスに設定している言語。これは、送信するテキストの言語ではありません。複数の言語でテキストを指定するには、LocalizedString をご覧ください。

フィードの候補が Google TV デバイスと Android TV デバイスのどこに表示されるかは、Google が決定します。候補は、同じ方法ですべてのフィードに送信します。

ステージング フィード

各フィードには、{recommendationsFeed}-staging という名前の一致するステージング フィードがあります。ステージング フィードは、許可リストに登録されているテスト アカウントにのみ配信されます。これを使用して、候補を本番環境の商品フィードに送信する前に統合を検証します。

ステージング フィードでは、本番環境フィードと同じエンドポイント、認証情報、リクエスト検証、割り当てが使用されます。異なるのは対象ユーザーのみです。

交換

フィードは置換の単位です。replaceCandidates を呼び出すたびに、そのフィードに以前保存された候補がすべて置き換えられ、他のフィードはそのまま残ります。

推奨候補を置き換える

partners.recommendationsFeeds.replaceCandidates メソッドを使用して、1 つのフィードのレコメンデーション候補の完全なリストを送信します。

HTTP リクエスト

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

URL パスには、候補が置き換えられるフィードのリソース名が含まれます。リクエスト本文には、URL パスの一部ではないすべてのフィールドが含まれます。

パスパラメータ

パラメータ 説明
name 必須。フィードのリソース名(partners/{partner}/recommendationsFeeds/{recommendationsFeed} 形式)。{partner} は、サービス アカウントがマッピングされているパートナー ID にする必要があります。{recommendationsFeed} は、Google がそのパートナー用に作成したフィード ID、または -staging サフィックスが付いたフィード ID である必要があります。

ReplaceCandidatesRequest

JSON リクエストの本文の構造は次のとおりです。

フィールド 型 必須 / 省略可 説明
recommendation_candidates array of RecommendationCandidate ○ 1 ~ 25 個の RecommendationCandidate アイテムのリスト。これらの候補は、フィードの現在の候補に置き換わります。

候補スキーマ

recommendation_candidates の各項目は、1 つの候補タイプのペイロード、オプションの推奨理由、オプションの配信期間を含む RecommendationCandidate オブジェクトです。

RecommendationCandidate

RecommendationCandidate オブジェクトには、1 つのメディアタイプ ペイロード フィールド、オプションのレコメンデーションの理由、オプションの提供可能期間が含まれます。

共用体フィールド candidate_type

candidate_type は必須です。次のフィールドのいずれかを設定してください。フィールドは相互に排他的であり、設定が 0 個または 2 個以上の候補は拒否されます。JSON に candidate_type キーはありません。選択したフィールドを RecommendationCandidate オブジェクトに直接設定します。

フィールド タイプ 説明
movie_candidate MovieCandidate オンデマンド映画(MovieCandidate を参照)。
tv_show_candidate TvShowCandidate 番組レベルのテレビ番組(TvShowCandidate を参照)。
live_tv_program_candidate LiveTvProgramCandidate スケジュール設定されたライブテレビ放送またはストリーミング イベント(LiveTvProgramCandidate を参照)。

コンテキストと可用性

どちらのフィールドも省略可能です。

フィールド 型 必須 / 省略可 説明
recommendation_contexts array of RecommendationContext いいえ 候補者が推奨される理由と、各理由が適用される期間(RecommendationContext を参照)。
availability_intervals array of Interval いいえ 候補が表示される時間枠(Interval を参照)。各時間枠は start_time(含む)で始まり、end_time(含まない)で終わります。設定されていない場合、候補は保存されている限り対象となります。すべてのウィンドウが過去にある候補は表示されません。

MovieCandidate

MovieCandidate オブジェクトは、オンデマンド映画を表します。

フィールド 型 必須 / 省略可 説明
title LocalizedString ○ 映画のタイトル(LocalizedString を参照)。各値は 1 ~ 100 の Unicode コードポイントで、送信されたとおりに表示されます。
description LocalizedString ○ 映画の短い説明(LocalizedString を参照)。各値は 1 ~ 400 の Unicode コードポイントです。
localized_media_images array of LocalizedMediaImage ○ 16:9 のアートワーク画像。言語ごとに 1 つのエントリ(LocalizedMediaImage を参照)。少なくとも 1 つの画像を含める必要があります。利用可能な最大のソースを提供します。1,920×1,080 ピクセルが推奨されます。
localized_provider_playback_uris array of LocalizedProviderPlaybackUri ○ プラットフォームごと、言語ごとのディープリンク(LocalizedProviderPlaybackUri を参照)。少なくとも 1 つのエントリに PLATFORM_ANDROID_TV を指定する必要があります。
release_date Date ○ 映画のリリース日(Date を参照)。
external_entity_ids array of ExternalEntityId いいえ エンティティ マッチング用の外部カタログ識別子(ExternalEntityId を参照)。識別子タイプごとに最大 1 つのエントリ。
duration string(Duration) いいえ 映画の長さ(Duration を参照)。例: 2 時間の場合は "7200s"。
content_ratings array of ContentRating いいえ 公式のコンテンツ レーティング(ContentRating を参照)。

TvShowCandidate

TvShowCandidate オブジェクトは、番組レベルのテレビ番組を表します。Google TV デバイスと Android TV デバイスには、番組のカードが表示されます。ディープリンクを使用して、番組ページで再生を開始するか、特定のエピソードで再生を開始するかを決定します。

フィールド 型 必須 / 省略可 説明
title LocalizedString ○ テレビ番組のタイトル(LocalizedString を参照)。各値は 1 ~ 100 の Unicode コードポイントで、送信されたとおりに表示されます。
description LocalizedString ○ テレビ番組の簡単な説明(LocalizedString を参照)。各値は 1 ~ 400 の Unicode コードポイントです。
localized_media_images array of LocalizedMediaImage ○ 16:9 のアートワーク画像。言語ごとに 1 つのエントリ(LocalizedMediaImage を参照)。少なくとも 1 つの画像を含める必要があります。利用可能な最大のソースを提供します。1,920×1,080 ピクセルが推奨されます。
localized_provider_playback_uris array of LocalizedProviderPlaybackUri ○ プラットフォームごと、言語ごとのディープリンク(LocalizedProviderPlaybackUri を参照)。少なくとも 1 つのエントリに PLATFORM_ANDROID_TV を指定する必要があります。uri は、番組ページまたはエピソードを指すことができます。
first_episode_air_date Date ○ 初回エピソードの放送日(Date を参照)。
external_entity_ids array of ExternalEntityId いいえ エンティティ マッチング用の外部カタログ識別子(ExternalEntityId を参照)。識別子タイプごとに最大 1 つのエントリ。
season_count integer(int32) いいえ サービスで利用可能なシーズン数。
content_ratings array of ContentRating いいえ 公式のコンテンツ レーティング(ContentRating を参照)。

LiveTvProgramCandidate

LiveTvProgramCandidate オブジェクトは、スケジュール設定されたライブテレビ放送またはストリーミング イベントを表します。ブロードキャスト ウィンドウは候補の一部であり、親候補の availability_intervals とは別 です。は、 カードが表示されるタイミングを制御します。

フィールド 型 必須 / 省略可 説明
title LocalizedString ○ ライブテレビ番組のタイトル(LocalizedString を参照)。各値は 1 ~ 100 の Unicode コードポイントで、送信されたとおりに表示されます。
description LocalizedString ○ ライブテレビ番組の簡単な説明(LocalizedString を参照)。各値は 1 ~ 400 の Unicode コードポイントです。
localized_media_images array of LocalizedMediaImage ○ 16:9 のアートワーク画像。言語ごとに 1 つのエントリ(LocalizedMediaImage を参照)。少なくとも 1 つの画像を含める必要があります。利用可能な最大のソースを提供します。1,920×1,080 ピクセルが推奨されます。
localized_provider_playback_uris array of LocalizedProviderPlaybackUri ○ プラットフォームごと、言語ごとのディープリンク(LocalizedProviderPlaybackUri を参照)。少なくとも 1 つのエントリに PLATFORM_ANDROID_TV を指定する必要があります。
broadcast_interval Interval ○ 番組の放送開始と終了(Interval を参照)。start_time と end_time の両方が必須です。
external_entity_ids array of ExternalEntityId いいえ エンティティ マッチング用の外部カタログ識別子(ExternalEntityId を参照)。識別子タイプごとに最大 1 つのエントリ。
content_ratings array of ContentRating いいえ 公式のコンテンツ レーティング(ContentRating を参照)。

サポート スキーマ

候補ペイロードは、ローカライズされたテキスト、ディープリンク、アートワーク、外部識別子、おすすめの理由、表示間隔、コンテンツのレーティング、既知の日付と時刻のタイプについて、次の共有オブジェクトを参照します。

LocalizedString

LocalizedString オブジェクトは、1 つ以上の言語で同じテキストを保持します。各値には言語のタグが付けられているため、Google TV デバイスと Android TV デバイスは、ユーザーのテレビデバイスの言語に一致するテキストを表示できます。

フィールド 型 必須 / 省略可 説明
values array of LocalizedText ○ 指定する各言語のテキスト(LocalizedText を参照)。少なくとも 1 つの値を含める必要があります。

LocalizedText

LocalizedText オブジェクトは、単一の言語のテキストです。

フィールド 型 必須 / 省略可 説明
text string ○ language_code で指定された言語のテキスト。
language_code string ○ text の BCP-47 言語コード("en-US"、"sr-Latn" など)。

LocalizedMediaImage

LocalizedMediaImage オブジェクトは、画像と画像内のテキストの言語をペアにします。

フィールド 型 必須 / 省略可 説明
language_code string ○ 画像内のテキストの BCP-47 言語コード("en-US"、"sr-Latn" など)。
image MediaImage ○ 16:9 の画像(MediaImage を参照)。利用可能な最大のソースを提供してください。1,920x1,080 ピクセルが推奨されます。

LocalizedProviderPlaybackUri

LocalizedProviderPlaybackUri オブジェクトは、ディープリンクを、そのリンクが開くコンテンツの言語、およびそのリンクを開くアプリとペア設定します。

フィールド 型 必須 / 省略可 説明
playback_uri PlaybackUri ○ ディープリンクと、それが適用されるプラットフォーム(PlaybackUri を参照)。
language_code string ○ ディープリンクで開くコンテンツの BCP-47 言語コード("en-US"、"sr-Latn" など)。
package_name string ○ ディープリンクを開くために使用される Android アプリケーション パッケージ名(例: "com.example.tvapp")。

PlaybackUri

PlaybackUri オブジェクトは、ディープリンクとそのターゲット プラットフォームを定義します。

フィールド 型 必須 / 省略可 説明
uri string ○ アプリで候補の再生を開始するディープリンク URI。
platforms array of string (enum) ○ このディープリンクが適用されるプラットフォーム。使用できる値: PLATFORM_UNSPECIFIED、PLATFORM_ANDROID_TV、PLATFORM_ANDROID、PLATFORM_IOS。Google TV デバイスと Android TV デバイスの場合は PLATFORM_ANDROID_TV を含めます。

MediaImage

MediaImage オブジェクトは、画像の URL、ピクセル寸法、ユーザー補助テキストを指定します。

フィールド 型 必須 / 省略可 説明
url string ○ 一般公開されている画像の HTTPS URL。
width integer ○ 変更されていない(最大)画像の幅(ピクセル単位)。
height integer ○ 変更されていない(最大)画像の高さ(ピクセル単位)。
accessibility_text string ○ 画像を説明するユーザー補助(代替)テキスト。

ExternalEntityId

ExternalEntityId オブジェクトは、候補を外部カタログの識別子にマッピングします。エントリごとに次のいずれかのフィールドを 1 つだけ設定し、候補者の external_entity_ids リストに識別子タイプごとに最大 1 つのエントリを含めます。

フィールド 型 必須 / 省略可 説明
tms_root_id string 次のいずれか 1 つ: Gracenote TMS ルート ID。タイトル(映画、番組、エピソード)を識別します。
tms_id string 次のいずれか 1 つ: Gracenote TMS バリアント ID。エディションまたはブロードキャスト リスティングを識別します。
data_feed_element_id string 次のいずれか 1 つ: メディア アクション データフィードのエンティティ ID。この値は、リソース名の {recommendationsFeed} セグメントとは無関係です。

RecommendationContext

RecommendationContext オブジェクトは、候補が推奨される理由と、その説明が適用される期間を説明します。

フィールド 型 必須 / 省略可 説明
recommendation_reason RecommendationReason いいえ 候補が推奨される理由(RecommendationReason を参照)。
validity_interval Interval いいえ このコンテキストが適用される時間枠(Interval を参照)。たとえば、候補が新規であるのは、限られた日数のみです。設定しない場合、コンテキストは候補が保存されている限り適用されます。

RecommendationReason

RecommendationReason オブジェクトには 1 つの理由が含まれます。次のいずれかのフィールドを設定します。

フィールド 型 必須 / 省略可 説明
top_on_partner object 次のいずれか 1 つ: 候補は、サービスで上位にランク付けされたアイテムです。単一の正の整数フィールド rank(「パートナーのトップ 1」の場合は {"rank": 1} など)が含まれます。
popular_on_partner object 次のいずれか 1 つ: 候補がサービスで人気がある。空のオブジェクト({})を渡します。
new_on_partner object 次のいずれか 1 つ: 候補者がサービスを初めて利用する場合。空のオブジェクト({})を渡します。
generic object 次のいずれか 1 つ: カスタム理由。1 つの LocalizedString フィールド generic_reason が含まれます(LocalizedString を参照)。各値は 1 ~ 100 の Unicode コードポイントです。

ContentRating

ContentRating オブジェクトは、レーティング機関によって割り当てられた公式のコンテンツ レーティングを表します。

フィールド 型 必須 / 省略可 説明
rating_system string ○ レーティング機関またはシステム(例: "MPAA"、"BBFC"、"CBFC")。
rating_value string ○ rating_system で定義されている評価(例: "PG-13"、"U/A 13+")。

Timestamp

Timestamp は、JSON で RFC 3339 文字列としてエンコードされます。この文字列は UTC で、Z 接尾辞が付きます(例: "2026-10-01T18:00:00Z")。秒数は小数点以下まで指定できます(例: "2026-10-01T18:00:00.500Z")。

Duration

Duration は、秒数とそれに続く接尾辞 s を含む文字列として JSON でエンコードされます。たとえば、2 時間の場合は "7200s" です。秒の小数部を使用できます(例: "5400.5s")。

Date

Date は、タイムゾーンのないカレンダーの日付です。JSON では、次のフィールドを持つオブジェクトとしてエンコードされます。

フィールド 型 必須 / 省略可 説明
year integer ○ 日付の年(例: 2025)。
month integer いいえ 月(1~12)。月が不明な場合は、0 に設定するか、省略します。
day integer いいえ 1~31 の範囲で、指定された年と月で有効な日。日付が不明な場合は、0 に設定するか、省略します。month が必須です。

たとえば、{"year": 2025, "month": 1, "day": 17} は 2025 年 1 月 17 日を表し、{"year": 2025, "month": 1} は 2025 年 1 月(日は不明)を表し、{"year": 2025} は 2025 年の日付(月と日は不明)を表します。

Interval

Interval は、start_time(この日時を含む)から end_time(この日時を含まない)までの半開の時間枠です。start_time <= T と T < end_time の場合、時間 T は間隔内です。

フィールド 型 必須 / 省略可 説明
start_time string(Timestamp) ○ ウィンドウの開始日時(この日時を含む)(Timestamp を参照)。例: "2026-10-01T18:00:00Z"。
end_time string(Timestamp) ○ ウィンドウの終了日時(この日時を含まない)(Timestamp を参照)。例: "2026-10-01T21:00:00Z"。start_time より後の日付を入力してください。

リクエスト例

次の例では、パートナー example-partner のフィード in-en-cricket の候補を 3 つの候補(映画、テレビ番組、ライブテレビ番組)に置き換えます。この動画には、2 つの言語のテキストが含まれています。

curl -X POST \
  "https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "recommendation_candidates": [
      {
        "movie_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Action Movie",
                "language_code": "en-US"
              },
              {
                "text": "Película de acción de ejemplo",
                "language_code": "es-419"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example action movie synopsis.",
                "language_code": "en-US"
              },
              {
                "text": "Sinopsis de una película de acción de ejemplo.",
                "language_code": "es-419"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Action Movie"
              }
            },
            {
              "language_code": "es-419",
              "image": {
                "url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Imagen de Película de acción de ejemplo"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=en",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            },
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/movie-1001?lang=es",
                "platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
              },
              "language_code": "es-419",
              "package_name": "com.example.tvapp"
            }
          ],
          "release_date": {
            "year": 2025,
            "month": 11,
            "day": 14
          },
          "external_entity_ids": [
            {
              "tms_root_id": "MV001234560000"
            }
          ],
          "duration": "7200s",
          "content_ratings": [
            {
              "rating_system": "MPAA",
              "rating_value": "PG-13"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "top_on_partner": {
                "rank": 1
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "tv_show_candidate": {
          "title": {
            "values": [
              {
                "text": "Example Drama Series",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "An example drama series synopsis.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/show-2002-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Example Drama Series"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/watch/show-2002",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "first_episode_air_date": {
            "year": 2024,
            "month": 3,
            "day": 8
          },
          "external_entity_ids": [
            {
              "data_feed_element_id": "show-2002"
            }
          ],
          "season_count": 3,
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-14"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "new_on_partner": {}
            },
            "validity_interval": {
              "start_time": "2026-11-01T00:00:00Z",
              "end_time": "2026-11-15T00:00:00Z"
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-01T00:00:00Z",
            "end_time": "2026-12-01T00:00:00Z"
          }
        ]
      },
      {
        "live_tv_program_candidate": {
          "title": {
            "values": [
              {
                "text": "Championship Live Broadcast",
                "language_code": "en-US"
              }
            ]
          },
          "description": {
            "values": [
              {
                "text": "Live coverage of the championship match.",
                "language_code": "en-US"
              }
            ]
          },
          "localized_media_images": [
            {
              "language_code": "en-US",
              "image": {
                "url": "https://www.example.com/images/live-prog-500-16x9.jpg",
                "width": 1920,
                "height": 1080,
                "accessibility_text": "Artwork for Championship Live Broadcast"
              }
            }
          ],
          "localized_provider_playback_uris": [
            {
              "playback_uri": {
                "uri": "https://www.example.com/live/sports-1",
                "platforms": ["PLATFORM_ANDROID_TV"]
              },
              "language_code": "en-US",
              "package_name": "com.example.tvapp"
            }
          ],
          "broadcast_interval": {
            "start_time": "2026-11-15T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          },
          "external_entity_ids": [
            {
              "tms_id": "EP012345670001"
            }
          ],
          "content_ratings": [
            {
              "rating_system": "TV_PG",
              "rating_value": "TV-PG"
            }
          ]
        },
        "recommendation_contexts": [
          {
            "recommendation_reason": {
              "generic": {
                "generic_reason": {
                  "values": [
                    {
                      "text": "Live this weekend",
                      "language_code": "en-US"
                    }
                  ]
                }
              }
            }
          }
        ],
        "availability_intervals": [
          {
            "start_time": "2026-11-14T18:00:00Z",
            "end_time": "2026-11-15T21:00:00Z"
          }
        ]
      }
    ]
  }'

レスポンスと置換の動作

このセクションでは、replaceCandidates から返される HTTP レスポンスと、各呼び出しで保存された候補がどのように更新されるかについて説明します。

ReplaceCandidatesResponse

リクエストが成功すると、API は ReplaceCandidatesResponse 本文を含む HTTP 200 OK を返します。

フィールド タイプ 説明
replaced_candidates_count integer(int32) 置き換えられた候補の数。

上記のリクエストの例に対するレスポンスは次のとおりです。

{
  "replaced_candidates_count": 3
}

置換動作

replaceCandidates が保存された候補を更新する方法を理解することは、統合を設計するうえで不可欠です。

  • フィードごとの完全な置き換え。呼び出しごとに、URL パスで指定されたフィードの以前に保存された候補リストが完全に置き換えられます。そのフィードで有効な候補の完全なセットを常に送信します。
  • 他のフィードは変更されません。候補を送信しないフィードは、送信するまで変更されません。たとえば、1 つのフィードの候補を置き換えても、他のフィードに保存されている候補は変更されません。{recommendationsFeed}-staging の候補を置き換えても、{recommendationsFeed} は変更されません。
  • フィードごとに 1 回の呼び出し。複数のフィードを更新するには、フィードごとに 1 回呼び出しを行います。呼び出しは独立しています。1 つが失敗しても、他のフィードは新しい候補を保持し、失敗した呼び出しのみを再試行します。
  • アクティビティ フィードを少なくとも 30 日ごとに再送信する。フィードのカタログが変更されていない場合でも、候補がアクティブな状態を維持し、期限切れにならないように、アクティブなフィードを少なくとも 30 日に 1 回(またはランダムなジッターを伴う定期的な日次または週次のスケジュールで)再送信してください。availability_intervals の end_time を遠い将来に設定しても、定期的な再送信は置き換えられません。
  • アトミック実行。API はリクエストをアトミックに適用します。いずれかの候補の検証が失敗した場合、API はリクエスト全体を拒否し、フィードは以前の候補を保持します。