จัดการข้อมูลการเดินทาง

เมื่อดึงข้อมูลการเดินทาง แบ็กเอนด์จะได้รับ เพย์โหลด 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
  }
}

หมายเหตุ: หากคุณได้รับข้อมูลโดยใช้ Google Cloud Pub/Sub บริการจะห่อหุ้ม การอัปเดตการเดินทางในซองข้อความมาตรฐาน ฟิลด์ข้อมูลมีเพย์โหลด JSON ของ Navigation Connect จริง

ตรวจสอบสถานะการเดินทางที่ใช้งานอยู่

หากต้องการยืนยันการเริ่มต้นที่สำเร็จและตรวจสอบความคืบหน้า ให้ประเมินฟิลด์ stateในเพย์โหลดทุกรายการ

สถานะ	คำอธิบาย
NEW	สร้างการเดินทางแล้ว แต่คนขับยังไม่ได้เริ่มนำทาง
ENROUTE	คนขับกำลังนำทางไปยังจุดหมายอย่างต่อเนื่อง ใช้สถานะนี้เพื่อยืนยันว่าการเดินทางได้รับการตรวจสอบสิทธิ์และเริ่มต้นเรียบร้อยแล้ว

จัดการจุดแวะพักที่เพิ่ม

คนขับสามารถเพิ่มจุดแวะพักลงในเส้นทางระหว่างการนำทางได้ หากมี Navigation Connect จะตั้งค่าฟิลด์ execution.stopAddedInRoute เป็น true ในเพย์โหลดข้อมูล JSON Navigation Connect API จะติดตามคนขับไปยังจุดหมายเดิมต่อไป เมตริกต่างๆ เช่น เวลาถึงโดยประมาณ (ETA), ระยะทาง และระยะเวลาจะเพิ่มขึ้น เพื่อให้รวมจุดแวะพักที่เพิ่มเข้ามา

ลักษณะการทำงานสำหรับการเพิ่มจุดแวะพักจะขึ้นอยู่กับแอปนำทางและตรงกับฟังก์ชันการทำงานมาตรฐานของแอป ดังนี้

• Google Maps: คนขับสามารถเพิ่มจุดแวะพักหลายจุดลงในเส้นทางได้
• Waze: คนขับเพิ่มจุดแวะพักได้เพียง 1 จุด หากคนขับพยายามเพิ่มป้ายหยุดพักอื่น Waze จะแจ้งให้เริ่มเซสชันการนำทางใหม่แทนที่จะเพิ่มป้ายหยุดพักลงในเส้นทางปัจจุบัน

คุณไม่จำเป็นต้องปรับอินพุตแบ็กเอนด์เพื่อรองรับฟีเจอร์นี้

แก้ปัญหาการตรวจสอบสิทธิ์และปัญหาการเริ่มต้น

หากไม่ได้รับสถานะ ENROUTE แสดงว่าอาจเกิดข้อผิดพลาดในการตรวจสอบสิทธิ์ สาเหตุที่พบบ่อย ได้แก่ พารามิเตอร์ API ที่สะกดผิดหรือโทเค็นการเดินทางหมดอายุ ตรวจสอบเวลาหมดอายุของโทเค็นในCreateTripการตอบกลับครั้งแรก

หากสถานะไม่เปลี่ยนจาก NEW เป็น ENROUTE แสดงว่าอุปกรณ์ของคนขับอาจ ป้องกันการตรวจสอบสิทธิ์ Navigation Connect จะไม่ส่งข้อความแสดงข้อผิดพลาด ในกรณีเหล่านี้ โปรดตรวจสอบสิ่งต่อไปนี้

• คนขับมี Waze เวอร์ชัน 5.15.5 ขึ้นไป หรือ Google Maps เวอร์ชัน 26.14 ขึ้นไป
• คนขับไม่ได้ใช้ Android Auto หรือ Apple CarPlay
• คนขับมีการเชื่อมต่ออินเทอร์เน็ตที่ใช้งานได้

จัดการข้อมูลเส้นทางที่เหลือ (Waze เท่านั้น)

หากเปิดใช้การรายงานเส้นทางที่เหลือในระหว่างการสร้างการเดินทาง แบ็กเอนด์จะได้รับเส้นโพลีไลน์ของเส้นทางที่เหลือและสภาพการจราจรแบบเรียลไทม์ จากตำแหน่งปัจจุบันของผู้ขับขี่ไปยังจุดหมายสุดท้าย

