Tích hợp đề xuất bằng API REST

API REST Khám phá video trên Google TV cho phép các đối tác gửi đề xuất không được cá nhân hoá đến các thiết bị Google TV và Android TV từ máy chủ phụ trợ của họ. Việc gửi nội dung đề xuất từ phần phụ trợ giúp danh mục và nội dung đề xuất chương trình trực tiếp của đối tác luôn mới mẻ trên các thiết bị này mà không yêu cầu người dùng mở ứng dụng của đối tác.

Đối tác gửi các đề xuất đến nguồn cấp dữ liệu đề xuất. Google tạo từng nguồn cấp dữ liệu cho đối tác và định cấu hình các quốc gia hoặc khu vực cũng như ngôn ngữ của thiết bị TV mà nguồn cấp dữ liệu đó hiển thị. Nguồn cấp dữ liệu có thể chứa phim, chương trình truyền hình và chương trình truyền hình trực tiếp.

Nếu bạn muốn xuất bản Cá nhân hoá đề xuất từ thiết bị của người dùng, hãy xem bài viết Tích hợp các đề xuất trên thiết bị bằng Engage SDK.

Điều kiện tiên quyết

Trước khi tích hợp với API REST, hãy đảm bảo bạn có những thông tin sau:

  • Một dự án Google Cloud để gửi yêu cầu API.
  • Một tài khoản Google Workspace liên kết với tổ chức của bạn.
  • Mã đối tác và mã nguồn cấp dữ liệu đề xuất do người đại diện của đối tác Google TV cung cấp trong quá trình làm quen. Hãy xem phần Nguồn cấp dữ liệu đề xuất để biết cách sử dụng các mã nhận dạng này.

Tận hưởng

Quyền truy cập vào API REST Khám phá video trên Google TV chỉ dành cho các đối tác truyền thông đã đăng ký của Google TV. Mỗi phương thức gọi được xác thực bằng một tài khoản dịch vụ Google Cloud được liên kết trên máy chủ với đúng một mã đối tác.

Để yêu cầu và định cấu hình quyền truy cập API, hãy làm theo các bước sau:

  1. Tạo tài khoản Google Workspace. Làm theo hướng dẫn trên trang hỗ trợ của Google Workspace để thiết lập tài khoản cho tổ chức của bạn.
  2. Tìm mã khách hàng Google Workspace. Tìm Mã khách hàng của bạn (ví dụ: C0123abcd) bằng cách làm theo các bước trong bài viết Tìm mã khách hàng của bạn.
  3. Tạo một dự án trên đám mây và tài khoản dịch vụ trên Google Cloud. Trong Google Cloud Console thuộc tổ chức Google Workspace của bạn, hãy tạo một dự án Google Cloud và một tài khoản dịch vụ cho máy chủ phụ trợ.
  4. Yêu cầu tham gia chương trình làm quen dành cho đối tác. Cung cấp Mã khách hàng Google Workspace, Mã dự án trên đám mây của Google và địa chỉ email của tài khoản dịch vụ (hoặc mã nhận dạng dạng số duy nhất) cho người đại diện của đối tác Google TV, cùng với các quốc gia hoặc khu vực và ngôn ngữ của thiết bị TV mà bạn muốn gửi nội dung đề xuất. Người đại diện của đối tác Google TV sẽ thông báo cho bạn sau khi liên kết tổ chức, dự án và tài khoản dịch vụ của bạn trên Google Workspace với mã đối tác, đồng thời cung cấp cho bạn mã nguồn cấp dữ liệu đề xuất được tạo cho đối tác của bạn.
  5. Bật API và tạo thông tin xác thực. Sau khi người đại diện của bạn xác nhận đã cấp quyền truy cập, hãy bật Google TV Video Discovery API (tvvideodiscovery.googleapis.com) trong dự án trên đám mây của bạn và tạo thông tin đăng nhập OAuth 2.0 cho tài khoản dịch vụ của bạn.
  6. Xác thực yêu cầu. Yêu cầu mã truy cập OAuth 2.0 bằng cách sử dụng phạm vi OAuth sau đây và truyền mã thông báo trong tiêu đề HTTP Authorization: Bearer trong mỗi lệnh gọi:

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

