建立行程並取得行程權杖

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

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

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

建構 CreateTripRequest 訊息

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

  1. 驗證:使用應用程式預設憑證 (ADC) 取得存取權杖,授權要求。詳情請參閱「建立 OAuth 權杖」。
  2. 產生行程 ID:以 UUIDv4 格式建立專屬行程 ID (tripId),用於在伺服器上識別行程。
  3. 建構酬載:建立 JSON 酬載,其中包含應用程式 ID 和設定。
  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 訊息中調整下列設定,自訂行程資料:

功能 類型 說明
回報剩餘路線 boolean

如要接收有效路線折線和即時路況,請將 config.enableRemainingRouteReporting 設為 true。

駕駛人必須使用 Android 版 Waze 5.20.0.2 以上版本、iOS 版 Waze 5.20.0.1 以上版本,或 Android 版 Google 地圖 26.27 以上版本。

路線偏離報表 (僅限 Waze) boolean

如要追蹤司機何時偏離路線,請將 config.enableRouteDeviationReporting 設為 true。

駕駛人必須使用 Waze 5.22 以上版本。

行程更新頻率 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