REST API를 사용하여 추천 통합

Google TV 동영상 탐색 REST API를 사용하면 파트너가 백엔드 서버에서 Google TV 및 Android TV 기기로 개인 맞춤이 아닌 추천 후보를 전송할 수 있습니다. 백엔드에서 후보를 전송하면 사용자가 파트너의 앱을 열지 않아도 이러한 기기에서 파트너의 카탈로그와 실시간 프로그래밍 추천이 최신 상태로 유지됩니다.

파트너는 추천 피드에 후보를 전송합니다. Google은 파트너를 위해 각 피드를 만들고 피드가 표시되는 국가 또는 지역과 TV 기기 언어를 구성합니다. 피드에는 영화, TV 프로그램, 라이브 TV 프로그램이 포함될 수 있습니다.

사용자 기기에서 맞춤 추천을 게시하려면 Engage SDK를 사용하여 기기 내 추천 통합을 참고하세요.

기본 요건

REST API와 통합하기 전에 다음 사항을 확인하세요.

  • API 요청을 수행할 Google Cloud 프로젝트
  • 조직과 연결된 Google Workspace 계정
  • 온보딩 중에 Google TV 파트너 담당자가 제공한 파트너 ID 및 추천 피드 ID입니다. 이러한 ID가 사용되는 방식은 추천 피드를 참조하세요.

이용하기

Google TV 동영상 탐색 REST API에 대한 액세스는 등록된 Google TV 미디어 파트너로 제한됩니다. 각 호출자는 서버에서 정확히 하나의 파트너 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)를 국가 또는 지역 및 후보를 전송할 TV 기기 언어와 함께 Google TV 파트너 담당자에게 제공합니다. Google TV 파트너 담당자가 Google Workspace 조직, 프로젝트, 서비스 계정을 파트너 ID에 매핑한 후 알려주고 파트너를 위해 생성된 추천 피드 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 프로젝트별 분당 요청 수 5
Google Cloud 프로젝트당 일일 요청 수 100
요청당 항목 RecommendationCandidate개 1~25

스테이징 피드에 대한 요청은 해당 제품 피드에 대한 요청과 동일한 할당량에 반영됩니다.

추천 피드

API는 추천 후보를 추천 피드로 구성합니다. 피드는 다음 형식의 리소스 이름으로 식별됩니다.

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

파트너

{partner}는 온보딩 중에 Google에서 할당하는 파트너 ID입니다. 인증에 사용하는 서비스 계정은 정확히 하나의 파트너 ID에 매핑됩니다. 다른 파트너의 이름을 지정하는 요청은 403 PERMISSION_DENIED 오류와 함께 실패합니다.

피드 ID

{recommendationsFeed}는 온보딩 중에 Google에서 생성하는 피드 ID입니다. API를 사용하여 피드를 만들 수 없습니다.

각 피드는 Google에서 피드를 만들 때 구성하는 잠재고객을 타겟팅합니다.

  • 국가 또는 지역: 피드의 후보가 표시되는 위치입니다.
  • TV 기기 언어: 타겟팅된 사용자가 TV 기기에 설정한 언어입니다. 전송하는 텍스트의 언어가 아닙니다. 두 개 이상의 언어로 텍스트를 제공하려면 LocalizedString를 참고하세요.

Google은 피드의 후보가 Google TV 및 Android TV 기기에 표시되는 위치를 결정합니다. 모든 피드에 동일한 방식으로 후보를 전송합니다.

스테이징 피드

각 피드에는 {recommendationsFeed}-staging라는 일치하는 스테이징 피드가 있습니다. 스테이징 피드는 허용 목록에 있는 테스트 계정에만 제공됩니다. 프로덕션 피드에 후보를 전송하기 전에 통합을 검증하는 데 사용합니다.

스테이징 피드는 제품 피드와 동일한 엔드포인트, 사용자 인증 정보, 요청 검증, 할당량을 사용합니다. 대상만 다릅니다.

대체

피드는 대체 단위입니다. 각 replaceCandidates 호출은 해당 피드에 이전에 저장된 모든 후보를 대체하고 다른 모든 피드는 그대로 둡니다.

추천 후보 교체

partners.recommendationsFeeds.replaceCandidates 메서드를 사용하여 한 피드의 전체 추천 후보 목록을 전송합니다.

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의 각 항목은 하나의 후보 유형 페이로드, 선택적 추천 이유, 선택적 표시 가용성 기간을 포함하는 RecommendationCandidate 객체입니다.

RecommendationCandidate