Giới hạn số lượng yêu cầu

Các yêu cầu gửi đến replaceCandidates phải tuân theo các giới hạn về tốc độ theo dự án và giới hạn về tải trọng theo yêu cầu sau đây:

Giới hạn Giá trị
Số yêu cầu mỗi phút trên mỗi dự án trên đám mây của Google Cloud 5
Số yêu cầu mỗi ngày trên mỗi dự án trên đám mây của Google 100
RecommendationCandidate mục cho mỗi yêu cầu 1 đến 25

Các yêu cầu đối với nguồn cấp dữ liệu thử nghiệm được tính vào cùng một hạn mức với các yêu cầu đối với nguồn cấp dữ liệu chính thức tương ứng.

Nguồn cấp dữ liệu đề xuất

API này sắp xếp các đề xuất tiềm năng vào nguồn cấp dữ liệu đề xuất. Nguồn cấp dữ liệu được xác định bằng tên tài nguyên có định dạng sau:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

Đối tác

{partner} là mã đối tác mà Google chỉ định cho bạn trong quá trình làm quen. Tài khoản dịch vụ mà bạn dùng để xác thực được liên kết với đúng một mã đối tác. Yêu cầu nêu tên bất kỳ đối tác nào khác đều không thành công với 403 PERMISSION_DENIED.

Mã nguồn cấp dữ liệu

{recommendationsFeed} là mã nguồn cấp dữ liệu mà Google tạo cho bạn trong quá trình tham gia. Bạn không thể tạo nguồn cấp dữ liệu bằng API.

Mỗi nguồn cấp dữ liệu nhắm đến một đối tượng mà Google định cấu hình khi tạo nguồn cấp dữ liệu:

  • Quốc gia hoặc khu vực: nơi các ứng viên của nguồn cấp dữ liệu xuất hiện.
  • Ngôn ngữ trên thiết bị TV: ngôn ngữ mà người dùng mục tiêu đã đặt trên thiết bị TV của họ. Đây không phải là ngôn ngữ của văn bản mà bạn gửi. Để cung cấp văn bản bằng nhiều ngôn ngữ, hãy xem LocalizedString.

Google quyết định nơi ứng viên của một nguồn cấp dữ liệu xuất hiện trên các thiết bị Google TV và Android TV. Bạn gửi các đề xuất đến mọi nguồn cấp dữ liệu theo cùng một cách.

Nguồn cấp dữ liệu thử nghiệm

Mỗi nguồn cấp dữ liệu đều có một nguồn cấp dữ liệu thử nghiệm tương ứng tên là {recommendationsFeed}-staging. Nguồn cấp dữ liệu thử nghiệm chỉ được phân phát cho các tài khoản thử nghiệm trong danh sách cho phép. Hãy sử dụng môi trường này để xác thực quá trình tích hợp trước khi gửi ứng viên đến nguồn cấp dữ liệu chính thức.

Nguồn cấp dữ liệu thử nghiệm sử dụng cùng một điểm cuối, thông tin đăng nhập, quy trình xác thực yêu cầu và hạn mức như nguồn cấp dữ liệu chính thức. Chỉ có đối tượng là khác nhau.

Thay thế

Nguồn cấp dữ liệu là đơn vị thay thế. Mỗi lệnh gọi replaceCandidates sẽ thay thế tất cả ứng viên đã lưu trữ trước đó cho nguồn cấp dữ liệu đó và giữ nguyên mọi nguồn cấp dữ liệu khác.

Thay thế các đề xuất

Sử dụng phương thức partners.recommendationsFeeds.replaceCandidates để gửi danh sách đầy đủ các đề xuất cho một nguồn cấp dữ liệu.

Yêu cầu HTTP

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

Đường dẫn URL chứa tên tài nguyên của nguồn cấp dữ liệu có ứng viên được thay thế. Nội dung yêu cầu chứa mọi trường không thuộc đường dẫn URL.

Tham số đường dẫn