คุณสามารถนำเข้าและประมวลผลข้อมูลนี้เพื่อขับเคลื่อนฟีเจอร์ต่างๆ ในแอปพลิเคชันของคุณ ซึ่งรวมถึงตัวอย่างต่อไปนี้

• ขับเคลื่อนแผนที่การติดตามแบบเรียลไทม์: แสดงผลเส้นหลายเหลี่ยมของเส้นทางที่เหลือในเว็บหรือแผนที่บนอุปกรณ์เคลื่อนที่ที่หันหน้าไปทางลูกค้าเพื่อให้มองเห็นเส้นทางการเดินทางของคนขับ
• เพิ่มความแม่นยำของเวลาถึงโดยประมาณ: รวมเส้นประกอบที่สแนปกับถนนและความเร็วของช่วงเวลาการจราจรเพื่อปรับปรุงการคาดการณ์เวลาถึงของการนำส่งหรือโลจิสติกส์ภายใน
• วิเคราะห์การปฏิบัติตามข้อกำหนดด้านการกำหนดเส้นทาง: เปรียบเทียบรูปทรงเรขาคณิตของเส้นทางที่เหลือกับ เส้นทางที่คาดว่าจะมีการมอบหมายงานเพื่อประเมินการปฏิบัติตามข้อกำหนดของคนขับ (ดูคำถามที่พบบ่อย เพื่อดูรายละเอียดเกี่ยวกับสาเหตุที่เส้นทางแบบเรียลไทม์และเส้นทางที่คำนวณไว้ล่วงหน้าอาจแตกต่างกัน)

Navigation Connect จะแสดงรายละเอียดเส้นทางที่เหลือในฟิลด์ execution.remainingRoute ไม่ว่าคุณจะส่งคำขอ GetTrip หรือรับการอัปเดตที่อิงตามเหตุการณ์ โดยใช้ Google Cloud Pub/Sub อย่างไรก็ตาม รูปแบบและโครงสร้างของเพย์โหลด ข้อมูลนี้จะขึ้นอยู่กับวิธีการดึงข้อมูลที่คุณใช้

GetTrip วิธี

เมื่อเรียกใช้เมธอด GetTrip รูปแบบการตอบกลับสำหรับเส้นประกอบจะขึ้นอยู่กับพารามิเตอร์ routePolylineFormat ที่คุณระบุในคำขอ ดูข้อมูลเพิ่มเติมได้ที่ปรับแต่งรูปแบบเส้นหลายส่วน

สำหรับรูปแบบ Polyline ทั้งหมด 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 เท่านั้น)

หากคุณเปิดใช้การรายงานการเบี่ยงเบนเส้นทางในระหว่างการสร้างการเดินทาง เมื่อคนขับออกนอกเส้นทาง API จะแสดงข้อมูลเมตาการเบี่ยงเบนเส้นทาง คุณ เข้าถึงข้อมูลนี้ได้ด้วยวิธีต่อไปนี้

• ตามต้องการ: เรียกใช้เมธอด GetTrip เซิร์ฟเวอร์จะคงสถานะการเบี่ยงเบนล่าสุดที่ทราบ
• เรียลไทม์: สมัครใช้บริการ Google Cloud Pub/Sub บริการจะเผยแพร่การอัปเดตความเบี่ยงเบนโดยใช้updated_tripเหตุการณ์ที่มีอยู่ภายใน 5 วินาที ของการตรวจจับ

อ่านเพย์โหลดการเบี่ยงเบน

ออบเจ็กต์ last_route_deviation จะให้ข้อมูลเมตาต่อไปนี้เพื่อช่วยคุณ วิเคราะห์เหตุการณ์

