RTU มีไว้เพื่ออัปเดตที่คุณคาดการณ์ไม่ได้เป็นหลัก เช่น การปิดฉุกเฉิน หรือข้อมูลเมตาที่มีการเปลี่ยนแปลงเป็นระยะๆ (เช่น เวลาถึงโดยประมาณ) หากไม่จำเป็นต้องแสดงการเปลี่ยนแปลงโดยทันที ให้ใช้การนำเข้าฟีดแบบกลุ่มแทน ระบบจะประมวลผลการอัปเดตแบบเรียลไทม์ไม่เกิน 5 นาที
การตั้งค่า Google Cloud Platform
- ตั้งค่าโปรเจ็กต์ GCP ต้องมีโปรเจ็กต์ GCP เพื่อเข้าถึง RTU API
- ให้สิทธิ์เข้าถึงแก่ผู้แก้ไข food-support@google.com
- แจ้งหมายเลขโปรเจ็กต์ GCP ของ Google POC โปรเจ็กต์ GCP ของคุณต้องเชื่อมโยงกับบัญชี Actions Center เพื่อให้การอัปเดตแบบเรียลไทม์ทำงานได้
- เปิดใช้ API การจอง Maps:
- ใน GCP ให้ไปที่ API และ บริการ > คลัง
- ค้นหา "Google Maps Booking API"
วันที่ - ค้นหาอินสแตนซ์แซนด์บ็อกซ์ ("Google Maps Booking API (Dev)") แล้วคลิกเปิดใช้
- ค้นหาอินสแตนซ์เวอร์ชันที่ใช้งานจริง ("การจอง API ของ Google Maps") แล้วคลิกเปิดใช้
- สร้างบัญชีบริการที่มีบทบาทผู้แก้ไขในโปรเจ็กต์ GCP โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อการสร้างบัญชีบริการ
- โปรดตรวจสอบว่าคุณอัปโหลดฟีดแบบกลุ่มไปยังสภาพแวดล้อมที่ใช้การอัปเดตแบบเรียลไทม์
- สำหรับการตรวจสอบสิทธิ์ API เราขอแนะนำให้ติดตั้งไลบรารีของไคลเอ็นต์ Google ในภาษาที่คุณต้องการ ใช้ “https://www.googleapis.com/auth/mapsbooking” เป็นขอบเขต OAuth ตัวอย่างโค้ดที่รวมอยู่ด้านล่างใช้ไลบรารีเหล่านี้ ไม่เช่นนั้น คุณจะต้องจัดการการแลกเปลี่ยนโทเค็นด้วยตนเองตามที่อธิบายไว้ในการใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs
การตั้งค่าบัญชีบริการ
คุณต้องมีบัญชีบริการเพื่อส่งคำขอ HTTPS ที่ตรวจสอบสิทธิ์แล้วไปยัง Google API เช่น API การอัปเดตแบบเรียลไทม์
โดยทำตามขั้นตอนต่อไปนี้
- เข้าถึงคอนโซล Google Cloud Platform
- บัญชีของคุณใน Actions Center มีโปรเจ็กต์ Google Cloud ที่เชื่อมโยงกับบัญชีดังกล่าวด้วย เลือกโปรเจ็กต์ดังกล่าว หากยังไม่ได้เลือก
- คลิกบัญชีบริการในเมนูด้านซ้าย
- คลิกสร้างบัญชีบริการ
- ป้อนชื่อบัญชีบริการแล้วคลิกสร้าง
- สำหรับเลือกบทบาท ให้เลือกโปรเจ็กต์ > เอดิเตอร์
- คลิกต่อไป
- ไม่บังคับ: เพิ่มผู้ใช้เพื่อให้สิทธิ์เข้าถึงบัญชีบริการ แล้วคลิกเสร็จสิ้น
- คลิกเพิ่มเติม > สร้างคีย์สำหรับบัญชีบริการที่คุณเพิ่งสร้าง
- เลือกรูปแบบเป็น JSON แล้วคลิกสร้าง
- หลังจากสร้างคู่คีย์สาธารณะ/ส่วนตัวใหม่แล้ว ให้ดาวน์โหลดลงในเครื่อง
การทำงานกับ API
API การอัปเดตแบบเรียลไทม์สนับสนุนการดำเนินการ 2 ประเภท ได้แก่ อัปเดตและลบ ไม่รองรับการเพิ่มเอนทิตีใหม่ผ่าน API การอัปเดตแบบเรียลไทม์ คุณสามารถรวมการอัปเดตแบบเรียลไทม์เป็นกลุ่มได้หากคุณรวมการอัปเดตหลายรายการไว้ในคำขอ API เดียว คุณจัดกลุ่มการอัปเดตได้สูงสุด 1,000 รายการในการเรียก API ครั้งเดียว เราขอแนะนำให้ใช้วิธีการที่อิงตามทริกเกอร์เพื่อส่งการอัปเดตผ่าน RTU (เช่น เมื่อมีการเปลี่ยนแปลงข้อมูลในระบบ ระบบจะทริกเกอร์การอัปเดตแบบเรียลไทม์ไปยัง Google) แทนวิธีการที่อิงตามความถี่ (เช่น ทุกๆ X นาทีจะสแกนหาการเปลี่ยนแปลงในระบบ) หากเป็นไปได้
API การอัปเดตแบบเรียลไทม์จะทำงานทั้งในสภาพแวดล้อมแซนด์บ็อกซ์และเวอร์ชันที่ใช้งานจริง สภาพแวดล้อมแซนด์บ็อกซ์ใช้เพื่อทดสอบคำขอ API และสภาพแวดล้อมการใช้งานจริงเพื่ออัปเดตเนื้อหาที่แสดงต่อผู้ใช้ปลายทางถึงปลายทาง
- แซนด์บ็อกซ์ -
partnerdev-mapsbooking.googleapis.com
- การผลิต -
mapsbooking.googleapis.com
ปลายทาง
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 จะอยู่ในศูนย์การดำเนินการ ในหน้าบัญชีและผู้ใช้ ดังที่แสดงในภาพหน้าจอด้านล่าง
![รหัสพาร์ทเนอร์ในพอร์ทัลพาร์ทเนอร์](https://developers-dot-devsite-v2-prod.appspot.com/static/actions-center/verticals/ordering/images/rtu-partnerid.png?authuser=5&hl=th)
ใช้ 10000001 เป็นค่าของ PARTNER_ID เป็นตัวอย่างจากภาพหน้าจอด้านบน URL ที่สมบูรณ์สำหรับการส่งคำขอ API ในแซนด์บ็อกซ์และเวอร์ชันที่ใช้งานจริงจะมีลักษณะเหมือนในตัวอย่างด้านล่าง
การอัปเดตแซนด์บ็อกซ์
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
การลบแซนด์บ็อกซ์
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
ลบเวอร์ชันที่ใช้งานจริง
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
การอัปเดตเอนทิตี
หากต้องการอัปเดตเอนทิตีในพื้นที่โฆษณา ให้ใช้ปลายทาง update ในคำขอ HTTP POST คำขอ POST แต่ละรายการต้องมีพารามิเตอร์ 10000001 พร้อมด้วยเพย์โหลด JSON ที่มีเอนทิตีที่คุณต้องการอัปเดต
หมายเหตุ: ตรวจสอบว่าฟีดข้อมูลรายวันมีการเปลี่ยนแปลงที่ส่งผ่าน API การอัปเดตแบบเรียลไทม์ด้วย มิฉะนั้น ข้อมูลอาจเก่าเกินไปหรือไม่ทันสมัย
อัปเดตเพย์โหลดคำขอ
เนื้อหาของคำขอเป็นออบเจ็กต์ JSON ที่มีรายการระเบียน แต่ละระเบียนจะสอดคล้องกับเอนทิตีที่อัปเดต ซึ่งประกอบด้วยช่อง proto_record
และ generation_timestamp
ที่ระบุเวลาของการอัปเดตเอนทิตี
{ "records": [ { "proto_record":"ServiceData PROTO", "generation_timestamp":"UPDATE_TIMESTAMP" } ] }
ServiceData PROTO
: การแปล Pro หรือ 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" }] }
ลบเอนทิตี
หากต้องการลบเอนทิตีออกจากพื้นที่โฆษณา ให้ใช้ปลายทางลบในคำขอ HTTP POST คำขอ POST แต่ละรายการต้องมีพารามิเตอร์ PARTNER_ID พร้อมด้วยเพย์โหลด JSON ซึ่งมีตัวระบุของเอนทิตีที่คุณต้องการลบ
หมายเหตุ: ตรวจสอบว่าฟีดข้อมูลรายวันมีการเปลี่ยนแปลงที่ส่งผ่าน 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
การตรวจสอบในการเรียก API การอัปเดตแบบเรียลไทม์มี 2 ประเภทดังนี้
- ระดับคำขอ - การตรวจสอบเหล่านี้จะตรวจสอบว่าเพย์โหลดเป็นไปตามสคีมา และทุกๆ
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." } ] }
- ระดับเอนทิตี: เอนทิตีแต่ละรายการ (protocol_record) ในเพย์โหลดจะได้รับการตรวจสอบเทียบกับสคีมา ปัญหาที่พบในขั้นตอนการตรวจสอบนี้จะไม่รายงานในการตอบกลับของ API ซึ่งจะรายงานในหน้าแดชบอร์ดการรายงาน RTU ของ Actions Center เท่านั้น
หมายเหตุ: โค้ดตอบกลับ 200 ไม่ได้หมายความว่านำเข้าเอนทิตีทั้งหมดเรียบร้อยแล้ว
โควต้า API
การอัปเดต API แบบเรียลไทม์มีโควต้าคำขอ 1,500 รายการทุกๆ 60 วินาที หรือ 25 คำขอต่อวินาทีโดยเฉลี่ย เมื่อเกินโควต้าแล้ว Google จะตอบกลับด้วยข้อความแสดงข้อผิดพลาดต่อไปนี้
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
หากต้องการแก้ไขปัญหานี้ ให้ลองโทรอีกครั้งเป็นช่วงเวลาที่เพิ่มขึ้นเรื่อยๆ จนกว่าจะสำเร็จ หากคุณใช้โควต้าจนหมดเป็นประจำ ให้พิจารณารวมเอนทิตีมากขึ้นในคำขอ API เดียว คุณรวมเอนทิตีในการเรียก API ได้สูงสุด 1,000 รายการ
เวลาประมวลผลการอัปเดตแบบเรียลไทม์
ระบบจะประมวลผลเอนทิตีที่อัปเดตผ่านการอัปเดตแบบเรียลไทม์ใน 5 นาที