Tham số Mô tả
name Bắt buộc. Tên tài nguyên của nguồn cấp dữ liệu, ở định dạng partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} phải là mã đối tác mà tài khoản dịch vụ của bạn được liên kết. {recommendationsFeed} phải là mã nhận dạng nguồn cấp dữ liệu mà Google đã tạo cho đối tác đó hoặc mã nhận dạng nguồn cấp dữ liệu có hậu tố -staging.

ReplaceCandidatesRequest

Nội dung yêu cầu JSON có cấu trúc như sau:

Trường Loại Bắt buộc Mô tả
recommendation_candidates array of RecommendationCandidate Có Danh sách từ 1 đến 25 mục RecommendationCandidate. Những ứng viên này sẽ thay thế các ứng viên hiện tại của nguồn cấp dữ liệu.

Giản đồ đề xuất

Mỗi mục trong recommendation_candidates là một đối tượng RecommendationCandidate chứa một tải trọng loại đề xuất, lý do đề xuất không bắt buộc và khung thời gian phát sóng hiển thị không bắt buộc.

RecommendationCandidate

Đối tượng RecommendationCandidate chứa đúng một trường tải trọng loại nội dung nghe nhìn, lý do đề xuất không bắt buộc và khoảng thời gian có thể xem không bắt buộc.

Trường nhóm candidate_type

candidate_type là bắt buộc: hãy đặt chính xác một trong các trường sau. Các trường này loại trừ lẫn nhau và ứng viên không đặt trường nào hoặc đặt nhiều hơn một trường sẽ bị từ chối. Không có khoá candidate_type trong JSON; hãy đặt trường đã chọn trực tiếp trên đối tượng RecommendationCandidate.

Trường Loại Mô tả
movie_candidate MovieCandidate Phim theo yêu cầu (xem MovieCandidate).
tv_show_candidate TvShowCandidate Chương trình truyền hình ở cấp chương trình (xem TvShowCandidate).
live_tv_program_candidate LiveTvProgramCandidate Một chương trình truyền hình trực tiếp hoặc sự kiện phát trực tuyến theo lịch (xem LiveTvProgramCandidate).

Bối cảnh và phạm vi cung cấp

Cả hai trường đều không bắt buộc:

Trường Loại Bắt buộc Mô tả
recommendation_contexts array of RecommendationContext Không Lý do đề xuất ứng viên và thời gian áp dụng của từng lý do (xem RecommendationContext).
availability_intervals array of Interval Không Khung thời gian mà ứng viên có thể được hiển thị (xem Interval). Mỗi khung thời gian bắt đầu từ start_time (bao gồm) và kết thúc tại end_time (không bao gồm). Nếu bạn không đặt, thì ứng viên sẽ đủ điều kiện trong suốt thời gian được lưu trữ. Một ứng cử viên có tất cả cửa sổ đều nằm trong quá khứ sẽ không bao giờ được hiển thị.

MovieCandidate

Đối tượng MovieCandidate đại diện cho một bộ phim theo yêu cầu:

Trường Loại Bắt buộc Mô tả
title LocalizedString Có Tên phim (xem LocalizedString). Mỗi giá trị có từ 1 đến 100 điểm mã Unicode và được hiển thị như khi gửi.
description LocalizedString Có Nội dung mô tả ngắn về phim (xem LocalizedString). Mỗi giá trị có từ 1 đến 400 điểm mã Unicode.
localized_media_images array of LocalizedMediaImage Có Hình ảnh minh hoạ có tỷ lệ khung hình 16:9, mỗi ngôn ngữ một mục (xem LocalizedMediaImage). Phải chứa ít nhất một hình ảnh. Cung cấp nguồn lớn nhất hiện có; bạn nên dùng kích thước 1920 x 1080 pixel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Có Đường liên kết sâu cho mỗi nền tảng và mỗi ngôn ngữ (xem LocalizedProviderPlaybackUri). Ít nhất một mục phải liệt kê PLATFORM_ANDROID_TV.
release_date Date Có Ngày phát hành phim (xem Date).
external_entity_ids array of ExternalEntityId Không Giá trị nhận dạng danh mục bên ngoài để so khớp thực thể (xem ExternalEntityId). Tối đa một mục nhập cho mỗi loại giá trị nhận dạng.
duration string (Duration) Không Thời lượng của phim (xem Duration). Ví dụ: "7200s" cho 2 giờ.
content_ratings array of ContentRating Không Mức phân loại nội dung chính thức (xem ContentRating).

