建立行程並取得行程權杖

如要為駕駛人安全啟動即時路況導航工作階段，後端必須建立行程，並從 Navigation Connect API 取得經過驗證的行程權杖。

在 Navigation Connect 中，行程代表前往單一目的地的導航工作階段。如要建立行程並取得驗證的行程權杖 (authToken)，授權工作階段時需要這個權杖，請將 CreateTripRequest 訊息傳送至 CreateTrip 方法。將行程權杖傳遞至行動應用程式，以便納入 Google 地圖或 Waze 的啟動網址。

本指南說明如何產生不重複的行程 ID，並提交 API 要求，完成這項程序。

建構 CreateTripRequest 訊息

如要建立行程並取得行程權杖，請按照下列步驟建構及傳送 CreateTripRequest 訊息：

  1. 驗證：使用應用程式預設憑證 (ADC) 取得存取權杖，授權要求。詳情請參閱「建立 OAuth 權杖」。
  2. 產生行程 ID：以 UUIDv4 格式建立專屬行程 ID (tripId)，在伺服器上識別行程。
  3. 建構酬載：建立包含應用程式 ID 和設定的 JSON 酬載。
  4. 呼叫 CreateTrip 方法：將 POST 要求傳送至 API，並在標頭中加入存取權杖，在主體中加入酬載。

以下範例說明如何傳送 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。 這與英數字元的專案 ID 不同，但代表相同的 Google Cloud 雲端專案。
  • TRIP_ID：後端產生的行程 ID，格式為 UUIDv4。
  • BASE64_ENCODED_TRIP_TOKEN：由 CreateTrip 方法傳回的已驗證行程權杖 (authToken.token)。將這個權杖傳遞至行動應用程式，即可在 Google 地圖或 Waze 中啟動追蹤式即時路況導航。

後續步驟

使用行程權杖啟動 Google 地圖或 Waze。

啟動 Google 地圖或 Waze