เมื่อคุณดึงข้อมูลการเดินทาง แบ็กเอนด์จะได้รับเพย์โหลด JSON ที่แสดงรายละเอียดความคืบหน้าของการเดินทางของคนขับ แยกวิเคราะห์เพย์โหลดเหล่านี้เพื่อตรวจสอบการเดินทาง อัปเดตระบบการจัดส่ง และตีความสถานะการเดินทางปัจจุบันเพื่อกำหนดขั้นตอนถัดไปสำหรับคนขับขณะที่เดินทางหรือเมื่อการเดินทางสิ้นสุดลง
อ่านเพย์โหลดข้อมูล
Google Maps หรือ Waze จะส่งเพย์โหลดข้อมูลการเดินทางไปยังเซิร์ฟเวอร์ Navigation Connect เมื่อคนขับเริ่มการนำทาง โดยจะส่งเป็นระยะๆ ตลอดเส้นทาง (ทุก 60 วินาทีโดยค่าเริ่มต้น) และเมื่อคนขับถึงจุดหมาย ข้อความ JSON แต่ละรายการจะมีข้อมูลการเดินทางที่เกี่ยวข้อง ซึ่งรวมถึงพิกัดที่สแนปกับถนนของผู้ขับขี่ ระยะทางที่เดินทาง และเวลาถึงโดยประมาณ (ETA) เนื่องจากข้อมูลอัปเดตเหล่านี้แสดงเส้นทางที่คนขับกำลังใช้งานอยู่แบบเรียลไทม์ จึงอาจแตกต่างจากเส้นทางที่ระบบแบ็กเอนด์คำนวณไว้ล่วงหน้า (ดูคำถามที่พบบ่อย)
ตัวอย่างโค้ดต่อไปนี้แสดงเพย์โหลดข้อมูลการเดินทางเมื่อคนขับเริ่มการนำทางสำหรับการเดินทางจาก King's Cross ไปยัง Central St. Giles
{
"name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
"state": "ENROUTE",
"execution": {
"origin": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
}
},
"destination": {
"point": {
"latitude": 51.515598,
"longitude": -0.1277623
}
},
"location": {
"point": {
"latitude": 51.5333329,
"longitude": -0.1265845
},
"sourceTime": "2025-05-30T12:37:26Z",
"serverTime": "2025-05-30T12:37:26.221069Z"
},
"traveledDuration": "0s",
"remainingDuration": "990s",
"traveledDistanceMeters": 0,
"remainingDistanceMeters": 2879,
"stopAddedInRoute": false
}
}
ตรวจสอบสถานะการเดินทางที่ดำเนินอยู่
หากต้องการยืนยันว่าเริ่มต้นสำเร็จและติดตามความคืบหน้า ให้ประเมินช่อง state ในเพย์โหลดทุกรายการ
| สถานะ | คำอธิบาย |
|---|---|
NEW |
ระบบสร้างการเดินทางแล้ว แต่คนขับยังไม่ได้เริ่มการนำทาง |
ENROUTE |
คนขับกำลังนำทางไปยังจุดหมาย ใช้สถานะนี้เพื่อยืนยันว่าการเดินทางได้รับการตรวจสอบสิทธิ์และเริ่มต้นเรียบร้อยแล้ว |
จัดการจุดแวะพักที่เพิ่ม
คนขับสามารถเพิ่มจุดแวะพักในเส้นทางระหว่างการนำทางได้ หากมี Navigation Connect จะตั้งค่าช่อง execution.stopAddedInRoute เป็น true ในเพย์โหลดข้อมูล JSON Navigation Connect API จะติดตามคนขับไปยังจุดหมายเดิมต่อไป เมตริกต่างๆ เช่น เวลาถึงโดยประมาณ (ETA) ระยะทาง และระยะเวลาจะเพิ่มขึ้นตามจุดแวะพักที่เพิ่มเข้ามา
ลักษณะการทำงานสำหรับการเพิ่มจุดแวะพักจะขึ้นอยู่กับแอปการนำทางและตรงกับฟังก์ชันการทำงานมาตรฐานของแอป ดังนี้
- Google Maps: คนขับสามารถเพิ่มจุดแวะพักหลายจุดในเส้นทางได้
- Waze: คนขับเพิ่มจุดแวะพักได้เพียงจุดเดียว หากผู้ขับพยายามเพิ่มจุดแวะพักอีกจุดหนึ่ง Waze จะแจ้งให้เริ่มเซสชันการนำทางใหม่แทนที่จะเพิ่มจุดแวะพักลงในเส้นทางปัจจุบัน
คุณไม่จำเป็นต้องปรับอินพุตแบ็กเอนด์เพื่อรองรับฟีเจอร์นี้
แก้ปัญหาการตรวจสอบสิทธิ์และการเริ่มต้น
หากไม่ได้รับสถานะ ENROUTE แสดงว่าอาจเกิดข้อผิดพลาดในการตรวจสอบสิทธิ์ สาเหตุที่พบบ่อย ได้แก่ พารามิเตอร์ API ที่สะกดผิดหรือโทเค็นการเดินทางที่หมดอายุ ตรวจสอบเวลาหมดอายุของโทเค็นในการตอบกลับ CreateTrip ครั้งแรก
หากสถานะไม่เปลี่ยนจาก NEW เป็น ENROUTE แสดงว่าอุปกรณ์ของคนขับอาจป้องกันการตรวจสอบสิทธิ์ Navigation Connect จะไม่ส่งข้อความแสดงข้อผิดพลาดสำหรับกรณีเหล่านี้ ยืนยันสิ่งต่อไปนี้
- คนขับติดตั้ง Waze เวอร์ชัน 5.15.5 ขึ้นไป หรือ Google Maps เวอร์ชัน 26.14 ขึ้นไป
- คนขับไม่ได้ใช้ Android Auto หรือ Apple CarPlay
- คนขับมีการเชื่อมต่ออินเทอร์เน็ตที่ใช้งานได้
จัดการข้อมูลเส้นทางที่เหลือ
หากคุณเปิดใช้การรายงานเส้นทางที่เหลือระหว่างการสร้างการเดินทาง แบ็กเอนด์จะได้รับเส้นประกอบของเส้นทางที่เหลือและสภาพการจราจรแบบเรียลไทม์จากตำแหน่งปัจจุบันของคนขับไปยังจุดหมายปลายทางสุดท้าย คนขับต้องใช้ Waze เวอร์ชัน 5.20.0.2 ขึ้นไปบน Android, เวอร์ชัน 5.20.0.1 ขึ้นไปบน iOS หรือ Google Maps สำหรับ Android เวอร์ชัน 26.27 ขึ้นไป
คุณสามารถนำเข้าและประมวลผลข้อมูลนี้เพื่อขับเคลื่อนฟีเจอร์ต่างๆ ในแอปพลิเคชันได้ เช่น ตัวอย่างต่อไปนี้
- ขับเคลื่อนแผนที่การติดตามแบบเรียลไทม์: แสดงผลเส้นประกอบของเส้นทางที่เหลือบนแผนที่บนเว็บหรืออุปกรณ์เคลื่อนที่ที่แสดงต่อลูกค้าเพื่อให้เห็นภาพการเดินทางของคนขับ
- เพิ่มความแม่นยำของ ETA: รวมเส้นประกอบที่ปรับให้สอดคล้องกับถนนและความเร็วในช่วงการจราจรเพื่อปรับปรุงการคาดการณ์การมาถึงของการจัดส่งหรือโลจิสติกส์ภายใน
- วิเคราะห์การปฏิบัติตามเส้นทาง: เปรียบเทียบเรขาคณิตของเส้นทางที่เหลือกับเส้นทางการจัดส่งที่คาดไว้เพื่อประเมินการปฏิบัติตามเส้นทางของคนขับ (ดูรายละเอียดเกี่ยวกับสาเหตุที่เส้นทางแบบเรียลไทม์และเส้นทางที่คำนวณไว้ล่วงหน้าอาจแตกต่างกันได้ที่คำถามที่พบบ่อย)
Navigation Connect จะแสดงรายละเอียดเส้นทางที่เหลือในช่อง execution.remainingRoute ไม่ว่าคุณจะส่งคำขอ GetTrip หรือรับการอัปเดตที่อิงตามเหตุการณ์โดยใช้ Google Cloud Pub/Sub อย่างไรก็ตาม วิธีที่เพย์โหลดจัดรูปแบบและโครงสร้างข้อมูลนี้จะขึ้นอยู่กับวิธีการดึงข้อมูลที่คุณใช้
GetTrip วิธี
เมื่อคุณเรียกใช้เมธอด GetTrip รูปแบบการตอบกลับสำหรับเส้นประกอบจะขึ้นอยู่กับพารามิเตอร์ routePolylineFormat ที่คุณระบุไว้ในคำขอ ดูข้อมูลเพิ่มเติมได้ที่ปรับแต่งรูปแบบเส้นประกอบ
สำหรับรูปแบบเส้นประกอบทั้งหมด Navigation Connect จะแสดงผลการจราจรเป็นรายการออบเจ็กต์ SpeedReadingInterval แยกต่างหากในฟิลด์ execution.remainingRoute.trafficInformation ออบเจ็กต์เหล่านี้จะแมปหมวดหมู่การจราจรกับดัชนีเส้นประกอบโดยใช้ค่าต่อไปนี้
startPolylinePointIndex: ดัชนีเริ่มต้นของช่วงการจราจรบนเส้นประกอบendPolylinePointIndex: ดัชนีสิ้นสุดของช่วงการเข้าชมspeed: หมวดหมู่การเข้าชมสำหรับกลุ่มนี้:NORMAL,SLOWหรือTRAFFIC_JAM
การอัปเดต Google Cloud Pub/Sub
เมื่อคุณดึงข้อมูลการเดินทางด้วย Pub/Sub การอัปเดตจะแสดงข้อมูลเส้นทางที่เหลือใน GeoJSON FeatureCollection แบบรวมในช่อง execution.remainingRoute เสมอ
รูปแบบนี้จะรวมเรขาคณิตของเส้นประกอบเข้ากับความเร็วของการจราจรโดยตรง จึงไม่จำเป็นต้องแมปดัชนีด้วยตนเอง
ดูตัวอย่างเพย์โหลด Pub/Sub
ตัวอย่างโค้ดต่อไปนี้แสดงโครงสร้าง GeoJSON ที่แสดงผลในฟิลด์ execution.remainingRoute ภายในออบเจ็กต์ updatedTrip ของข้อความ Pub/Sub
{ "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.3934, 37.7955], [-122.4010, 37.7980] ] }, "properties": { "speed": "SLOW" } }, { "type": "Feature", "geometry": { "type": "LineString", "coordinates": [ [-122.4010, 37.7980], [-122.4058, 37.8025], [-122.4187, 37.8021] ] }, "properties": { "speed": "NORMAL" } } ] }
เพิ่มประสิทธิภาพขนาดเพย์โหลด
เนื่องจากอาร์เรย์พิกัดมีขนาดใหญ่ การรวมข้อมูลเส้นทางที่เหลือไว้ในข้อความ Pub/Sub จึงอาจเพิ่มขนาดเพย์โหลดได้อย่างมาก (สูงสุด 13-14 KB ต่อข้อความ) หากคุณได้รับการอัปเดตที่มีความถี่สูง ปริมาณนี้อาจเพิ่มภาระงานในการประมวลผลแบ็กเอนด์และค่าใช้จ่ายในการใช้งาน
หากต้องการเพิ่มประสิทธิภาพสตรีม ให้ใช้พารามิเตอร์ pubsubFieldMask ในออบเจ็กต์ TripConfig ระหว่างการสร้างการเดินทางเพื่อยกเว้นช่องที่มีข้อมูลจำนวนมาก โปรดดูรายละเอียดที่หัวข้อการกำหนดค่าที่ไม่บังคับ
จัดการการออกนอกเส้นทาง (Waze เท่านั้น)
คนขับต้องใช้ Waze เวอร์ชัน 5.22 ขึ้นไป
หากคุณเปิดใช้การรายงานการออกนอกเส้นทางระหว่างการสร้างการเดินทาง เมื่อคนขับออกนอกเส้นทาง API จะแสดงผลข้อมูลเมตาการออกนอกเส้นทาง คุณสามารถเข้าถึงข้อมูลนี้ได้ด้วยวิธีต่อไปนี้
- ตามต้องการ: เรียกใช้เมธอด
GetTripเซิร์ฟเวอร์จะคงสถานะการเบี่ยงเบนที่ทราบล่าสุดไว้ - แบบเรียลไทม์: สมัครใช้บริการ Google Cloud Pub/Sub บริการจะเผยแพร่การอัปเดตความคลาดเคลื่อนโดยใช้เหตุการณ์
updated_tripที่มีอยู่ภายใน 5 วินาทีหลังจากการตรวจจับ
อ่านเพย์โหลดความเบี่ยงเบน
ออบเจ็กต์ last_route_deviation จะให้ข้อมูลเมตาต่อไปนี้เพื่อช่วยคุณวิเคราะห์เหตุการณ์
| ช่อง | ประเภท | คำอธิบาย |
|---|---|---|
location |
LatLng |
พิกัดละติจูดและลองจิจูดที่อุปกรณ์ไคลเอ็นต์บันทึกค่าเบี่ยงเบน |
source |
TriggerSource |
เหตุผลที่เบี่ยงเบน ใช้ข้อมูลนี้เพื่อพิจารณาว่าคนขับดำเนินการที่ไม่คาดคิดหรือปฏิบัติตามคำแนะนำของระบบหรือไม่
|
client_timestamp |
Timestamp |
เวลาที่อุปกรณ์ไคลเอ็นต์ตรวจพบความคลาดเคลื่อน |
server_timestamp |
Timestamp |
เวลาที่เซิร์ฟเวอร์ประมวลผลการอัปเดตความคลาดเคลื่อน |
จัดการสถานะสิ้นสุดการเดินทาง
เมื่อคนขับถึงจุดหมายหรือหยุดการนำทาง เพย์โหลดจะแสดงผลสถานะสิ้นสุดอย่างใดอย่างหนึ่งต่อไปนี้ ใช้สถานะเหล่านี้เพื่อทริกเกอร์ขั้นตอนถัดไปที่เหมาะสมในแอป
| สถานะ | คำอธิบาย | การดำเนินการที่แนะนำ |
|---|---|---|
ARRIVED |
คนขับถึงจุดหมายแล้ว | ดูremainingDistanceMeters หากคนขับจอดรถในบริเวณใกล้เคียงแต่ไม่ได้จอดที่พิกัดที่แน่นอน ให้พิจารณาแสดงเส้นทางเดินเท้าในแอป |
SUSPENDED |
คนขับออกจากระบบนำทางแบบเลี้ยวต่อเลี้ยวด้วยตนเองก่อนที่จะถึงจุดหมาย เนื่องจาก Google Maps หรือ Waze ไม่ได้นำคนขับกลับไปยังแอปของคุณโดยอัตโนมัติเมื่อออกจากเซสชันก่อนเวลา คนขับจึงต้องแตะปุ่มย้อนกลับด้วยตนเอง |
หากต้องการช่วยให้คนขับเดินทางถึงจุดหมาย ให้เปรียบเทียบ execution.location กับจุดหมาย หากยังเหลือระยะทาง ให้แสดงปุ่มหรือลิงก์เพื่อเดินทางต่อหรือเปลี่ยนเป็นโหมดเดินเท้า |
FAILED |
ข้อผิดพลาดทางเทคนิคขัดจังหวะการเชื่อมต่อ ซึ่งจะเกิดขึ้นหากแอปคำนวณเส้นทางไม่ได้หรือมีคำเตือนเพื่อความปลอดภัยปรากฏขึ้น คนขับอาจยังคงนำทางอยู่ แต่คุณจะไม่ได้รับการอัปเดต | กลับไปใช้การติดตามสถานะด้วยตนเองในแอป |
CLIENT_ERROR |
สถานะนี้จะปรากฏขึ้นเนื่องจากสาเหตุข้อใดข้อหนึ่งต่อไปนี้
|
กลับไปใช้การติดตามสถานะด้วยตนเองในแอป |