Créer des routes sélectionnées

Cette page explique comment créer des routes et ajouter des attributs personnalisés à l'aide de l'API Roads Selection dans les sections suivantes :

Créer une route : définissez une seule route à l'aide du create point de terminaison.
Créer des routes par lot : définissez plusieurs routes dans une seule requête à l'aide du point de terminaison batchCreate.
Créer une route avec des points de cheminement intermédiaires : définissez une route avec jusqu'à 25 points de cheminement intermédiaires.
Utiliser des attributs de route personnalisés : ajoutez jusqu'à 10 paires clé-valeur personnalisées à vos routes à des fins d'organisation.

Créer une route

Pour créer une route, envoyez une POST requête au create point de terminaison.

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

Le corps de la requête doit être un objet JSON qui définit la SelectedRoute ressource. Cet objet spécifie les informations suivantes :

Un objet dynamicRoute contenant les informations suivantes :
- The origin de la route sélectionnée.
- The destination de la route sélectionnée.
- Tous les intermediates (également appelés points de cheminement) de la route.
Un unique selectedRouteId. Cette valeur doit comporter entre 4 et 63 caractères et ne doit utiliser que des caractères alphanumériques. Si vous ne fournissez pas d'ID, le système en génère un unique pour la route sélectionnée.

L'exemple de code suivant montre la structure d'une requête POST au point de terminaison create.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

En cas de succès, l'API renvoie la SelectedRoute ressource. La réponse inclut le selectedRouteId dans le champ name. Vous pouvez utiliser ce selectedRouteId pour récupérer ou supprimer la ressource SelectedRoute.

L'exemple de code suivant montre la structure d'une réponse réussie du create point de terminaison.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Créer des routes par lot

Pour créer plusieurs routes dans une seule requête, utilisez le batchCreate point de terminaison. Ce point de terminaison vous permet de définir jusqu'à 1 000 routes en un seul appel.

Envoyez une requête POST au point de terminaison batchCreate :

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

L'URL utilise la syntaxe de transcodage gRPC.

Le corps de la requête doit être un objet JSON contenant un tableau requests. Chaque objet de ce tableau est un CreateSelectedRouteRequest qui définit une ressource SelectedRoute individuelle.

L'exemple de code suivant montre la structure d'une requête POST au point de terminaison batchCreate :

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -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:batchCreate"

En cas de succès, l'API renvoie une réponse contenant un tableau des SelectedRoute ressources créées.

L'exemple de code suivant montre la structure d'une batchCreate réponse du point de terminaison :

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Créer une route avec des points de cheminement intermédiaires

Pour créer une route qui passe par des points spécifiques entre l'origine et la destination, incluez un intermediates tableau dans l' dynamicRoute objet du corps de votre requête. Chaque élément du intermediates tableau est un point de cheminement défini par sa latitude et longitude. Une route peut comporter jusqu'à 25 points de cheminement.

L'exemple de code suivant montre comment créer un SelectedRoute avec des points de cheminement intermédiaires :

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

Utiliser des attributs de route personnalisés

Pour améliorer la gestion des routes et l'analyse des données dans Insights de gestion des routes, l'objet SelectedRoute inclut un champ route_attributes.

Utilisez le routeAttributes champ pour définir vos propres propriétés personnalisées pour des routes individuelles, où chaque attribut est une paire clé-valeur. Vous pouvez fournir jusqu'à 10 paires clé-valeur personnalisées par route.

Ces attributs sont utiles pour identifier des routes spécifiques ou pour regrouper des routes en fonction de critères pertinents pour vos besoins.

Voici quelques exemples d'attributs de route que vous pouvez utiliser :

"road_classification": "highway"
"maintenance_zone": "north_district"
"event_id": "marathon_2024"
"pavement_type": "asphalt"

Suivez les consignes ci-dessous lorsque vous définissez le routeAttributes champ :

Les clés ne doivent pas commencer par le préfixe goog.
La longueur de chaque clé et de chaque valeur ne doit pas dépasser 100 caractères.

Vous pouvez ensuite utiliser ces routeAttributes personnalisés dans Insights de gestion des routes de plusieurs manières :

Filtrer les notifications Pub/Sub : vous pouvez définir des filtres sur vos abonnements Pub/Sub pour ne recevoir des mises à jour que pour les routes qui correspondent ou non à des clés d'attribut spécifiques et à leurs valeurs correspondantes.
Affiner l'analyse BigQuery : dans vos tables BigQuery, vous pouvez utiliser ces attributs pour filtrer des routes spécifiques en fonction de la valeur d'un attribut. Vous pouvez également regrouper les routes par clé d'attribut spécifique pour une analyse de données plus ciblée.

L'exemple de code suivant montre comment créer un SelectedRoute avec des routeAttributes personnalisés.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"