ช่อง	ประเภท	คำอธิบาย
location	LatLng	พิกัดละติจูดและลองจิจูดที่อุปกรณ์ไคลเอ็นต์บันทึกความคลาดเคลื่อน
source	TriggerSource	เหตุผลของการเบี่ยงเบน ใช้เพื่อพิจารณาว่าคนขับได้ดำเนินการ ที่ไม่คาดคิดหรือทำตามคำแนะนำของระบบหรือไม่ DRIVER_INITIATED_REROUTE: คนขับเลือกเส้นทางอื่น (เช่น เลี้ยวผิดทางหรือเลือกเส้นทางใหม่ด้วยตนเอง ) SYSTEM_INITIATED_REROUTE: แอปนำทาง คำนวณเส้นทางใหม่ (เช่น เนื่องจากสภาพการจราจรที่เปลี่ยนแปลง หรือการปิดถนน)
client_timestamp	Timestamp	เวลาที่อุปกรณ์ไคลเอ็นต์ตรวจพบความเบี่ยงเบน
server_timestamp	Timestamp	เวลาที่เซิร์ฟเวอร์ประมวลผลการอัปเดตความคลาดเคลื่อน

จัดการสถานะการสิ้นสุดการเดินทาง

เมื่อคนขับถึงจุดหมายหรือหยุดการนำทาง เพย์โหลดจะแสดงสถานะสิ้นสุดอย่างใดอย่างหนึ่งต่อไปนี้ ใช้สถานะเหล่านี้เพื่อทริกเกอร์ ขั้นตอนถัดไปที่เหมาะสมในแอป

สถานะ	คำอธิบาย	การดำเนินการที่แนะนำ
ARRIVED	คนขับถึงจุดหมายแล้ว	ดูremainingDistanceMeters หากคนขับจอดรถ ในบริเวณใกล้เคียงแต่ไม่ใช่ที่พิกัดที่แน่นอน ให้พิจารณาให้ เส้นทางการเดินในแอป
SUSPENDED	คนขับออกจากระบบการนำทางแบบเลี้ยวต่อเลี้ยวด้วยตนเองก่อนที่จะถึง จุดหมาย เนื่องจาก Google Maps หรือ Waze จะไม่นำผู้ขับขี่กลับไปที่แอปของคุณโดยอัตโนมัติเมื่อ ผู้ขับขี่ออกจากเซสชันก่อนเวลา ผู้ขับขี่จึงต้องแตะปุ่มกลับด้วยตนเอง หมายเหตุ: หากคนขับใช้ปุ่มย้อนกลับ เพื่อสลับกลับไปที่แอปของคุณโดยไม่ออกจากเซสชันการนำทางที่ใช้งานอยู่ สถานะการเดินทางจะยังคงเป็นENROUTE ดูข้อมูลเพิ่มเติมได้ที่จัดการการสลับแอป ระหว่างการเดินทาง	เปรียบเทียบexecution.locationกับจุดหมายปลายทางเพื่อช่วยให้ผู้ขับขี่เดินทางถึงจุดหมาย หากยังคงมีระยะทางเหลืออยู่ ให้ระบุปุ่มหรือลิงก์เพื่อเดินทางต่อหรือเปลี่ยนเป็น โหมดการเดิน
FAILED	ข้อผิดพลาดทางเทคนิคขัดขวางการเชื่อมต่อ กรณีนี้จะเกิดขึ้นหากแอป คำนวณเส้นทางไม่ได้หรือคำเตือนด้านความปลอดภัยปรากฏขึ้น คนขับอาจ ยังคงนำทางอยู่ แต่คุณจะไม่ได้รับการอัปเดต	กลับไปใช้การติดตามสถานะด้วยตนเองในแอป
CLIENT_ERROR	สถานะนี้จะปรากฏขึ้นจากสาเหตุข้อใดข้อหนึ่งต่อไปนี้ คนขับเพิกถอนความยินยอม คนขับใช้แพลตฟอร์มที่ไม่รองรับ เช่น Android Auto หรือ Apple CarPlay แอปของคุณใช้โทเค็นการเดินทางซ้ำในการเดินทางที่แยกกัน ตัวอย่างเช่น Navigation Connect จะปฏิเสธคำขอที่เปลี่ยนจุดหมายของการเดินทางหรือ อัปเดตการเดินทางที่เสร็จสมบูรณ์แล้ว คนขับอยู่ในสหรัฐอเมริกา ณ จุดใดก็ตามระหว่างการเดินทาง แต่แอปของคุณไม่ได้เปิดใช้การแชร์ข้อมูลในสหรัฐอเมริกาเมื่อคุณยืนยันแอปในระหว่างการตั้งค่า	กลับไปใช้การติดตามสถานะด้วยตนเองในแอป