REST API สำหรับการค้นพบวิดีโอของ Google TV ช่วยให้พาร์ทเนอร์ส่งวิดีโอแนะนำที่ไม่ได้ปรับเปลี่ยนในแบบของคุณไปยังอุปกรณ์ Google TV และอุปกรณ์ Android TV จากเซิร์ฟเวอร์แบ็กเอนด์ได้ การส่งรายการที่แนะนำจากแบ็กเอนด์จะช่วยให้แคตตาล็อกและวิดีโอแนะนำรายการสดของพาร์ทเนอร์อัปเดตอยู่เสมอในอุปกรณ์เหล่านี้โดยที่ผู้ใช้ไม่ต้องเปิดแอปของพาร์ทเนอร์
พาร์ทเนอร์จะส่งรายการที่อาจเป็นไปได้ไปยังฟีดวิดีโอแนะนำ Google จะสร้างฟีดแต่ละรายการให้พาร์ทเนอร์และกำหนดค่าประเทศหรือภูมิภาค รวมถึงภาษาของอุปกรณ์ทีวีที่จะแสดงฟีด ฟีดอาจมีภาพยนตร์ รายการทีวี และรายการทีวีสด
หากต้องการเผยแพร่คำแนะนำที่ปรับเปลี่ยนในแบบของคุณจากอุปกรณ์ของผู้ใช้ โปรดดูหัวข้อผสานรวมคำแนะนำในอุปกรณ์โดยใช้ Engage SDK
สิ่งที่ต้องมีก่อน
ก่อนผสานรวมกับ REST API โปรดตรวจสอบว่าคุณมีสิ่งต่อไปนี้
- โปรเจ็กต์ Google Cloud เพื่อส่งคำขอ API
- บัญชี Google Workspace ที่เชื่อมโยงกับองค์กรของคุณ
- รหัสพาร์ทเนอร์และรหัสฟีดวิดีโอแนะนำที่ตัวแทนพาร์ทเนอร์ Google TV ให้ไว้ระหว่างการเริ่มต้นใช้งาน ดูวิธีใช้รหัสเหล่านี้ได้ที่ฟีดวิดีโอแนะนำ
รับสิทธิ์
สิทธิ์เข้าถึง REST API ของ Google TV Video Discovery จำกัดไว้สำหรับพาร์ทเนอร์สื่อของ Google TV ที่ลงทะเบียนแล้วเท่านั้น ผู้โทรแต่ละรายจะได้รับการตรวจสอบสิทธิ์โดยใช้บัญชีบริการ Google Cloud ที่แมปบนเซิร์ฟเวอร์กับรหัสพาร์ทเนอร์เพียงรหัสเดียว
หากต้องการขอและกำหนดค่าสิทธิ์เข้าถึง API ให้ทำตามขั้นตอนต่อไปนี้
- สร้างบัญชี Google Workspace ทำตามวิธีการในหน้าการสนับสนุนของ Google Workspace เพื่อตั้งค่าบัญชีสำหรับองค์กร
- ค้นหารหัสลูกค้า Google Workspace ค้นหารหัสลูกค้า (เช่น
C0123abcd) โดยทำตามขั้นตอนในหัวข้อค้นหารหัสลูกค้า - สร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และบัญชีบริการ ในคอนโซล Google Cloud ภายใต้องค์กร Google Workspace ให้สร้างโปรเจ็กต์ Google Cloud และบัญชีบริการสำหรับเซิร์ฟเวอร์แบ็กเอนด์
- ขอการเริ่มต้นใช้งานสำหรับพาร์ทเนอร์ ระบุรหัสลูกค้า Google Workspace, รหัสโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และอีเมลบัญชีบริการ (หรือรหัสตัวเลขที่ไม่ซ้ำกัน) ให้กับตัวแทนพาร์ทเนอร์ Google TV พร้อมกับประเทศหรือภูมิภาคและภาษาของอุปกรณ์ทีวีที่คุณต้องการส่งผู้สมัครไปให้ ตัวแทนพาร์ทเนอร์ Google TV จะแจ้งให้คุณทราบหลังจากแมปองค์กร โปรเจ็กต์ และบัญชีบริการ Google Workspace กับรหัสพาร์ทเนอร์ และให้รหัสฟีดวิดีโอแนะนำที่สร้างขึ้นสำหรับพาร์ทเนอร์แก่คุณ
- เปิดใช้ API และสร้างข้อมูลเข้าสู่ระบบ หลังจากตัวแทนยืนยันว่าได้รับสิทธิ์เข้าถึงแล้ว ให้เปิดใช้ Google TV Video Discovery API (
tvvideodiscovery.googleapis.com) ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และสร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 สำหรับบัญชีบริการ ตรวจสอบสิทธิ์คำขอ ขอโทเค็นเพื่อการเข้าถึง OAuth 2.0 โดยใช้ขอบเขต OAuth ต่อไปนี้ และส่งโทเค็นในส่วนหัว HTTP
Authorization: Bearerในการเรียกทุกครั้งhttps://www.googleapis.com/auth/tvvideodiscovery
ขีดจำกัดอัตรา
คำขอไปยัง replaceCandidates จะขึ้นอยู่กับการจำกัดอัตราคำขอต่อโปรเจ็กต์และขีดจำกัดเพย์โหลดต่อคำขอต่อไปนี้
| ขีดจำกัด | ค่า |
|---|---|
| คำขอต่อนาทีต่อโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google | 5 |
| คำขอต่อวันต่อโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google | 100 |
RecommendationCandidate รายการต่อคำขอ |
1 ถึง 25 |
คำขอไปยังฟีดทดลองจะนับรวมในโควต้าเดียวกับคำขอไปยังฟีดสินค้าเวอร์ชันที่ใช้งานจริงที่เกี่ยวข้อง
ฟีดวิดีโอแนะนำ
API จะจัดระเบียบรายการแนะนำที่เป็นไปได้ลงในฟีดวิดีโอแนะนำ ฟีดจะระบุด้วยชื่อทรัพยากรในรูปแบบต่อไปนี้
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
พาร์ทเนอร์
{partner} คือรหัสพาร์ทเนอร์ที่ Google กำหนดให้คุณในระหว่างการเริ่มต้นใช้งาน บัญชีบริการที่คุณตรวจสอบสิทธิ์จะแมปกับรหัสพาร์ทเนอร์เพียงรหัสเดียวเท่านั้น
คำขอที่ระบุชื่อพาร์ทเนอร์รายอื่นจะดำเนินการไม่สำเร็จพร้อมข้อผิดพลาด 403 PERMISSION_DENIED
รหัสฟีด
{recommendationsFeed} คือรหัสฟีดที่ Google สร้างให้คุณในระหว่างการเริ่มต้นใช้งาน คุณสร้างฟีดด้วย API ไม่ได้
ฟีดแต่ละรายการจะกำหนดเป้าหมายไปยังกลุ่มเป้าหมายที่ Google กำหนดค่าไว้เมื่อสร้างฟีด ดังนี้
- ประเทศหรือภูมิภาค: ที่แสดงผู้สมัครรับเลือกตั้งของฟีด
- ภาษาของอุปกรณ์ทีวี: ภาษาที่ผู้ใช้เป้าหมายตั้งค่าไว้ในอุปกรณ์ทีวี นี่ไม่ใช่ภาษาของข้อความที่คุณส่ง หากต้องการระบุข้อความมากกว่า 1 ภาษา โปรดดู
LocalizedString
Google จะตัดสินใจว่าจะแสดงรายการที่อาจได้แสดงของฟีดที่ใดในอุปกรณ์ Google TV และ Android TV คุณส่งผู้สมัครไปยังทุกฟีดด้วยวิธีเดียวกัน
ฟีดทดลองใช้
แต่ละฟีดจะมีฟีดทดลองใช้ที่ตรงกันชื่อ {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} ต้องเป็นรหัสพาร์ทเนอร์ที่แมปกับบัญชีบริการของคุณ {recommendationsFeed} ต้องเป็นรหัสฟีดที่ Google สร้างขึ้นสำหรับพาร์ทเนอร์รายนั้น หรือรหัสฟีดที่มีคำต่อท้าย -staging |
ReplaceCandidatesRequest
เนื้อหาคำขอ JSON มีโครงสร้างดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
ใช่ | รายการ RecommendationCandidate 1 ถึง 25 รายการ ผู้สมัครเหล่านี้จะแทนที่ผู้สมัครปัจจุบันของฟีด |
สคีมาที่เป็นไปได้
แต่ละรายการใน recommendation_candidates คือออบเจ็กต์ RecommendationCandidate ที่มีเพย์โหลดประเภทผู้สมัคร 1 รายการ เหตุผลในการแนะนำ (ไม่บังคับ) และระยะเวลาที่พร้อมจำหน่าย (ไม่บังคับ)
RecommendationCandidate
ออบเจ็กต์ RecommendationCandidate มีฟิลด์เพย์โหลดประเภทสื่อ 1 ฟิลด์ เหตุผลในการแนะนำที่ไม่บังคับ และช่วงเวลาที่พร้อมให้บริการที่ไม่บังคับ
ฟิลด์ Union candidate_type
ต้องระบุ candidate_type: ตั้งค่าฟิลด์ใดฟิลด์หนึ่งต่อไปนี้ ฟิลด์เหล่านี้เป็นข้อมูลแยกกัน และระบบจะปฏิเสธผู้สมัครที่ไม่ได้ตั้งค่าหรือตั้งค่ามากกว่า 1 รายการ ไม่มีคีย์ candidate_type ใน JSON ให้ตั้งค่าฟิลด์ที่เลือก
ในออบเจ็กต์ RecommendationCandidate โดยตรง
| ช่อง | ประเภท | คำอธิบาย |
|---|---|---|
movie_candidate |
MovieCandidate |
ภาพยนตร์แบบออนดีมานด์ (ดู MovieCandidate) |
tv_show_candidate |
TvShowCandidate |
รายการทีวีที่ระดับรายการ (ดู TvShowCandidate) |
live_tv_program_candidate |
LiveTvProgramCandidate |
การออกอากาศรายการทีวีสดหรือกิจกรรมที่สตรีมตามกำหนดเวลา (ดู LiveTvProgramCandidate) |
บริบทและความพร้อมใช้งาน
ทั้ง 2 ช่องไม่บังคับให้กรอกข้อมูล
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
ไม่ | เหตุผลที่แนะนำผู้สมัคร และระยะเวลาที่เหตุผลแต่ละข้อมีผล (ดู RecommendationContext) |
availability_intervals |
array of Interval |
ไม่ | กรอบเวลาที่อาจแสดงผู้สมัคร (ดู Interval) กรอบเวลาแต่ละรายการจะเริ่มต้นที่ start_time (รวม) และสิ้นสุดที่ end_time (ไม่รวม) หากไม่ได้ตั้งค่า ผู้สมัครจะมีสิทธิ์ตราบเท่าที่ยังจัดเก็บไว้ ระบบจะไม่แสดงผู้สมัครที่มีกรอบเวลาทั้งหมดอยู่ในอดีต |
MovieCandidate
ออบเจ็กต์ MovieCandidate แสดงถึงภาพยนตร์แบบออนดีมานด์ ดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
title |
LocalizedString |
ใช่ | ชื่อภาพยนตร์ (ดู LocalizedString) แต่ละค่ามี Code Point ของ Unicode 1-100 รายการและแสดงตามที่ส่ง |
description |
LocalizedString |
ใช่ | คำอธิบายสั้นๆ ของภาพยนตร์ (ดู LocalizedString) แต่ละค่าคือ Code Point ของ Unicode 1 ถึง 400 รายการ |
localized_media_images |
array of LocalizedMediaImage |
ใช่ | รูปภาพอาร์ตเวิร์ก 16:9, 1 รายการต่อภาษา (ดู LocalizedMediaImage) ต้องมีรูปภาพอย่างน้อย 1 รูป ใช้แหล่งที่มาที่มีขนาดใหญ่ที่สุดเท่าที่มี โดยแนะนำให้ใช้ขนาด 1920x1080 พิกเซล |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
ใช่ | Deep Link ต่อแพลตฟอร์มและต่อภาษา (ดู LocalizedProviderPlaybackUri) โดยต้องมีรายการอย่างน้อย 1 รายการที่แสดง PLATFORM_ANDROID_TV |
release_date |
Date |
ใช่ | วันที่เผยแพร่ภาพยนตร์ (ดู Date) |
external_entity_ids |
array of ExternalEntityId |
ไม่ | ตัวระบุแคตตาล็อกภายนอกสำหรับการจับคู่เอนทิตี (ดู ExternalEntityId) รายการต่อประเภทตัวระบุไม่เกิน 1 รายการ |
duration |
string (Duration) |
ไม่ | ระยะเวลาของภาพยนตร์ (ดู Duration) เช่น "7200s" เป็นเวลา 2 ชั่วโมง |
content_ratings |
array of ContentRating |
ไม่ | การจัดประเภทเนื้อหาอย่างเป็นทางการ (ดู ContentRating) |
TvShowCandidate
ออบเจ็กต์ TvShowCandidate แสดงรายการทีวีที่ระดับรายการ อุปกรณ์ Google TV และ Android TV จะแสดงการ์ดสำหรับรายการนั้นๆ โดยใช้ Deep Link เพื่อตัดสินใจว่าจะเริ่มเล่นในหน้ารายการหรือตอนที่เฉพาะเจาะจง
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
title |
LocalizedString |
ใช่ | ชื่อรายการทีวี (ดู LocalizedString) แต่ละค่ามี Code Point ของ Unicode 1-100 รายการและแสดงตามที่ส่ง |
description |
LocalizedString |
ใช่ | คำอธิบายสั้นๆ ของรายการทีวี (ดู LocalizedString) โดยแต่ละค่าจะมี Code Point ของ Unicode 1-400 รายการ |
localized_media_images |
array of LocalizedMediaImage |
ใช่ | รูปภาพอาร์ตเวิร์ก 16:9, 1 รายการต่อภาษา (ดู LocalizedMediaImage) ต้องมีรูปภาพอย่างน้อย 1 รูป ใช้แหล่งที่มาที่มีขนาดใหญ่ที่สุดเท่าที่มี โดยแนะนำให้ใช้ขนาด 1920x1080 พิกเซล |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
ใช่ | Deep Link ต่อแพลตฟอร์มและต่อภาษา (ดู 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) แต่ละค่ามี Code Point ของ Unicode 1 ถึง 100 รายการและแสดงตามที่ส่ง |
description |
LocalizedString |
ใช่ | คำอธิบายสั้นๆ ของรายการทีวีสด (ดู LocalizedString) โดยแต่ละค่าจะมี Code Point ของ Unicode 1-400 รายการ |
localized_media_images |
array of LocalizedMediaImage |
ใช่ | รูปภาพอาร์ตเวิร์ก 16:9, 1 รายการต่อภาษา (ดู LocalizedMediaImage) ต้องมีรูปภาพอย่างน้อย 1 รูป ใช้แหล่งที่มาที่มีขนาดใหญ่ที่สุดเท่าที่มี โดยแนะนำให้ใช้ขนาด 1920x1080 พิกเซล |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
ใช่ | Deep Link ต่อแพลตฟอร์มและต่อภาษา (ดู 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) |
สคีมาที่รองรับ
เพย์โหลดที่เป็นไปได้จะอ้างอิงออบเจ็กต์ที่ใช้ร่วมกันต่อไปนี้สำหรับข้อความที่แปลแล้ว, Deep Link, อาร์ตเวิร์ก, ตัวระบุภายนอก, เหตุผลในการแนะนำ, ช่วงเวลาที่แสดง, การจัดประเภทเนื้อหา และประเภทวันที่และเวลาที่รู้จักกันดี
LocalizedString
ออบเจ็กต์ LocalizedString มีข้อความเดียวกันในภาษาอย่างน้อย 1 ภาษา
ค่าแต่ละค่าจะได้รับการติดแท็กด้วยภาษาของค่านั้น เพื่อให้อุปกรณ์ Google TV และ Android TV สามารถแสดงข้อความที่ตรงกับภาษาของอุปกรณ์ทีวีของผู้ใช้ได้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
values |
array of LocalizedText |
ใช่ | ข้อความในแต่ละภาษาที่คุณระบุ (ดู LocalizedText) ต้องมีค่าอย่างน้อย 1 ค่า |
LocalizedText
ออบเจ็กต์ LocalizedText เป็นข้อความในภาษาเดียว ดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
text |
string |
ใช่ | ข้อความในภาษาที่ระบุโดย language_code |
language_code |
string |
ใช่ | รหัสภาษา BCP-47 ของ text เช่น "en-US" หรือ "sr-Latn" |
LocalizedMediaImage
ออบเจ็กต์ LocalizedMediaImage จะจับคู่รูปภาพกับภาษาของข้อความในรูปภาพ
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
language_code |
string |
ใช่ | รหัสภาษา BCP-47 ของข้อความในรูปภาพ เช่น "en-US" หรือ "sr-Latn" |
image |
MediaImage |
ใช่ | รูปภาพ 16:9 (ดู MediaImage) ระบุแหล่งที่มาที่ใหญ่ที่สุดที่มีอยู่ โดยแนะนำให้ใช้ 1920x1080 พิกเซล |
LocalizedProviderPlaybackUri
ออบเจ็กต์ LocalizedProviderPlaybackUri จะจับคู่ Deep Link กับภาษาของเนื้อหาที่เปิดและแอปที่เปิดเนื้อหา ดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
playback_uri |
PlaybackUri |
ใช่ | Deep Link และแพลตฟอร์มที่ใช้ Deep Link (ดู PlaybackUri) |
language_code |
string |
ใช่ | รหัสภาษา BCP-47 ของเนื้อหาที่ Deep Link เปิด เช่น "en-US" หรือ "sr-Latn" |
package_name |
string |
ใช่ | ชื่อแพ็กเกจแอปพลิเคชัน Android ที่ใช้เปิด Deep Link (เช่น "com.example.tvapp") |
PlaybackUri
ออบเจ็กต์ PlaybackUri จะกำหนด Deep Link และแพลตฟอร์มเป้าหมาย ดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
uri |
string |
ใช่ | URI ของ Deep Link ที่เริ่มเล่นเนื้อหาที่เสนอในแอปของคุณ |
platforms |
array of string (enum) |
ใช่ | แพลตฟอร์มที่ Deep Link นี้ใช้ได้ ค่าที่อนุญาต: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS รวม PLATFORM_ANDROID_TV สำหรับอุปกรณ์ Google TV และ Android TV |
MediaImage
ออบเจ็กต์ MediaImage จะระบุ URL ของรูปภาพ ขนาดพิกเซล และข้อความสำหรับการช่วยเหลือพิเศษ ดังนี้
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
url |
string |
ใช่ | HTTPS URL ของรูปภาพที่เข้าถึงได้แบบสาธารณะ |
width |
integer |
ใช่ | ความกว้างของรูปภาพที่ไม่ได้แก้ไข (สูงสุด) ในหน่วยพิกเซล |
height |
integer |
ใช่ | ความสูงของรูปภาพที่ไม่มีการแก้ไข (สูงสุด) เป็นพิกเซล |
accessibility_text |
string |
ใช่ | ข้อความสำหรับการช่วยเหลือพิเศษ (alt) ที่อธิบายรูปภาพ |
ExternalEntityId
ออบเจ็กต์ ExternalEntityId จะจับคู่ผู้สมัครกับตัวระบุในแคตตาล็อกภายนอก ตั้งค่าช่องใดช่องหนึ่งต่อไปนี้ต่อรายการ และใส่รายการได้สูงสุด 1 รายการต่อประเภทตัวระบุในรายการ external_entity_ids ของผู้สมัคร
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
tms_root_id |
string |
หนึ่งใน | รหัสรูท TMS ของ Gracenote ระบุชื่อภาพยนตร์ รายการ หรือตอน |
tms_id |
string |
หนึ่งใน | รหัสตัวแปร TMS ของ Gracenote ระบุฉบับหรือรายการออกอากาศ |
data_feed_element_id |
string |
หนึ่งใน | รหัสเอนทิตีจากฟีดข้อมูลการดำเนินการเกี่ยวกับสื่อ ค่านี้ไม่เกี่ยวข้องกับกลุ่ม {recommendationsFeed} ของชื่อทรัพยากร |
RecommendationContext
ออบเจ็กต์ RecommendationContext จะอธิบายสาเหตุที่แนะนำผู้สมัครและระยะเวลาที่คำอธิบายนั้นมีผล
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
ไม่ | เหตุผลที่แนะนำผู้สมัคร (ดู RecommendationReason) |
validity_interval |
Interval |
ไม่ | กรอบเวลาที่บริบทนี้มีผล (ดู Interval) เช่น ผู้สมัครจะถือว่าเป็นผู้สมัครใหม่เป็นเวลาไม่กี่วันเท่านั้น หากไม่ได้ตั้งค่า บริบทจะมีผลตราบเท่าที่จัดเก็บผู้สมัครไว้ |
RecommendationReason
ออบเจ็กต์ RecommendationReason มีเหตุผล 1 ข้อ ตั้งค่าช่องใดช่องหนึ่งต่อไปนี้เพียงช่องเดียว
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
top_on_partner |
object |
หนึ่งใน | ผู้สมัครเป็นรายการอันดับต้นๆ ในบริการของคุณ มีช่องจำนวนเต็มบวก 1 ช่อง rank (เช่น {"rank": 1} สำหรับ "อันดับ 1 ในพาร์ทเนอร์") |
popular_on_partner |
object |
หนึ่งใน | ผู้สมัครเป็นที่นิยมในบริการของคุณ ส่งออบเจ็กต์ที่ว่างเปล่า ({}) |
new_on_partner |
object |
หนึ่งใน | ผู้สมัครเป็นผู้ใช้ใหม่ในบริการของคุณ ส่งออบเจ็กต์ที่ว่างเปล่า ({}) |
generic |
object |
หนึ่งใน | เหตุผลที่กำหนดเอง มีช่อง LocalizedString generic_reason ช่องเดียว (ดู LocalizedString) โดยแต่ละค่ามี Code Point ของ Unicode 1 ถึง 100 รายการ |
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 จะเข้ารหัสใน JSON เป็นสตริงที่มีจำนวนวินาทีตามด้วยคำต่อท้าย s เช่น "7200s" สำหรับ 2 ชั่วโมง อนุญาตให้ใช้เศษส่วนของวินาที เช่น "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} หมายถึงวันที่ 17 มกราคม 2025, {"year": 2025, "month": 1} หมายถึงเดือนมกราคม 2025 โดยไม่ระบุวัน และ {"year": 2025} หมายถึงวันที่ในปี 2025 โดยไม่ระบุเดือนและวัน
Interval
Interval คือกรอบเวลาแบบกึ่งเปิดที่เริ่มต้นที่ start_time (รวม) และสิ้นสุดที่ end_time (ไม่รวม) เวลา T อยู่ในช่วงเวลาที่ start_time <= T และ T < end_time
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
start_time |
string (Timestamp) |
ใช่ | จุดเริ่มต้นของกรอบเวลา (รวมวันที่เริ่มต้น) (ดู Timestamp) เช่น "2026-10-01T18:00:00Z" |
end_time |
string (Timestamp) |
ใช่ | จุดสิ้นสุดของกรอบเวลา (ไม่รวมวันที่สิ้นสุด) (ดู Timestamp) เช่น "2026-10-01T21:00:00Z" ต้องอยู่หลัง start_time |
ตัวอย่างคำขอ
ตัวอย่างต่อไปนี้จะแทนที่ตัวเลือกของฟีด in-en-cricket ของพาร์ทเนอร์ example-partner ด้วยตัวเลือก 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"
}
]
}
]
}'
ลักษณะการทำงานของการตอบกลับและการแทนที่
ส่วนนี้จะอธิบายการตอบกลับ HTTP ที่ replaceCandidates แสดงผล และวิธีที่การเรียกแต่ละครั้งอัปเดตผู้สมัครที่จัดเก็บไว้
ReplaceCandidatesResponse
หากคำขอสำเร็จ API จะแสดงผล HTTP 200 OK พร้อมเนื้อหา ReplaceCandidatesResponse ดังนี้
| ช่อง | ประเภท | คำอธิบาย |
|---|---|---|
replaced_candidates_count |
integer (int32) |
จำนวนผู้สมัครที่ถูกแทนที่ |
สำหรับตัวอย่างคำขอก่อนหน้า การตอบกลับจะเป็นดังนี้
{
"replaced_candidates_count": 3
}
ลักษณะการทำงานของการแทนที่
การทำความเข้าใจวิธีที่ replaceCandidates อัปเดตผู้สมัครที่จัดเก็บไว้เป็นสิ่งสำคัญสำหรับการออกแบบการผสานรวม ดังนี้
- การแทนที่ทั้งหมดต่อฟีด การเรียกแต่ละครั้งจะแทนที่รายการผู้สมัครที่จัดเก็บไว้ก่อนหน้านี้โดยสมบูรณ์สำหรับฟีดที่มีชื่อในเส้นทาง URL ส่งชุดผู้สมัครที่ใช้งานอยู่ทั้งหมดสำหรับฟีดนั้นเสมอ
- ฟีดอื่นๆ จะยังคงเหมือนเดิม ฟีดที่คุณไม่ได้ส่งผู้สมัครไปให้จะยังคงไม่เปลี่ยนแปลงจนกว่าคุณจะส่ง ตัวอย่างเช่น การแทนที่ผู้สมัครของฟีดหนึ่งจะไม่แก้ไขผู้สมัครที่จัดเก็บไว้สำหรับฟีดอื่นๆ และการแทนที่ผู้สมัครของ
{recommendationsFeed}-stagingจะไม่แก้ไข{recommendationsFeed} - การเรียก 1 ครั้งต่อฟีด หากต้องการอัปเดตฟีดหลายรายการ ให้เรียกใช้ 1 ครั้งต่อฟีด การเรียกใช้แต่ละครั้งจะแยกกัน หากการเรียกใช้หนึ่งล้มเหลว ฟีดอื่นๆ จะเก็บผู้สมัครใหม่ไว้ และคุณจะลองเรียกใช้ที่ล้มเหลวอีกครั้งเท่านั้น
- ส่งฟีดกิจกรรมที่ใช้งานอยู่อีกครั้งอย่างน้อยทุก 30 วัน แม้ว่าแคตตาล็อกสำหรับฟีดจะไม่มีการเปลี่ยนแปลง แต่ให้ส่งฟีดที่ใช้งานอยู่แต่ละรายการอีกครั้งอย่างน้อย 1 ครั้งทุกๆ 30 วัน (หรือตามกำหนดการรายวันหรือรายสัปดาห์ปกติที่มีความผันผวนแบบสุ่ม) เพื่อให้ผู้สมัครยังคงใช้งานอยู่และไม่หมดอายุ การตั้งค่า
availability_intervalsend_timeเป็นเวลาที่ห่างออกไปนานๆ ไม่ได้แทนที่การส่งซ้ำเป็นระยะๆ - การดำเนินการแบบอะตอม API จะใช้คำขอแบบอะตอมมิก หากผู้สมัครรายใดไม่ผ่านการตรวจสอบความถูกต้อง API จะปฏิเสธคำขอทั้งหมดและฟีดจะเก็บผู้สมัครรายก่อนหน้าไว้