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

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

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

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

สถานะ คำอธิบาย
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

สำหรับรูปแบบ 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ระหว่างการสร้างการเดินทางเพื่อยกเว้นฟิลด์ที่มีขนาดใหญ่ โปรดดูรายละเอียดที่การกำหนดค่าที่ไม่บังคับ

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

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

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