RecommendationCandidate 객체에는 미디어 유형 페이로드 필드 하나, 선택적 추천 이유, 선택적 사용 가능 간격이 포함됩니다.

통합 필드 candidate_type

candidate_type은 필수 항목입니다. 다음 필드 중 하나만 설정하세요. 필드는 상호 배타적이며, 설정하지 않거나 둘 이상을 설정하는 후보는 거부됩니다. JSON에 candidate_type 키가 없습니다. 선택한 필드를 RecommendationCandidate 객체에 직접 설정합니다.

필드 유형 설명
movie_candidate MovieCandidate 주문형 영화(MovieCandidate 참고)
tv_show_candidate TvShowCandidate 프로그램 수준의 TV 프로그램(TvShowCandidate 참고)
live_tv_program_candidate LiveTvProgramCandidate 예약된 라이브 TV 방송 또는 스트리밍 이벤트(LiveTvProgramCandidate 참고)

컨텍스트 및 사용 가능 여부

두 필드 모두 선택사항입니다.

필드 유형 필수 설명
recommendation_contexts array of RecommendationContext 아니요 후보가 추천되는 이유 및 각 이유가 적용되는 기간(RecommendationContext 참조)
availability_intervals array of Interval 아니요 후보가 표시될 수 있는 기간입니다(Interval 참고). 각 기간은 start_time(포함)에서 시작하여 end_time(제외)에서 끝납니다. 설정하지 않으면 후보는 저장되어 있는 동안 사용할 수 있습니다. 기간이 모두 과거인 후보는 표시되지 않습니다.

MovieCandidate

MovieCandidate 객체는 주문형 영화를 나타냅니다.

필드 유형 필수 설명
title LocalizedString 예 영화 제목입니다(LocalizedString 참고). 각 값은 1~100개의 유니코드 코드 포인트이며 전송된 대로 표시됩니다.
description LocalizedString 예 영화에 대한 간단한 설명입니다(LocalizedString 참고). 각 값은 1~400개의 유니코드 코드 포인트입니다.
localized_media_images array of LocalizedMediaImage 예 16:9 아트워크 이미지, 언어당 항목 1개(LocalizedMediaImage 참고). 이미지가 하나 이상 포함되어야 합니다. 사용 가능한 가장 큰 소스를 제공합니다. 1920x1080픽셀이 권장됩니다.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri 예 플랫폼 및 언어별 딥 링크(LocalizedProviderPlaybackUri 참고). 하나 이상의 항목에 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 객체는 프로그램 수준의 TV 프로그램을 나타냅니다. Google TV 및 Android TV 기기에는 프로그램 카드가 표시됩니다. 딥 링크를 사용하여 프로그램 페이지에서 재생을 시작할지 아니면 특정 에피소드에서 재생을 시작할지 결정합니다.

필드 유형 필수 설명
title LocalizedString 예 TV 프로그램의 제목입니다(LocalizedString 참고). 각 값은 1~100개의 유니코드 코드 포인트이며 전송된 대로 표시됩니다.
description LocalizedString 예 TV 프로그램에 관한 간단한 설명입니다(LocalizedString 참고). 각 값은 1~400개의 유니코드 코드 포인트입니다.
localized_media_images array of LocalizedMediaImage 예 16:9 아트워크 이미지, 언어당 항목 1개(LocalizedMediaImage 참고). 이미지가 하나 이상 포함되어야 합니다. 사용 가능한 가장 큰 소스를 제공합니다. 1920x1080픽셀이 권장됩니다.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri 예 플랫폼 및 언어별 딥 링크(LocalizedProviderPlaybackUri 참고). 하나 이상의 항목에 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 객체는 예약된 라이브 TV 방송 또는 스트리밍 이벤트를 나타냅니다. 브로드캐스트 기간은 후보의 일부이며 카드가 표시될 수 있는 시점을 제어하는 상위 후보의 availability_intervals와는 별개입니다.

필드 유형 필수 설명
title LocalizedString 예 라이브 TV 프로그램의 제목입니다(LocalizedString 참고). 각 값은 1~100개의 유니코드 코드 포인트이며 전송된 대로 표시됩니다.
description LocalizedString 예 라이브 TV 프로그램에 관한 간단한 설명입니다(LocalizedString 참고). 각 값은 1~400개의 유니코드 코드 포인트입니다.
localized_media_images array of LocalizedMediaImage 예 16:9 아트워크 이미지, 언어당 항목 1개(LocalizedMediaImage 참고). 이미지가 하나 이상 포함되어야 합니다. 사용 가능한 가장 큰 소스를 제공합니다. 1920x1080픽셀이 권장됩니다.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri 예 플랫폼 및 언어별 딥 링크(LocalizedProviderPlaybackUri 참고). 하나 이상의 항목에 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 객체는 하나 이상의 언어로 동일한 텍스트를 전달합니다. 각 값은 언어로 태그가 지정되므로 Google TV 및 Android TV 기기에서 사용자의 TV 기기 언어와 일치하는 텍스트를 표시할 수 있습니다.