TvShowCandidate

Đối tượng TvShowCandidate đại diện cho một chương trình truyền hình ở cấp chương trình. Thiết bị Google TV và Android TV sẽ hiển thị một thẻ cho chương trình; hãy sử dụng đường liên kết sâu để quyết định xem có bắt đầu phát trên trang chương trình hay trên một tập cụ thể hay không.

Trường Loại Bắt buộc Mô tả
title LocalizedString Có Tên của chương trình truyền hình (xem LocalizedString). Mỗi giá trị có từ 1 đến 100 điểm mã Unicode và được hiển thị như khi gửi.
description LocalizedString Có Nội dung mô tả ngắn về chương trình truyền hình (xem LocalizedString). Mỗi giá trị có từ 1 đến 400 điểm mã Unicode.
localized_media_images array of LocalizedMediaImage Có Hình ảnh minh hoạ có tỷ lệ khung hình 16:9, mỗi ngôn ngữ một mục (xem LocalizedMediaImage). Phải chứa ít nhất một hình ảnh. Cung cấp nguồn lớn nhất hiện có; bạn nên dùng kích thước 1920 x 1080 pixel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Có Đường liên kết sâu cho mỗi nền tảng và mỗi ngôn ngữ (xem LocalizedProviderPlaybackUri). Ít nhất một mục phải liệt kê PLATFORM_ANDROID_TV. uri có thể trỏ đến trang chương trình hoặc một tập.
first_episode_air_date Date Có Ngày phát sóng tập đầu tiên (xem Date).
external_entity_ids array of ExternalEntityId Không Giá trị nhận dạng danh mục bên ngoài để so khớp thực thể (xem ExternalEntityId). Tối đa một mục nhập cho mỗi loại giá trị nhận dạng.
season_count integer (int32) Không Số mùa có trên dịch vụ của bạn.
content_ratings array of ContentRating Không Mức phân loại nội dung chính thức (xem ContentRating).

LiveTvProgramCandidate

Đối tượng LiveTvProgramCandidate đại diện cho một chương trình truyền hình trực tiếp hoặc sự kiện phát trực tuyến theo lịch. Cửa sổ phát sóng là một phần của đề xuất và tách biệt với availability_intervals của đề xuất mẹ, giúp kiểm soát thời điểm thẻ có thể xuất hiện.

Trường Loại Bắt buộc Mô tả
title LocalizedString Có Tiêu đề của chương trình truyền hình trực tiếp (xem LocalizedString). Mỗi giá trị là từ 1 đến 100 điểm mã Unicode và được hiển thị như khi gửi.
description LocalizedString Có Nội dung mô tả ngắn về chương trình truyền hình trực tuyến (xem LocalizedString). Mỗi giá trị có từ 1 đến 400 điểm mã Unicode.
localized_media_images array of LocalizedMediaImage Có Hình ảnh minh hoạ có tỷ lệ khung hình 16:9, mỗi ngôn ngữ một mục (xem LocalizedMediaImage). Phải chứa ít nhất một hình ảnh. Cung cấp nguồn lớn nhất hiện có; bạn nên dùng kích thước 1920 x 1080 pixel.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Có Đường liên kết sâu cho mỗi nền tảng và mỗi ngôn ngữ (xem LocalizedProviderPlaybackUri). Ít nhất một mục phải liệt kê PLATFORM_ANDROID_TV.
broadcast_interval Interval Có Thời gian bắt đầu và kết thúc phát sóng của chương trình (xem Interval). Bạn phải cung cấp cả start_time và end_time.
external_entity_ids array of ExternalEntityId Không Giá trị nhận dạng danh mục bên ngoài để so khớp thực thể (xem ExternalEntityId). Tối đa một mục nhập cho mỗi loại giá trị nhận dạng.
content_ratings array of ContentRating Không Mức phân loại nội dung chính thức (xem ContentRating).

