Update selected routes

Questa pagina descrive come aggiornare i percorsi che hai già creato utilizzando l'API Roads Selection:

Aggiorna una route

Per aggiornare una route, invia una richiesta PATCH all'endpoint patch:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID?updateMask=UPDATE_MASK

Il corpo della richiesta deve essere un oggetto JSON contenente i campi di SelectedRoute da aggiornare. I campi aggiornabili includono displayName, routeAttributes, dynamicRoute e dynamicRouting (se la route è fissa o dinamica). Quando aggiorni i waypoint del percorso (dynamicRoute), devi fornire l'intero oggetto dynamicRoute (origine, destinazione e waypoint intermedi). Gli aggiornamenti parziali dei campi secondari non sono supportati. I campi di sistema di sola lettura come name, createTime e state non possono essere modificati. I dati storici in BigQuery conservano i dati dei waypoint precedenti e aggiornati nello stesso selectedRouteId. Se hai bisogno di dati storici separati, crea un nuovo percorso anziché eseguire un aggiornamento.

L'aggiornamento dei waypoint di un percorso (dynamicRoute) attiva una nuova convalida del percorso. I campi static_route_geometry e road_segment_ids nella tabella BigQuery routes_status vengono aggiornati di conseguenza.

Gli aggiornamenti dei waypoint sono consentiti quando il percorso è in stato STATE_RUNNING o STATE_INVALID e vengono rifiutati se il percorso è in stato STATE_VALIDATING o STATE_DELETING. Per saperne di più, consulta la sezione Stati di convalida e route. L'aggiornamento di metadati come displayName, routeAttributes o dynamicRouting è consentito in tutti gli stati, ad eccezione di STATE_DELETING.

Il seguente esempio di codice mostra la struttura di una richiesta PATCH all'endpoint patch:

curl -X PATCH -d '{
    "dynamicRoute": {
      "origin": {
        "latitude": 38.5817,
        "longitude": -121.4944
      },
      "destination": {
        "latitude": 38.5449,
        "longitude": -121.7405
      }
    }
  }' \
-H 'X-Goog-User-Project: PROJECT_NUMBER' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
"https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes/"\
"SELECTED_ROUTE_ID?updateMask=dynamicRoute"

In caso di esito positivo, l'API restituisce la risorsa SelectedRoute aggiornata:

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": 38.5817,
      "longitude": -121.4944
    },
    "destination": {
      "latitude": 38.5449,
      "longitude": -121.7405
    }
  },
  "createTime": "2026-08-14T20:58:41.345418Z",
  "state": "STATE_VALIDATING",
  "dynamicRouting": TRUE_OR_FALSE
}

Aggiornamento batch delle route

Per aggiornare più percorsi in un'unica richiesta, utilizza l'endpoint batchUpdate. Questo endpoint ti consente di aggiornare fino a 1000 route in una sola chiamata. Gli aggiornamenti batch sono atomici: se una route nella richiesta non supera la convalida o non può essere aggiornata, nessuna route nel batch viene modificata.

Invia una richiesta POST all'endpoint batchUpdate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchUpdate

Il corpo della richiesta deve essere un oggetto JSON contenente un array requests. Ogni oggetto all'interno di questo array è un UpdateSelectedRouteRequest che specifica la route name, un updateMask facoltativo a livello di elemento e i campi selectedRoute da aggiornare.

Un updateMask è un parametro facoltativo che specifica l'elenco di campi da aggiornare (displayName, routeAttributes, dynamicRouting o l'intero oggetto dynamicRoute). L'impostazione updateMask=* indica una sostituzione completa. È possibile specificare un updateMask all'interno di ogni singolo elemento in requests o spostarlo al livello superiore del corpo della richiesta batch per applicarlo a tutti i percorsi aggiornati nel batch. Se updateMask viene omesso, si presume che tutti i campi aggiornabili compilati nella richiesta vengano aggiornati. Se un updateMask è impostato sia a livello di batch che di elemento, i valori devono corrispondere. La specifica di maschere in conflitto genera un errore INVALID_ARGUMENT.

Il seguente esempio di codice mostra la struttura di una richiesta POST all'endpoint batchUpdate:

curl -X POST -d '{
    "requests": [
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
          "displayName": "DISPLAY_NAME_1",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      },
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
          "displayName": "DISPLAY_NAME_2",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      }
    ]}' \
-H 'X-Goog-User-Project: PROJECT_NUMBER' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
"https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes:batchUpdate"

In caso di esito positivo, l'API restituisce una risposta contenente un array delle risorse SelectedRoute aggiornate:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "displayName": "DISPLAY_NAME_1",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING",
      "dynamicRouting": TRUE_OR_FALSE
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "displayName": "DISPLAY_NAME_2",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING",
      "dynamicRouting": TRUE_OR_FALSE
    }
  ]
}