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 액세스를 요청하고 구성하려면 다음 단계를 따르세요.
- Google Workspace 계정을 만듭니다. Google Workspace 지원 페이지의 안내에 따라 조직의 계정을 설정합니다.
- Google Workspace 고객 ID를 찾습니다. 고객 ID 찾기의 단계에 따라 고객 ID(예:
C0123abcd)를 찾습니다. - Google Cloud 프로젝트 및 서비스 계정을 만듭니다. Google Workspace 조직의 Google Cloud 콘솔에서 백엔드 서버의 Google Cloud 프로젝트와 서비스 계정을 만듭니다.
- 파트너 온보딩을 요청합니다. Google Workspace 고객 ID, Google Cloud 프로젝트 ID, 서비스 계정 이메일 주소(또는 고유 숫자 ID)를 국가 또는 지역 및 후보를 전송할 TV 기기 언어와 함께 Google TV 파트너 담당자에게 제공합니다. Google TV 파트너 담당자가 Google Workspace 조직, 프로젝트, 서비스 계정을 파트너 ID에 매핑한 후 알려주고 파트너를 위해 생성된 추천 피드 ID를 제공합니다.
- API를 사용 설정하고 사용자 인증 정보를 생성합니다. 담당자가 액세스 권한이 부여되었음을 확인하면 Google Cloud 프로젝트에서 Google TV Video Discovery API(
tvvideodiscovery.googleapis.com)를 사용 설정하고 서비스 계정의 OAuth 2.0 사용자 인증 정보를 생성합니다. 요청을 인증합니다. 다음 OAuth 범위를 사용하여 OAuth 2.0 액세스 토큰을 요청하고 호출할 때마다
Authorization: BearerHTTP 헤더에 토큰을 전달합니다.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_intervalsend_time를 먼 미래로 설정해도 주기적인 재전송을 대체하지 않습니다. - 원자적 실행. API는 요청을 원자적으로 적용합니다. 후보가 검증에 실패하면 API는 전체 요청을 거부하고 피드는 이전 후보를 유지합니다.