如要安全地為駕駛啟動即時路況導航工作階段,後端必須建立行程,並從 Navigation Connect API 取得經過驗證的行程權杖。
在 Navigation Connect 中,行程代表前往單一目的地的導航工作階段。如要建立行程並取得授權工作階段所需的已驗證行程權杖 (authToken),請將 CreateTripRequest 訊息傳送至 CreateTrip 方法。將行程權杖傳遞至行動應用程式,以便納入 Google 地圖或 Waze 的啟動網址。
本指南說明如何產生不重複的行程 ID 並提交 API 要求,完成這項程序。
建構 CreateTripRequest 訊息
如要建立行程並取得行程權杖,請按照下列步驟建構及傳送 CreateTripRequest 訊息:
- 驗證:使用應用程式預設憑證 (ADC) 取得存取權杖,授權要求。詳情請參閱「建立 OAuth 權杖」。
- 產生行程 ID:以 UUIDv4 格式建立專屬行程 ID (
tripId),用於在伺服器上識別行程。 - 建構酬載:建立 JSON 酬載,其中包含應用程式 ID 和設定。
- 呼叫
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 |
如要接收有效路線折線和即時路況,請將 駕駛人必須使用 Android 版 Waze 5.20.0.2 以上版本、iOS 版 Waze 5.20.0.1 以上版本,或 Android 版 Google 地圖 26.27 以上版本。 |
| 路線偏離報表 (僅限 Waze) | boolean |
如要追蹤司機何時偏離路線,請將 駕駛人必須使用 Waze 5.22 以上版本。 |
| 行程更新頻率 | boolean |
根據預設,Navigation Connect 每 60 秒會更新一次行程資料。如要啟用高頻率更新 (每 5 秒),請將 |
| Google Cloud Pub/Sub 事件產生 | boolean |
如要使用 Google Cloud Pub/Sub 啟用行程事件生成功能,請將 |
| Google Cloud Pub/Sub 欄位遮罩 | FieldMask |
如要管理酬載大小,並降低後端處理負載或 Google Cloud Pub/Sub 使用費用,請使用 |
從回應中取得行程權杖
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。