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 tài xế, 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, một chuyến đi đại diện cho một phiên chỉ đường đến một điểm đế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 CreateTripRequest thông báo đế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.

Tạo thông báo CreateTripRequest

Để tạo một chuyến đi và lấy 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 chi tiết, hãy xem bài viết Tạo mã thông báo OAuth.
  2. Tạo mã chuyến đi: Tạo một 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 bằng mã truy cập trong tiêu đề và tải trọng trong nội dung.

Ví dụ sau đây cho thấy 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 tuyến đường còn lại (chỉ trên Waze) boolean

Để nhận đường nhiều đoạ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 chuyến đi boolean

Theo mặc định, Navigation Connect cập nhật dữ liệu chuyến đi 60 giây một lần. Để bật tính năng 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 nặng (chẳng hạn như execution.remainingRoute) khỏi luồng sự kiện của bạ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 bài viết 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 chỉ đườ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.

Mã mẫu sau đây cho thấy một ví dụ về phản hồi:

{
    "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. Giá trị này khác với Mã dự án gồm chữ và số nhưng đại diện cho cùng một dự án trên đám mây của Google.
  • TRIP_ID: Mã chuyến đi do phần 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

Sử 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