处理行程数据

当您检索行程数据时,您的后端会收到详细说明司机行程进度的 JSON 载荷。解析这些载荷,以监控行程、更新调度系统,并解读当前行程状态,从而确定司机在行程进行中或行程结束时的下一步操作。

读取数据载荷

当司机开始导航、沿路线定期(默认每 60 秒)以及司机到达目的地时,Google 地图或 Waze 会将行程数据载荷发送到 Navigation Connect 服务器。每条 JSON 消息都包含相关的行程数据,包括司机在道路上行驶的坐标、行驶距离和预计到达时间 (ETA)。由于这些更新反映了驾驶员的实时路线,因此可能与后端预先计算的路线不同(请参阅常见问题解答)。

以下代码示例展示了司机开始导航从国王十字车站到圣吉尔斯中央广场的行程时的行程数据载荷。

{
  "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 会在 JSON 数据载荷中将 execution.stopAddedInRoute 字段设置为 true。Navigation Connect API 会继续跟踪司机前往原始目的地。预计到达时间 (ETA)、距离和时长等指标会增加,以包含添加的经停点。

添加经停点的行为取决于导航应用,并与其标准功能一致:

  • Google 地图:驾驶员可以向路线添加多个经停点。
  • Waze:司机只能添加一个经停点。如果司机尝试添加其他经停点,Waze 会提示他们开始新的导航会话,而不是将经停点添加到当前路线。

您无需调整后端输入即可支持此功能。

排查身份验证和启动问题

如果您没有收到 ENROUTE 状态,则可能发生了身份验证错误。常见原因包括 API 参数拼写错误或行程令牌过期。在初始 CreateTrip 响应中查看令牌到期时间。

如果状态未从 NEW 更改为 ENROUTE,则可能是司机的设备阻止了身份验证。Navigation Connect 不会针对这些情况发送出错提示。验证以下事项:

  • 司机已安装 Waze 5.15.5 或更高版本,或者 Google 地图 26.14 或更高版本。
  • 驾驶员未使用 Android Auto 或 Apple CarPlay。
  • 司机已连接到互联网。

处理剩余路线数据

如果您在创建行程期间启用了剩余路线报告功能,您的后端会收到从司机当前位置到其最终目的地的剩余路线多段线和实时路况信息。司机需要使用 Waze 5.20.0.2 或更高版本(Android 设备)、5.20.0.1 或更高版本(iOS 设备),或者 Google 地图 26.27 或更高版本(Android 设备)。

您可以注入和处理这些数据,以便在应用中实现多种功能,包括以下示例:

  • 提供实时跟踪地图:在面向客户的网页或移动地图上呈现剩余路线多段线,以便客户了解司机的行程。
  • 提高预计到达时间的准确性:结合使用贴合道路的多段线和路况区间速度,提高内部物流或送货到达预测的准确性。
  • 分析路线合规性:将剩余路线几何图形与预期调度路线进行比较,以评估司机是否遵守路线(如需详细了解实时路线和预先计算的路线为何可能存在差异,请参阅常见问题解答)。

无论您是发送 GetTrip 请求,还是使用 Google Cloud Pub/Sub 接收事件驱动型更新,Navigation Connect 都会在 execution.remainingRoute 字段中返回剩余路线详情。不过,载荷如何设置这些数据的格式和结构取决于您使用的检索方法。

GetTrip 方法

当您调用 GetTrip 方法时,多段线的响应格式取决于您在请求中指定的 routePolylineFormat 参数。如需了解详情,请参阅自定义多段线格式。

对于所有多段线格式,Navigation Connect 都会在 execution.remainingRoute.trafficInformation 字段中以单独的 SpeedReadingInterval 对象列表形式返回路况信息。这些对象使用以下值将路况类别映射到多段线索引:

Google Cloud Pub/Sub 更新

当您使用 Pub/Sub 检索行程数据时,更新始终会在 execution.remainingRoute 字段中以统一的 GeoJSON FeatureCollection 格式返回剩余路线数据。

此格式将多段线几何图形与路况速度直接结合,无需手动映射索引。

查看 Pub/Sub 载荷示例

以下代码示例展示了在 Pub/Sub 消息的 updatedTrip 对象内的 execution.remainingRoute 字段中返回的 GeoJSON 结构:

{
  "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)。如果您收到高频更新,此数据量可能会增加后端处理负载和使用费用。

如需优化数据流,请在创建行程期间使用 TripConfig 对象中的 pubsubFieldMask 参数来排除大型字段。如需了解详情,请参阅可选配置。

处理路线偏离(仅限 Waze)

司机需要使用 Waze 5.22 或更高版本。

如果您在创建行程时启用了路线偏离报告,那么当司机偏离路线时,API 会返回路线偏离元数据。您可以通过以下方式访问这些数据:

  • 按需:调用 GetTrip 方法。服务器会保留最后已知的偏差状态。
  • 实时:订阅 Google Cloud Pub/Sub。该服务会在检测到偏差后 5 秒内使用现有 updated_trip 事件发布偏差更新。

读取偏差载荷

last_route_deviation 对象提供以下元数据,以帮助您分析事件。

字段 类型 说明
location LatLng 客户端设备记录偏差时的纬度和经度坐标。
source TriggerSource 偏离的原因。使用此字段可确定司机是采取了意外操作还是遵循了系统指引:
  • DRIVER_INITIATED_REROUTE:驾驶员做出了主动选择(例如,转错弯或手动选择新路线)。
  • SYSTEM_INITIATED_REROUTE:导航应用计算了一条新路线(例如,由于路况信息发生变化或封路)。
client_timestamp Timestamp 客户端设备检测到偏差的时间。
server_timestamp Timestamp 服务器处理偏差更新的时间。

处理行程结束状态

当司机到达目的地或停止导航时,载荷会返回以下结束状态之一。使用这些状态在应用中触发适当的后续步骤。

状态 说明 建议采取的操作
ARRIVED 司机已到达目的地。 查看 remainingDistanceMeters。如果司机将车停在附近,但未停在确切坐标处,请考虑在应用中提供步行路线。
SUSPENDED 司机在到达目的地之前手动退出了精细导航。
由于 Google 地图或 Waze 不会在司机提前退出会话时自动将其返回到您的应用,因此司机必须手动点按返回按钮。
为了帮助司机完成行程,请将 execution.location 与目的地进行比较。如果仍有距离,请提供一个按钮或链接,以便恢复行程或切换到步行模式。
FAILED 连接因技术错误而中断。如果应用无法计算路线或显示安全警告,就会发生这种情况。司机可能仍在导航,但您不会收到更新。 在应用中回退到手动状态跟踪。
CLIENT_ERROR 出现此状态的原因可能如下:
  • 司机撤销同意。
  • 司机使用的是不受支持的平台,例如 Android Auto 或 Apple CarPlay。
  • 您的应用在不同的行程中重复使用行程令牌。例如,Navigation Connect 会拒绝更改行程目的地或更新已完成行程的请求。
  • 司机在行程中的任何时间点位于美国境内,但您在设置期间验证应用时,未在美国境内启用数据共享。
在应用中回退到手动状态跟踪。