Giản đồ hỗ trợ

Trọng tải đề xuất tham chiếu đến các đối tượng dùng chung sau đây cho văn bản đã bản địa hoá, đường liên kết sâu, hình minh hoạ, giá trị nhận dạng bên ngoài, lý do đề xuất, khoảng thời gian hiển thị, mức phân loại nội dung và các loại ngày giờ phổ biến.

LocalizedString

Đối tượng LocalizedString chứa cùng một văn bản bằng một hoặc nhiều ngôn ngữ. Mỗi giá trị được gắn thẻ bằng ngôn ngữ của giá trị đó để thiết bị Google TV và Android TV có thể hiển thị văn bản khớp với ngôn ngữ trên thiết bị TV của người dùng:

Trường Loại Bắt buộc Mô tả
values array of LocalizedText Có Văn bản bằng từng ngôn ngữ mà bạn cung cấp (xem LocalizedText). Phải chứa ít nhất một giá trị.

LocalizedText

Đối tượng LocalizedText là văn bản bằng một ngôn ngữ:

Trường Loại Bắt buộc Mô tả
text string Có Văn bản bằng ngôn ngữ do language_code cung cấp.
language_code string Có Mã ngôn ngữ BCP-47 của text, chẳng hạn như "en-US" hoặc "sr-Latn".

LocalizedMediaImage

Đối tượng LocalizedMediaImage ghép nối hình ảnh với ngôn ngữ của văn bản bất kỳ trong hình ảnh:

Trường Loại Bắt buộc Mô tả
language_code string Có Mã ngôn ngữ BCP-47 của văn bản trong hình ảnh, chẳng hạn như "en-US" hoặc "sr-Latn".
image MediaImage Có Hình ảnh có tỷ lệ 16:9 (xem MediaImage). Cung cấp nguồn lớn nhất hiện có; nên dùng 1920x1080 pixel.

LocalizedProviderPlaybackUri

Đối tượng LocalizedProviderPlaybackUri ghép nối một đường liên kết sâu với ngôn ngữ của nội dung mà đường liên kết đó mở ra và ứng dụng mở đường liên kết đó:

Trường Loại Bắt buộc Mô tả
playback_uri PlaybackUri Có Đường liên kết sâu và các nền tảng áp dụng đường liên kết sâu đó (xem PlaybackUri).
language_code string Có Mã ngôn ngữ BCP-47 của nội dung mà đường liên kết sâu mở ra, chẳng hạn như "en-US" hoặc "sr-Latn".
package_name string Có Tên gói ứng dụng Android dùng để mở đường liên kết sâu (ví dụ: "com.example.tvapp").

PlaybackUri

Đối tượng PlaybackUri xác định một đường liên kết sâu và các nền tảng mục tiêu của đường liên kết đó:

Trường Loại Bắt buộc Mô tả
uri string Có URI đường liên kết sâu bắt đầu phát nội dung đề xuất trong ứng dụng của bạn.
platforms array of string (enum) Có Các nền tảng mà đường liên kết sâu này áp dụng. Các giá trị được phép: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Thêm PLATFORM_ANDROID_TV cho thiết bị Google TV và Android TV.

MediaImage

Đối tượng MediaImage chỉ định URL hình ảnh, kích thước pixel và văn bản hỗ trợ tiếp cận:

Trường Loại Bắt buộc Mô tả
url string Có URL loại HTTPS có thể truy cập công khai của hình ảnh.
width integer Có Chiều rộng hình ảnh chưa sửa đổi (tối đa) tính bằng pixel.
height integer Có Chiều cao hình ảnh chưa sửa đổi (tối đa) tính bằng pixel.
accessibility_text string Có Văn bản hỗ trợ tiếp cận (văn bản thay thế) mô tả hình ảnh.

ExternalEntityId

Đối tượng ExternalEntityId liên kết một đề xuất với một giá trị nhận dạng trong danh mục bên ngoài. Đặt chính xác một trong các trường sau cho mỗi mục nhập và thêm tối đa một mục nhập cho mỗi loại giá trị nhận dạng trong danh sách external_entity_ids của ứng viên:

