ผสานรวมวิดีโอแนะนำโดยใช้ REST API

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 ให้ทำตามขั้นตอนต่อไปนี้

  1. สร้างบัญชี Google Workspace ทำตามวิธีการในหน้าการสนับสนุนของ Google Workspace เพื่อตั้งค่าบัญชีสำหรับองค์กร
  2. ค้นหารหัสลูกค้า Google Workspace ค้นหารหัสลูกค้า (เช่น C0123abcd) โดยทำตามขั้นตอนในหัวข้อค้นหารหัสลูกค้า
  3. สร้างโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และบัญชีบริการ ในคอนโซล Google Cloud ภายใต้องค์กร Google Workspace ให้สร้างโปรเจ็กต์ Google Cloud และบัญชีบริการสำหรับเซิร์ฟเวอร์แบ็กเอนด์
  4. ขอการเริ่มต้นใช้งานสำหรับพาร์ทเนอร์ ระบุรหัสลูกค้า Google Workspace, รหัสโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และอีเมลบัญชีบริการ (หรือรหัสตัวเลขที่ไม่ซ้ำกัน) ให้กับตัวแทนพาร์ทเนอร์ Google TV พร้อมกับประเทศหรือภูมิภาคและภาษาของอุปกรณ์ทีวีที่คุณต้องการส่งผู้สมัครไปให้ ตัวแทนพาร์ทเนอร์ Google TV จะแจ้งให้คุณทราบหลังจากแมปองค์กร โปรเจ็กต์ และบัญชีบริการ Google Workspace กับรหัสพาร์ทเนอร์ และให้รหัสฟีดวิดีโอแนะนำที่สร้างขึ้นสำหรับพาร์ทเนอร์แก่คุณ
  5. เปิดใช้ API และสร้างข้อมูลเข้าสู่ระบบ หลังจากตัวแทนยืนยันว่าได้รับสิทธิ์เข้าถึงแล้ว ให้เปิดใช้ Google TV Video Discovery API (tvvideodiscovery.googleapis.com) ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google และสร้างข้อมูลเข้าสู่ระบบ OAuth 2.0 สำหรับบัญชีบริการ
  6. ตรวจสอบสิทธิ์คำขอ ขอโทเค็นเพื่อการเข้าถึง 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_intervals end_time เป็นเวลาที่ห่างออกไปนานๆ ไม่ได้แทนที่การส่งซ้ำเป็นระยะๆ
  • การดำเนินการแบบอะตอม API จะใช้คำขอแบบอะตอมมิก หากผู้สมัครรายใดไม่ผ่านการตรวจสอบความถูกต้อง API จะปฏิเสธคำขอทั้งหมดและฟีดจะเก็บผู้สมัครรายก่อนหน้าไว้