필드 유형 필수 설명
values array of LocalizedText 예 제공하는 각 언어의 텍스트입니다(LocalizedText 참고). 하나 이상의 값이 포함되어야 합니다.

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 참고). 사용 가능한 가장 큰 소스를 제공하세요. 1920x1080픽셀이 권장됩니다.

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 객체는 후보를 외부 카탈로그의 식별자에 매핑합니다. 항목당 다음 필드 중 하나만 설정하고 후보자의 external_entity_ids 목록에 식별자 유형당 최대 하나의 항목을 포함합니다.

필드 유형 필수 설명
tms_root_id string 1개 Gracenote TMS 루트 ID입니다. 영화, TV 프로그램 또는 에피소드와 같은 콘텐츠를 식별합니다.
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 객체에는 하나의 이유가 포함됩니다. 다음 필드 중 하나를 정확하게 설정합니다.

필드 유형 필수 설명
top_on_partner object 1개 후보는 서비스에서 순위가 매겨진 상위 항목입니다. 단일 양의 정수 필드 rank를 포함합니다(예: '파트너의 상위 1위'의 경우 {"rank": 1}).
popular_on_partner object 1개 후보가 서비스에서 인기가 있습니다. 빈 객체({})를 전달합니다.
new_on_partner object 1개 후보가 서비스에 새로 추가되었습니다. 빈 객체({})를 전달합니다.
generic object 1개 맞춤 이유 단일 LocalizedString 필드 generic_reason를 포함합니다(LocalizedString 참고). 각 값은 1~100개의 유니코드 코드 포인트입니다.

ContentRating

ContentRating 객체는 등급 기관에서 할당한 공식 콘텐츠 등급을 나타냅니다.

필드 유형 필수 설명
rating_system string 예 등급 기관 또는 시스템(예: "MPAA", "BBFC", "CBFC")
rating_value string 예 rating_system에서 정의한 등급입니다(예: "PG-13" 또는 "U/A 13+").

Timestamp

Timestamp는 JSON에서 UTC의 RFC 3339 문자열로 인코딩되며 Z 서픽스(예: "2026-10-01T18:00:00Z")가 있습니다. 초 단위의 소수점은 허용됩니다(예: "2026-10-01T18:00:00.500Z").

Duration

Duration는 JSON에서 초 수와 접미사 s가 포함된 문자열로 인코딩됩니다(예: 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 후보를 세 가지 후보(영화, TV 프로그램, 라이브 TV 프로그램)로 바꿉니다. 영화에는 두 가지 언어로 된 텍스트가 포함되어 있습니다.

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 경로에 이름이 지정된 피드에 대해 이전에 저장된 후보 목록을 완전히 대체합니다. 항상 해당 피드의 전체 활성 후보 집합을 전송하세요.
  • 다른 피드는 변경되지 않습니다. 후보를 전송하지 않는 피드는 전송할 때까지 변경되지 않습니다. 예를 들어 한 피드의 후보를 대체해도 다른 피드의 저장된 후보는 수정되지 않으며 {recommendationsFeed}-staging의 후보를 대체해도 {recommendationsFeed}는 수정되지 않습니다.
  • 피드당 한 번의 호출. 여러 피드를 업데이트하려면 피드당 한 번씩 호출합니다. 호출은 독립적입니다. 하나가 실패하면 다른 피드는 새 후보를 유지하고 실패한 호출만 다시 시도합니다.
  • 활성 피드를 최소 30일마다 다시 전송합니다. 피드의 카탈로그가 변경되지 않았더라도 후보가 활성 상태로 유지되고 만료되지 않도록 30일마다 한 번 이상(또는 무작위 지터가 있는 정기적인 일일 또는 주간 일정으로) 각 활성 피드를 다시 전송하세요. availability_intervals end_time를 먼 미래로 설정해도 주기적인 재전송을 대체하지 않습니다.
  • 원자적 실행. API는 요청을 원자적으로 적용합니다. 후보가 검증에 실패하면 API는 전체 요청을 거부하고 피드는 이전 후보를 유지합니다.