Crea un viaggio e ottieni un token di viaggio

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

In Navigation Connect, un percorso rappresenta una sessione di navigazione verso una singola destinazione. Per creare una corsa e ottenere il token della corsa autenticato (authToken) richiesto per autorizzare la sessione, invia un messaggio CreateTripRequest al metodo CreateTrip. Passa il token della corsa alla tua app mobile per includerlo nell'URL di lancio per Google Maps o Waze.

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

Crea un messaggio CreateTripRequest

Per creare una corsa e ottenere un token della corsa, segui questi passaggi per creare e inviare un messaggio CreateTripRequest:

  1. Autenticati: utilizza le Credenziali predefinite dell'applicazione (ADC) per ottenere un token di accesso per autorizzare la tua richiesta. Per maggiori dettagli, consulta Crea un token OAuth.
  2. Genera un ID corsa: crea un ID corsa univoco (tripId) in formato UUIDv4 per identificare la corsa 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 una corsa 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 del percorso modificando le seguenti impostazioni nel messaggio CreateTripRequest:

Funzionalità Tipo Descrizione
Segnalazione del percorso rimanente boolean

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

I conducenti devono avere Waze versione 5.20.0.2 o successive su Android, 5.20.0.1 o successive su iOS oppure Google Maps per Android versione 26.27 o successive.

Segnalazione di deviazione dal percorso (solo Waze) boolean

Per monitorare quando un conducente esce dal percorso, imposta config.enableRouteDeviationReporting su true.

I conducenti devono avere Waze versione 5.22 o successive.

Frequenza di aggiornamento delle corse boolean

Per impostazione predefinita, Navigation Connect aggiorna i dati del 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 percorso utilizzando Google Cloud Pub/Sub, imposta config.enablePubsub su true. Questa funzionalità è disattivata per impostazione predefinita.

Maschera di campo Google Cloud Pub/Sub FieldMask

Per gestire le dimensioni dei 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) dallo stream di eventi. Per saperne di più sulle dimensioni del payload per i dati sul percorso rimanente, consulta Gestisci i dati sul percorso rimanente.

Ottieni il token della corsa dalla risposta

Il metodo CreateTrip restituisce una risposta contenente il token della corsa autenticato. Per autorizzare la sessione di navigazione, estrai questo token dalla risposta e passalo alla tua app mobile per includerlo nell'URL di lancio.

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 progetto. Questo è diverso dall'ID progetto alfanumerico, ma rappresenta lo stesso progetto Google Cloud.
  • TRIP_ID: l'ID corsa generato dal tuo backend in formato UUIDv4.
  • BASE64_ENCODED_TRIP_TOKEN: il token della corsa autenticata (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 della corsa per avviare Google Maps o Waze.

Avvia Google Maps o Waze