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

เมื่อคุณดึงข้อมูลการเดินทาง แบ็กเอนด์จะได้รับเพย์โหลด 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 เหตุผลที่เบี่ยงเบน ใช้ข้อมูลนี้เพื่อพิจารณาว่าคนขับดำเนินการที่ไม่คาดคิดหรือปฏิบัติตามคำแนะนำของระบบหรือไม่
  • DRIVER_INITIATED_REROUTE: คนขับเลือกดำเนินการอย่างใดอย่างหนึ่ง (เช่น เลี้ยวผิดหรือเลือกเส้นทางใหม่ด้วยตนเอง)
  • SYSTEM_INITIATED_REROUTE: แอปการนำทางคำนวณเส้นทางใหม่ (เช่น เนื่องจากสภาพการจราจรที่เปลี่ยนแปลงหรือการปิดถนน)
client_timestamp Timestamp เวลาที่อุปกรณ์ไคลเอ็นต์ตรวจพบความคลาดเคลื่อน
server_timestamp Timestamp เวลาที่เซิร์ฟเวอร์ประมวลผลการอัปเดตความคลาดเคลื่อน

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

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

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