Tạo chuyến đi và nhận mã thông báo chuyến đi

Để khởi chạy một phiên chỉ đường từng chặng một cách an toàn cho người lái xe, phần phụ trợ của bạn phải tạo một chuyến đi và lấy mã thông báo chuyến đi đã xác thực từ Navigation Connect API.

Trong Navigation Connect, chuyến đi là một phiên điều hướng đến một đích đến duy nhất. Để tạo một chuyến đi và lấy mã thông báo chuyến đi đã xác thực (authToken) cần thiết để uỷ quyền cho phiên, hãy gửi một thông báo CreateTripRequest đến phương thức CreateTrip. Truyền mã thông báo chuyến đi đến ứng dụng di động của bạn để đưa vào URL khởi chạy cho Google Maps hoặc Waze.

Hướng dẫn này mô tả cách hoàn tất quy trình này bằng cách tạo một mã chuyến đi duy nhất và gửi yêu cầu API.

Soạn một thông báo CreateTripRequest

Để tạo một chuyến đi và nhận mã thông báo chuyến đi, hãy thực hiện các bước sau để tạo và gửi thông báo CreateTripRequest:

  1. Xác thực: Sử dụng Thông tin xác thực mặc định của ứng dụng (ADC) để lấy mã truy cập nhằm uỷ quyền cho yêu cầu của bạn. Để biết thêm thông tin, hãy xem phần Tạo mã thông báo OAuth.
  2. Tạo mã chuyến đi: Tạo mã chuyến đi duy nhất (tripId) ở định dạng UUIDv4 để xác định chuyến đi trên máy chủ của bạn.
  3. Tạo tải trọng: Tạo tải trọng JSON bao gồm mã ứng dụng và chế độ cài đặt cấu hình.
  4. Gọi phương thức CreateTrip: Gửi yêu cầu POST đến API cùng với mã truy cập trong tiêu đề và tải trọng trong nội dung.

Ví dụ sau đây cho biết cách tạo một chuyến đi bằng cách gửi thông báo 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}"

Cấu hình không bắt buộc

Bạn có thể tuỳ chỉnh dữ liệu chuyến đi bằng cách điều chỉnh các chế độ cài đặt sau trong thông báo CreateTripRequest:

Tính năng Loại Mô tả
Báo cáo về tuyến đường còn lại (chỉ trên Waze) boolean

Để nhận đường đa tuyến của tuyến đường đang hoạt động và tình trạng giao thông theo thời gian thực, hãy đặt config.enableRemainingRouteReporting thành true.
Tần suất cập nhật thông tin về chuyến đi boolean

Theo mặc định, Navigation Connect cập nhật dữ liệu chuyến đi sau mỗi 60 giây. Để bật chế độ cập nhật tần suất cao (5 giây một lần), hãy đặt config.enableHighFrequencyUpdates thành true.
Tạo sự kiện Google Cloud Pub/Sub boolean

Để bật tính năng tạo sự kiện chuyến đi bằng Google Cloud Pub/Sub, hãy đặt config.enablePubsub thành true. Tính năng này bị tắt theo mặc định.
Mặt nạ trường Google Cloud Pub/Sub FieldMask

Để quản lý kích thước tải trọng và giảm tải xử lý phụ trợ hoặc chi phí sử dụng Google Cloud Pub/Sub, hãy sử dụng config.pubsubFieldMask để loại trừ các trường có kích thước lớn (chẳng hạn như execution.remainingRoute) khỏi luồng sự kiện. Để biết thêm thông tin về kích thước tải trọng cho dữ liệu tuyến đường còn lại, hãy xem phần Xử lý dữ liệu tuyến đường còn lại.

Lấy mã thông báo chuyến đi từ phản hồi

Phương thức CreateTrip trả về một phản hồi chứa mã thông báo chuyến đi đã xác thực. Để uỷ quyền cho phiên điều hướng, hãy trích xuất mã thông báo này từ phản hồi và truyền mã thông báo đó đến ứng dụng di động của bạn để đưa vào URL khởi chạy.

Đoạn mã mẫu sau đây cho thấy một phản hồi mẫu:

{
    "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"
}

Phản hồi này bao gồm các giá trị sau:

  • PROJECT_NUMBER: Giá trị nhận dạng bằng số duy nhất cho dự án của bạn. Mã này khác với Mã dự án gồm cả chữ và số nhưng đại diện cho cùng một dự án trên Google Cloud.
  • TRIP_ID: Mã chuyến đi do phụ trợ của bạn tạo ở định dạng UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN: Mã thông báo chuyến đi đã xác thực (authToken.token) do phương thức CreateTrip trả về. Truyền mã thông báo này đến ứng dụng di động của bạn để bắt đầu chỉ đường từng chặng có theo dõi trong Google Maps hoặc Waze.

Bước tiếp theo

Dùng mã thông báo chuyến đi để khởi chạy Google Maps hoặc Waze.

Khởi chạy Google Maps hoặc Waze