Crea un viaggio e ottieni un token di viaggio

Per avviare in modo sicuro una sessione di navigazione passo passo per un conducente, il backend deve creare un viaggio e ottenere un token di viaggio autenticato dall'API Navigation Connect.

In Navigation Connect, un viaggio rappresenta una sessione di navigazione verso una singola destinazione. Per creare un viaggio e ottenere il token di viaggio autenticato (authToken) necessario per autorizzare la sessione, invia un messaggio CreateTripRequest al metodo CreateTrip. Trasferisci il token di viaggio alla tua app mobile da includere nell'URL di avvio per Google Maps o Waze.

Questa guida descrive come completare la procedura generando un ID viaggio univoco e inviando la richiesta API.

Costruire un messaggio CreateTripRequest

Per creare un viaggio e ottenere un token di viaggio, segui questi passaggi per creare e inviare un messaggio CreateTripRequest:

  1. Autenticazione: utilizza le credenziali predefinite dell'applicazione (ADC) per ottenere un token di accesso per autorizzare la richiesta. Per maggiori dettagli, consulta Crea un token OAuth.
  2. Genera un ID viaggio: crea un ID viaggio univoco (tripId) in formato UUIDv4 per identificare il viaggio sul tuo server.
  3. Crea il payload: crea un payload JSON che includa gli ID app e le impostazioni di configurazione.
  4. Chiama il metodo CreateTrip: invia una richiesta POST all'API con il token di accesso nell'intestazione e il payload nel corpo.

L'esempio seguente mostra come creare un viaggio inviando un messaggio 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}"

Configurazioni facoltative

Puoi personalizzare i dati sul percorso modificando le seguenti impostazioni nel messaggio CreateTripRequest:

Funzionalità Tipo Descrizione
Segnalazione del percorso rimanente (solo Waze) boolean

Per ricevere la polilinea del percorso attivo e le condizioni del traffico in tempo reale, imposta config.enableRemainingRouteReporting su true.
Frequenza di aggiornamento del viaggio boolean

Per impostazione predefinita, Navigation Connect aggiorna i dati sul percorso ogni 60 secondi. Per attivare gli aggiornamenti ad alta frequenza (ogni 5 secondi), imposta config.enableHighFrequencyUpdates su true.
Generazione di eventi Google Cloud Pub/Sub boolean

Per attivare la generazione di eventi di viaggio utilizzando Google Cloud Pub/Sub, imposta config.enablePubsub su true. Questa funzionalità è disattivata per impostazione predefinita.
Maschera del campo Google Cloud Pub/Sub FieldMask

Per gestire le dimensioni del payload e ridurre il carico di elaborazione del backend o i costi di utilizzo di Google Cloud Pub/Sub, utilizza config.pubsubFieldMask per escludere i campi pesanti (come execution.remainingRoute) dal flusso di eventi. Per ulteriori informazioni sulle dimensioni del payload per i dati di itinerario rimanenti, vedi Gestire i dati di itinerario rimanenti.

Ottieni il token della corsa dalla risposta

Il metodo CreateTrip restituisce una risposta contenente il token di viaggio autenticato. Per autorizzare la sessione di navigazione, estrai questo token dalla risposta e passalo alla tua app mobile da includere nell'URL di avvio.

Il seguente esempio di codice mostra una risposta di esempio:

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

Questa risposta include i seguenti valori:

  • PROJECT_NUMBER: un identificatore numerico univoco per il tuo progetto. È diverso dall'ID progetto alfanumerico, ma rappresenta lo stesso progetto Google Cloud.
  • TRIP_ID: l'ID viaggio generato dal backend in formato UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN: il token di viaggio autenticato (authToken.token) restituito dal metodo CreateTrip. Passa questo token alla tua app mobile per avviare la navigazione passo passo monitorata in Google Maps o Waze.

Passaggi successivi

Utilizza il token di viaggio per avviare Google Maps o Waze.

Avviare Google Maps o Waze