处理行程数据

当您检索行程数据时，后端会收到详细说明司机行程进度的 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）

如果您已在创建行程期间启用剩余路线报告，您的后端会收到从司机当前位置到最终目的地的剩余路线折线和实时路况信息。

您可以提取和处理这些数据，以支持应用中的多项功能，包括以下示例：

  • 为实时跟踪地图提供支持：在面向客户的网络地图或移动地图上呈现剩余路线多段线，以便客户了解司机的行程。
  • 提高预计到达时间 (ETA) 的准确性：结合贴合道路的多段线和交通间隔速度，改进内部物流或送货到达预测。
  • 分析路线合规性：将剩余路线几何图形与预期派单路线进行比较，以评估驾驶员的合规性（如需详细了解实时路线与预先计算的路线可能存在差异的原因，请参阅常见问题解答）。

无论是发送 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）

如果您已在创建行程时启用路线偏离报告，那么当司机偏离路线时，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 会拒绝更改行程目的地或更新已完成行程的请求。
  • 司机在行程期间的任何时间点都位于美国，但您在设置期间验证应用时，并未在美国启用数据共享。
 在应用中回退到手动状态跟踪。