Trường Loại Bắt buộc Mô tả
tms_root_id string Một trong Mã gốc TMS của Gracenote. Xác định một tiêu đề: phim, chương trình hoặc tập.
tms_id string Một trong Mã biến thể Gracenote TMS. Xác định một ấn bản hoặc danh sách phát sóng.
data_feed_element_id string Một trong Mã nhận dạng thực thể trong nguồn cấp dữ liệu Hành động trong nội dung nghe nhìn. Giá trị này không liên quan đến phân đoạn {recommendationsFeed} của tên tài nguyên.

RecommendationContext

Đối tượng RecommendationContext giải thích lý do đề xuất một ứng viên và thời gian áp dụng nội dung giải thích đó:

Trường Loại Bắt buộc Mô tả
recommendation_reason RecommendationReason Không Lý do đề xuất ứng viên (xem RecommendationReason).
validity_interval Interval Không Khung thời gian áp dụng bối cảnh này (xem Interval). Ví dụ: một ứng viên chỉ được coi là mới trong một số ngày nhất định. Nếu bạn không đặt, ngữ cảnh sẽ áp dụng trong suốt thời gian lưu trữ ứng viên.

RecommendationReason

Đối tượng RecommendationReason chứa một lý do. Đặt chính xác một trong các trường sau:

Trường Loại Bắt buộc Mô tả
top_on_partner object Một trong Ứng viên là một mục được xếp hạng cao nhất trên dịch vụ của bạn. Chứa một trường số nguyên dương rank (ví dụ: {"rank": 1} cho "Top 1 on Partner").
popular_on_partner object Một trong Ứng viên này phổ biến trên dịch vụ của bạn. Truyền một đối tượng trống ({}).
new_on_partner object Một trong Ứng viên này mới sử dụng dịch vụ của bạn. Truyền một đối tượng trống ({}).
generic object Một trong Lý do tuỳ chỉnh. Chứa một trường LocalizedString generic_reason (xem LocalizedString). Mỗi giá trị là từ 1 đến 100 điểm mã Unicode.

ContentRating

Đối tượng ContentRating đại diện cho mức phân loại nội dung chính thức do một cơ quan phân loại chỉ định:

Trường Loại Bắt buộc Mô tả
rating_system string Có Cơ quan hoặc hệ thống phân loại, ví dụ: "MPAA", "BBFC" hoặc "CBFC".
rating_value string Có Điểm xếp hạng theo định nghĩa của rating_system, ví dụ: "PG-13" hoặc "U/A 13+".

Timestamp

Timestamp được mã hoá trong JSON dưới dạng chuỗi RFC 3339 theo giờ UTC với hậu tố Z, ví dụ: "2026-10-01T18:00:00Z". Bạn có thể dùng giây thập phân, ví dụ: "2026-10-01T18:00:00.500Z".

Duration

Duration được mã hoá trong JSON dưới dạng một chuỗi chứa số giây, theo sau là hậu tố s, ví dụ: "7200s" cho 2 giờ. Bạn có thể sử dụng giây phân số, ví dụ: "5400.5s".

Date

Date là ngày theo lịch không có múi giờ. Nó được mã hoá trong JSON dưới dạng một đối tượng có các trường sau:

Trường Loại Bắt buộc Mô tả
year integer Có Năm của ngày, ví dụ: 2025.
month integer Không Tháng trong năm, từ 1 đến 12. Đặt thành 0 hoặc bỏ qua nếu không biết tháng.
day integer Không Ngày trong tháng, từ 1 đến 31 và hợp lệ cho năm và tháng đã cho. Đặt thành 0 hoặc bỏ qua nếu không biết ngày. Cần có month.

Ví dụ: {"year": 2025, "month": 1, "day": 17} đại diện cho ngày 17 tháng 1 năm 2025, {"year": 2025, "month": 1} đại diện cho tháng 1 năm 2025 nhưng không rõ ngày, và {"year": 2025} đại diện cho một ngày trong năm 2025 nhưng không rõ tháng và ngày.

Interval

