โดยหลักแล้ว RTU มีไว้สำหรับข้อมูลอัปเดตที่คุณไม่สามารถคาดการณ์ได้ เช่น การปิดฉุกเฉิน หรือข้อมูลเมตาที่มีการเปลี่ยนแปลงเป็นระยะๆ (เช่น เวลาถึงโดยประมาณ) หากไม่จําเป็นต้องแสดงการเปลี่ยนแปลงทันที คุณสามารถใช้การส่งผ่านข้อมูลฟีดแบบเป็นกลุ่มแทนได้ การอัปเดตแบบเรียลไทม์จะประมวลผลไม่เกิน 5 นาที
การตั้งค่า Google Cloud Platform
- ตั้งค่าโปรเจ็กต์ GCP คุณต้องมีโปรเจ็กต์ GCP เพื่อเข้าถึง RTU API
- ให้สิทธิ์เข้าถึงผู้แก้ไข food-support@google.com
- แจ้งหมายเลขโปรเจ็กต์ GCP ของคุณให้ POC ของ Google ทราบ โปรเจ็กต์ GCP ต้องเชื่อมโยงกับบัญชีศูนย์การดำเนินการของคุณเพื่อให้การอัปเดตแบบเรียลไทม์ทำงานได้
- เปิดใช้ Maps Booking API:
- ใน GCP ให้ไปที่ API และบริการ > ไลบรารี
- ค้นหา "Google Maps Booking API"
- ค้นหาอินสแตนซ์ Sandbox ("Google Maps Booking API (Dev)") แล้วคลิกเปิดใช้
- ค้นหาอินสแตนซ์เวอร์ชันที่ใช้งานจริง ("Google Maps Booking API") แล้วคลิกเปิดใช้
- สร้างบัญชีบริการที่มีบทบาทผู้แก้ไขในโปรเจ็กต์ GCP โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อการตั้งค่าบัญชีบริการ
- ตรวจสอบว่าคุณอัปโหลดฟีดกลุ่มไปยังสภาพแวดล้อมที่คุณอัปเดตแบบเรียลไทม์
- สําหรับการตรวจสอบสิทธิ์ API เราขอแนะนําให้ติดตั้งไลบรารีไคลเอ็นต์ Google ในภาษาที่ต้องการ ใช้ "https://www.googleapis.com/auth/mapsbooking" เป็นขอบเขต OAuth ตัวอย่างโค้ดที่รวมไว้ด้านล่างใช้ไลบรารีเหล่านี้ มิเช่นนั้น คุณจะต้องจัดการการแลกเปลี่ยนโทเค็นด้วยตนเองตามที่อธิบายไว้ในการใช้ OAuth 2.0 เพื่อเข้าถึง Google API
การตั้งค่าบัญชีบริการ
คุณต้องมีบัญชีบริการเพื่อส่งคําขอ HTTPS ที่ตรวจสอบสิทธิ์ไปยัง Google API เช่น Real-time Updates API
วิธีตั้งค่าบัญชีบริการมีดังนี้
- เข้าถึงคอนโซล Google Cloud Platform
- บัญชีของคุณใน Actions Center ยังมีโปรเจ็กต์ Google Cloud ที่เชื่อมโยงอยู่ด้วย เลือกโปรเจ็กต์นั้น หากยังไม่ได้เลือก
- คลิกบัญชีบริการในเมนูด้านซ้าย
- คลิกสร้างบัญชีบริการ
- ป้อนชื่อบัญชีบริการ แล้วคลิกสร้าง
- ในส่วนเลือกบทบาท ให้เลือกโปรเจ็กต์ > ผู้แก้ไข
- คลิกต่อไป
- ไม่บังคับ: เพิ่มผู้ใช้เพื่อให้สิทธิ์เข้าถึงบัญชีบริการและคลิกเสร็จสิ้น
- คลิกเพิ่มเติม > สร้างคีย์สำหรับบัญชีบริการที่คุณเพิ่งสร้างขึ้น
- เลือก JSON เป็นรูปแบบ แล้วคลิกสร้าง
- หลังจากสร้างคู่คีย์สาธารณะ/ส่วนตัวใหม่แล้ว ให้ดาวน์โหลดคู่คีย์นั้นลงในเครื่อง
การทำงานกับ API
Real-time updates API รองรับการดำเนินการ 2 ประเภท ได้แก่ อัปเดตและลบ ระบบไม่รองรับการเพิ่มเอนทิตีใหม่ผ่าน Real-time Update API คุณสามารถส่งการอัปเดตแบบเรียลไทม์เป็นกลุ่มได้หากรวมการอัปเดตหลายรายการไว้ในคําขอ API รายการเดียว คุณอัปเดตแบบเป็นกลุ่มได้สูงสุด 1,000 รายการในการเรียก API ครั้งเดียว เราขอแนะนำให้ใช้แนวทางแบบทริกเกอร์เพื่อส่งการอัปเดตผ่าน RTU (กล่าวคือ เมื่อข้อมูลในระบบมีการเปลี่ยนแปลง ให้ทริกเกอร์การอัปเดตแบบเรียลไทม์ไปยัง Google) แทนแนวทางแบบความถี่ (กล่าวคือ สแกนระบบเพื่อหาการเปลี่ยนแปลงทุกๆ X นาที) หากเป็นไปได้
API การอัปเดตแบบเรียลไทม์จะทํางานทั้งในสภาพแวดล้อมแซนด์บ็อกซ์และเวอร์ชันที่ใช้งานจริง สภาพแวดล้อม Sandbox ใช้เพื่อทดสอบคำขอ API และสภาพแวดล้อมเวอร์ชันที่ใช้งานจริงเพื่ออัปเดตเนื้อหาที่ผู้ใช้การสั่งซื้อแบบครบวงจรเห็น
- แซนด์บ็อกซ์ -
partnerdev-mapsbooking.googleapis.com - เวอร์ชันที่ใช้งานจริง -
mapsbooking.googleapis.com
ปลายทาง
Real-time updates API จะแสดงปลายทาง 2 รายการเพื่อจัดการคําขออัปเดตพื้นที่โฆษณาขาเข้า ดังนี้
- อัปเดต -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - ลบ -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
พารามิเตอร์ PARTNER_ID จะอยู่ในศูนย์การดำเนินการในหน้าบัญชีและผู้ใช้ ดังที่แสดงในภาพหน้าจอด้านล่าง
โดยใช้ 10000001 เป็นค่าของ PARTNER_ID จากตัวอย่างภาพหน้าจอด้านบน URL แบบเต็มสำหรับการส่งคำขอ API ในแซนด์บ็อกซ์และเวอร์ชันที่ใช้งานจริงจะมีลักษณะดังตัวอย่างด้านล่าง
การอัปเดตแซนด์บ็อกซ์
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
ข้อมูลอัปเดตเวอร์ชันที่ใช้งานจริง
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Production DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
การอัปเดตเอนทิตี
หากต้องการอัปเดตเอนทิตีในคลังสินค้า ให้ใช้ปลายทาง update ในคำขอ HTTP POST คําขอ POST แต่ละรายการต้องมีพารามิเตอร์ 10000001 พร้อมกับเพย์โหลด JSON ที่มีเอนทิตีที่คุณต้องการอัปเดต
หมายเหตุ: ตรวจสอบว่าฟีดข้อมูลรายวันมีการเปลี่ยนแปลงที่ส่งผ่าน Real-time Updates API ด้วย มิฉะนั้นข้อมูลของคุณอาจล้าสมัยหรือไม่ถูกต้อง
เพย์โหลดคำขออัปเดต
เนื้อความของคำขอคือออบเจ็กต์ JSON ที่มีรายการระเบียน แต่ละระเบียนจะสอดคล้องกับเอนทิตีที่อัปเดต ซึ่งประกอบด้วยช่อง proto_record และ generation_timestamp ที่ระบุเวลาของการอัปเดตเอนทิตี
{
"records": [
{
"proto_record":"ServiceData PROTO",
"generation_timestamp":"UPDATE_TIMESTAMP"
}
]
}ServiceData PROTO: การแปลภาษา Proto หรือ JSON ของเอนทิตี ServiceData ที่คุณอัปเดตUPDATE_TIMESTAMP: อย่าลืมใส่การประทับเวลาที่สร้างเอนทิตีในระบบแบ็กเอนด์ หากไม่ได้ระบุข้อมูลในช่องนี้ ระบบจะตั้งค่าเป็นเวลาที่ Google ได้รับคำขอ เมื่ออัปเดตเอนทิตีผ่านคำขอbatchPushระบบจะใช้ช่องgeneration_timestampสำหรับการกำหนดเวอร์ชันของเอนทิตี ดูรูปแบบที่คาดไว้ของค่าเวลาในสคีมาสินค้าคงคลังเชิงสัมพันธ์
- เนื้อหาของเพย์โหลดต้องมีขนาดไม่เกิน 5 MB
- นำเว้นวรรคออกเพื่อลดขนาด
- อัปเดตในคำขอ
batchPushรายการมีได้สูงสุด 1,000 รายการ
ตัวอย่าง
อัปเดตเวลาถึงโดยประมาณ
สมมติว่าคุณต้องอัปเดตเวลาถึงโดยประมาณของบริการนำส่งจาก 30-60 เป็น 60-90 นาทีอย่างเร่งด่วน การอัปเดตของคุณต้องมี JSON สำหรับเอนทิตีบริการทั้งหมด
ลองพิจารณาเอนทิตีบริการที่มีหน้าตาดังต่อไปนี้
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
การอัปเดตแบบเรียลไทม์ของคุณผ่าน HTTP POST มีดังนี้ (ระบบจะแสดงเนื้อหาคำขออย่างสวยงามเพื่อให้อ่านง่าย)
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
อัปเดตเอนทิตีหลายรายการ
หากต้องการอัปเดตเอนทิตีร้านอาหารหลายรายการในการเรียก API ครั้งเดียว ให้ใส่ระเบียนหลายรายการในช่อง proto_record ของเนื้อหาคำขอ
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
ลบเอนทิตี
หากต้องการลบเอนทิตีออกจากคลัง ให้ใช้ปลายทาง DELETE ในคำขอ HTTP POST คำขอ POST แต่ละรายการต้องมีพารามิเตอร์ PARTNER_ID พร้อมกับเพย์โหลด JSON ซึ่งมีตัวระบุของเอนทิตีที่คุณต้องการลบ
หมายเหตุ: ตรวจสอบว่าฟีดข้อมูลรายวันมีการเปลี่ยนแปลงที่ส่งผ่าน Real-time Update API ด้วย มิเช่นนั้น การนำเข้ากลุ่มแบบรายวันจะเขียนทับการเปลี่ยนแปลงแบบเรียลไทม์
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
การเพิ่มเอนทิตี
อย่าใช้การอัปเดตแบบเรียลไทม์เพื่อเพิ่มเอนทิตีใหม่ เนื่องจากอาจส่งผลให้ข้อมูลไม่สอดคล้องกัน แต่ให้ใช้ฟีดกลุ่มแทน
การตรวจสอบและรหัสการตอบกลับของ API
การตรวจสอบมี 2 ประเภทที่ดำเนินการกับการเรียก API การอัปเดตแบบเรียลไทม์ ได้แก่
- ระดับคำขอ - การตรวจสอบเหล่านี้จะตรวจสอบว่าเพย์โหลดเป็นไปตามสคีมา และ
proto_recordทุกรายการมีช่องidและtypeการตรวจสอบเหล่านี้เป็นแบบซิงค์และระบบจะแสดงผลลัพธ์ในส่วนเนื้อหาการตอบกลับของ API รหัสการตอบกลับ 200 และเนื้อหา JSON ว่าง{}หมายความว่าการตรวจสอบเหล่านี้ผ่านและระบบได้จัดคิวเอนทิตีในคำขอนั้นเพื่อประมวลผล รหัสคำตอบที่ไม่ใช่ 200 หมายความว่าการตรวจสอบอย่างน้อย 1 รายการไม่สำเร็จและคำขอทั้งหมดถูกปฏิเสธ (รวมถึงเอนทิตีทั้งหมดในเพย์โหลด) ตัวอย่างเช่น หากproto_recordไม่มี@typeระบบจะแสดงการตอบกลับข้อผิดพลาดต่อไปนี้
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- ระดับเอนทิตี: ระบบจะตรวจสอบเอนทิตีแต่ละรายการ (proto_record) ในเพย์โหลดเทียบกับสคีมา ระบบจะไม่รายงานปัญหาที่พบในระยะการตรวจสอบนี้ในการตอบกลับของ API โดยจะรายงานในหน้าแดชบอร์ดการรายงาน RTU ของศูนย์การดำเนินการเท่านั้น
หมายเหตุ: โค้ดตอบกลับ 200 ไม่ได้หมายความว่าระบบนำเข้าเอนทิตีทั้งหมดเรียบร้อยแล้ว
โควต้า API
การอัปเดต API แบบเรียลไทม์มีโควต้า 1,500 คำขอทุก 60 วินาที หรือ 25 คำขอต่อวินาทีโดยเฉลี่ย เมื่อใช้โควต้าเกิน Google จะตอบกลับด้วยข้อความแสดงข้อผิดพลาดต่อไปนี้
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}วิธีแก้ปัญหานี้คือลองเรียกใช้อีกครั้งเป็นระยะๆ ที่นานขึ้นเรื่อยๆ จนกว่าจะสำเร็จ หากคุณใช้โควต้าจนหมดเป็นประจำ ให้พิจารณารวมเอนทิตีเพิ่มเติมในคําขอ API 1 รายการ คุณรวมเอนทิตีได้สูงสุด 1,000 รายการในการเรียก API ครั้งเดียว
การอัปเดตแบบเรียลไทม์เกี่ยวกับเวลาในการประมวลผล
ระบบจะประมวลผลเอนทิตีที่อัปเดตผ่านการอัปเดตแบบเรียลไทม์ใน 5 นาที