Choisissez les informations à retourner

Lorsque vous appelez une méthode pour calculer un itinéraire ou une matrice de routage, vous devez spécifier les informations souhaitées en indiquant les champs à renvoyer dans la réponse. Il n'existe pas de liste par défaut des champs renvoyés. Si vous omettez cette liste, les méthodes renvoient une erreur.

Vous spécifiez la liste des champs en créant un masque de champ de réponse. Vous transmettez ensuite le masque de champ de réponse à l'une ou l'autre méthode à l'aide du paramètre d'URL $fields ou fields, ou de l'en-tête HTTP ou gRPC X-Goog-FieldMask.

Le masquage de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter les temps de traitement et les frais facturés inutiles.

Pour en savoir plus sur les paramètres d'URL, consultez Paramètres système.

Définir un masque de champ de réponse

Le masque de champ de réponse est une liste de chemins d'accès séparés par une virgule, où chaque chemin spécifie un champ unique dans le message de réponse. Le chemin d'accès commence à partir du message de réponse de premier niveau et utilise un chemin d'accès au champ spécifié, séparé par un point.

Créez un chemin d'accès de champ comme suit:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Masque de champ de routage de calcul
    • REST: spécifie les champs de l'objet Route dans la réponse à renvoyer, précédés de routes. (par exemple, routes.distanceMeters).
    • gRPC: spécifie les champs de l'objet Route dans la réponse à renvoyer.
  • Masques de champ de la matrice de routage Compute

Pour en savoir plus sur la construction de masques de champ, consultez le fichier field_mask.proto.

Déterminer les masques de champ à utiliser

Pour déterminer les masques de champ que vous souhaitez utiliser, procédez comme suit:

  1. Demandez tous les champs à l'aide d'un masque de champ de *.
  2. Examinez la hiérarchie des champs dans la réponse et déterminez les champs souhaités.
  3. Créez votre masque de champ à l'aide de la hiérarchie de champs.

Par exemple, pour cette réponse partielle d'un itinéraire en transports en commun:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Si vous souhaitez ne renvoyer que le champ distanceMeters, votre masque de champ se présente comme suit:

routes.legs.distanceMeters

Autre exemple. Pour renvoyer tout ce qui se trouve sous legs dans la réponse, votre masque de champ est le suivant :

routes.legs

Spécifier un chemin d'accès à un champ

Cette section contient des exemples sur la manière de spécifier un chemin d'accès de champ dans un masque de champ de réponse.

Appel REST à computeRoutes

Dans le premier exemple, vous utilisez un appel REST à la méthode computeRoutes pour calculer un itinéraire. Dans cet exemple, dans l'en-tête, vous spécifiez des masques de champ pour renvoyer les champs Route.distanceMeters et Route.duration dans la réponse. N'oubliez pas de faire précéder le nom du champ par routes.

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

Appel REST à computeRouteMatrix

Pour la méthode REST computeRouteMatrix utilisée pour calculer une matrice d'itinéraires, indiquez dans l'en-tête de renvoyer originIndex, destinationIndex et duration pour chaque combinaison de point de départ et de destination:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

appel gRPC

Pour gRPC, définissez une variable contenant le masque de champ de réponse. Vous pouvez ensuite transmettre cette variable à la requête.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Remarques concernant les chemins d'accès aux champs

Incluez uniquement les champs dont vous avez besoin dans la réponse. Renvoyez uniquement les champs dont vous avez besoin:

  • Réduit les temps de traitement, de sorte que vos résultats sont renvoyés avec une latence plus faible.
  • Garantit des performances de latence stables si l'API ajoute d'autres champs de réponse à l'avenir et que ces nouveaux champs nécessitent un temps de calcul supplémentaire. Si vous sélectionnez tous les champs ou que vous sélectionnez tous les champs au niveau supérieur, vous risquez de constater une dégradation des performances lorsque tous les nouveaux champs sont automatiquement inclus dans votre réponse.
  • Cela réduit la taille de réponse, ce qui se traduit par un débit réseau plus élevé.
  • Ne demandez pas de données inutiles, ce qui permet d'éviter des temps de traitement et des frais facturés inutiles.

Demander un jeton de routage

Pour demander à l'API Routes de renvoyer des jetons de routage pour les routes générées, suivez les exigences pour renvoyer un jeton de routage, puis utilisez le masque de champ routes.route_token pour demander le jeton:

  1. Définissez travel_mode sur DRIVING.
  2. Définissez routing_preference sur TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
  3. Vérifiez qu'aucun de vos points de cheminement de l'itinéraire n'est un point de cheminement via.
  4. Spécifiez le masque de champ du jeton de route :
    -H X-Goog-FieldMask: routes.route_token

Vous pouvez utiliser votre itinéraire planifié dans le SDK Navigation. Pour en savoir plus, consultez Planifier un itinéraire (Android) ou Planifier un itinéraire (iOS).

Exemple de jeton de route

Voici un exemple de corps de requête cURL pour un seul point de départ et une seule destination. Il utilise des masques de champ pour demander un jeton d'itinéraire, ainsi que la durée, la distance et la polyligne de l'itinéraire:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Pour en savoir plus, consultez la documentation de référence de l'API Compute Routes.