Interval là một khung thời gian nửa mở, bắt đầu từ start_time (bao gồm) và kết thúc tại end_time (không bao gồm). Thời gian T nằm trong khoảng thời gian khi start_time <= T và T < end_time.

Trường Loại Bắt buộc Mô tả
start_time string (Timestamp) Có Điểm bắt đầu của khoảng thời gian (bao gồm cả điểm này, xem Timestamp), ví dụ: "2026-10-01T18:00:00Z".
end_time string (Timestamp) Có Điểm kết thúc của khoảng thời gian (không bao gồm) (xem Timestamp), ví dụ: "2026-10-01T21:00:00Z". Phải muộn hơn start_time.

Yêu cầu mẫu

Ví dụ sau đây thay thế các đề cử của nguồn cấp dữ liệu in-en-cricket của đối tác example-partner bằng ba đề cử (một bộ phim, một chương trình truyền hình và một chương trình truyền hình trực tiếp). Bộ phim có văn bản bằng hai ngôn ngữ:

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"
          }
        ]
      }
    ]
  }'

Hành vi phản hồi và thay thế

Phần này mô tả phản hồi HTTP do replaceCandidates trả về và cách mỗi lệnh gọi cập nhật các ứng viên được lưu trữ của bạn.

ReplaceCandidatesResponse

Nếu yêu cầu thành công, API sẽ trả về HTTP 200 OK với nội dung ReplaceCandidatesResponse:

Trường Loại Mô tả
replaced_candidates_count integer (int32) Số lượng ứng viên được thay thế.

Đối với yêu cầu mẫu trước đó, phản hồi sẽ là:

{
  "replaced_candidates_count": 3
}

Hành vi thay thế

Bạn cần hiểu rõ cách replaceCandidates cập nhật các ứng viên được lưu trữ để thiết kế quy trình tích hợp:

  • Thay thế toàn bộ cho mỗi nguồn cấp dữ liệu. Mỗi lệnh gọi sẽ thay thế hoàn toàn danh sách ứng viên đã lưu trữ trước đó cho nguồn cấp dữ liệu có tên trong đường dẫn URL. Luôn gửi bộ ứng viên đang hoạt động hoàn chỉnh cho nguồn cấp dữ liệu đó.
  • Các nguồn cấp dữ liệu khác vẫn không thay đổi. Những nguồn cấp dữ liệu mà bạn không gửi ứng viên đến sẽ không thay đổi cho đến khi bạn gửi. Ví dụ: việc thay thế ứng viên của một nguồn cấp dữ liệu sẽ không sửa đổi ứng viên được lưu trữ cho bất kỳ nguồn cấp dữ liệu nào khác và việc thay thế ứng viên của {recommendationsFeed}-staging sẽ không sửa đổi {recommendationsFeed}.
  • Một lệnh gọi cho mỗi nguồn cấp dữ liệu. Để cập nhật nhiều nguồn cấp dữ liệu, hãy thực hiện một lệnh gọi cho mỗi nguồn cấp dữ liệu. Các lệnh gọi này độc lập với nhau: nếu một lệnh gọi không thành công, các nguồn cấp dữ liệu khác sẽ giữ lại các đề xuất mới và bạn chỉ cần thử lại lệnh gọi không thành công.
  • Gửi lại nguồn cấp dữ liệu đang hoạt động ít nhất 30 ngày một lần. Ngay cả khi danh mục của một nguồn cấp dữ liệu không thay đổi, hãy gửi lại từng nguồn cấp dữ liệu đang hoạt động ít nhất một lần mỗi 30 ngày (hoặc theo lịch biểu hằng ngày hoặc hằng tuần thông thường với độ trễ ngẫu nhiên) để các ứng viên vẫn hoạt động và không hết hạn. Việc đặt availability_intervals end_time trong tương lai xa không thay thế cho việc gửi lại định kỳ.
  • Thực thi nguyên tử. API áp dụng yêu cầu một cách tự động. Nếu có bất kỳ ứng viên nào không vượt qua được quy trình xác thực, API sẽ từ chối toàn bộ yêu cầu và nguồn cấp dữ liệu sẽ giữ lại các ứng viên trước đó.