创建行程并获取行程令牌

如需为司机安全地启动精细导航会话，您的后端必须创建行程并从 Navigation Connect API 获取经过身份验证的行程令牌。

在 Navigation Connect 中，行程是指前往单个目的地的导航会话。如需创建行程并获取授权会话所需的经过身份验证的行程令牌 (authToken)，请向 CreateTrip 方法发送 CreateTripRequest 消息。将行程令牌传递给您的移动应用，以包含在 Google 地图或 Waze 的启动网址中。

本指南介绍了如何通过生成唯一的行程 ID 并提交 API 请求来完成此流程。

构建 CreateTripRequest 消息

如需创建行程并获取行程令牌，请执行以下步骤来构建和发送 CreateTripRequest 消息：

  1. 进行身份验证：使用应用默认凭证 (ADC) 获取访问令牌，以授权您的请求。如需了解详情，请参阅创建 OAuth 令牌。
  2. 生成行程 ID：创建 UUIDv4 格式的唯一行程 ID (tripId)，用于在服务器上标识行程。
  3. 构建载荷：创建包含应用 ID 和配置设置的 JSON 载荷。
  4. 调用 CreateTrip 方法：向 API 发送 POST 请求，并在标头中包含访问令牌，在正文中包含载荷。

以下示例展示了如何通过发送 CreateTripRequest 消息来创建行程：

#!/bin/bash

# Authenticate with ADC
access_token="$(gcloud auth application-default login --impersonate-service-account=SERVICE_ACCOUNT_EMAIL)"

# Generate a unique Trip ID
trip_id="$(uuidgen)"

# Construct the payload
payload=$(cat <<EOF
{
  "androidAppId": "ANDROID_APP_ID",
  "iosAppId": "IOS_APP_ID",
  "config": {
    "enablePubsub": true
  }
}
EOF
)

# Call the CreateTrip method to request a trip token
curl -X POST "https://navigationconnect.googleapis.com/v1/projects/PROJECT_ID/trips?tripId=${trip_id}" \
-H "Authorization: Bearer ${access_token}" \
-H "Content-Type: application/json" \
-d "${payload}"

可选配置

您可以在 CreateTripRequest 消息中调整以下设置，以自定义行程数据：

功能 类型 说明
剩余路线报告（仅限 Waze） boolean

如需接收有效路线的折线和实时路况信息，请将 config.enableRemainingRouteReporting 设置为 true。
行程更新频率 boolean

默认情况下，Navigation Connect 每 60 秒更新一次行程数据。如需启用高频更新（每 5 秒），请将 config.enableHighFrequencyUpdates 设置为 true。
Google Cloud Pub/Sub 事件生成 boolean

如需使用 Google Cloud Pub/Sub 启用行程事件生成功能，请将 config.enablePubsub 设置为 true。此功能默认处于停用状态。
Google Cloud Pub/Sub 字段掩码 FieldMask

如需管理载荷大小并减少后端处理负载或 Google Cloud Pub/Sub 使用费用，请使用 config.pubsubFieldMask 从事件流中排除占用空间较大的字段（例如 execution.remainingRoute）。如需详细了解剩余路线数据的载荷大小，请参阅处理剩余路线数据。

从响应中获取行程令牌

CreateTrip 方法会返回包含经过身份验证的行程令牌的响应。如需授权导航会话，请从响应中提取此令牌，并将其传递给移动应用以包含在启动网址中。

以下代码示例展示了一个示例响应：

{
    "name": "projects/PROJECT_NUMBER/trips/TRIP_ID",
  "authToken": {
    "token": "BASE64_ENCODED_TRIP_TOKEN",
    "expireTime": "2026-03-06T11:09:47.476942Z"
  },
  "state": "NEW",
  "execution": {
    "traveledDistanceMeters": 0,
    "stopAddedInRoute": false
  },
  "createTime": "2026-03-05T23:09:50.768959Z",
  "updateTime": "2026-03-05T23:09:50.768959Z"
}

此响应包含以下值：

  • PROJECT_NUMBER：项目的唯一数字标识符。此标识符与字母数字项目 ID 不同，但表示的是同一个 Google Cloud 项目。
  • TRIP_ID：由后端生成的行程 ID，采用 UUIDv4 格式。
  • BASE64_ENCODED_TRIP_TOKEN：由 CreateTrip 方法返回的经过身份验证的行程令牌 (authToken.token)。将此令牌传递给您的移动应用，以在 Google 地图或 Waze 中启动跟踪的精细导航。

后续步骤

使用行程令牌启动 Google 地图或 Waze。

启动 Google 地图或 Waze