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

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

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

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

สถานะ	คำอธิบาย
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 เท่านั้น)

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

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

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

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

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

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