Choisir les informations à retourner
Lorsque vous appelez une méthode pour calculer une route ou une matrice de routage, vous devez spécifier les informations souhaitées en indiquant les champs que vous souhaitez 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.
Pour spécifier la liste des champs, créez 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. Cela permet d'éviter des temps de traitement inutiles et des frais facturés.
Pour en savoir plus sur les paramètres d'URL, consultez la section 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 séparé par un point vers le champ spécifié.
Pour construire un chemin d'accès de champ, procédez comme suit:
topLevelField[.secondLevelField][.thirdLevelField][...]
- Masque de champ de routage de calcul
- Masques de champ de la matrice de routage Compute
- REST: spécifie les champs du corps de la réponse à renvoyer.
- gRPC: spécifie les champs de l'objet RouteMatrixElement dans la réponse à renvoyer.
Pour en savoir plus sur la construction de masques de champ, consultez le fichier field_mask.proto.
Déterminer les masques de champ à utiliser
Voici comment déterminer les masques de champ que vous souhaitez utiliser:
- Demandez tous les champs à l'aide d'un masque de champ de
*
. - Examinez la hiérarchie des champs dans la réponse et déterminez les champs qui vous intéressent.
- Créez votre masque de champ à l'aide de la hiérarchie des champs.
Par exemple, pour cette réponse partielle d'un itinéraire de transports en commun:
"routes": [ { "legs": [ { "distanceMeters": 12886, } ... ]}]
Si vous souhaitez ne renvoyer que le champ distanceMeters
, votre masque de champ est le suivant:
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 de champ
Cette section contient des exemples de spécification d'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 d'ajouter le préfixe routes
au nom du champ.
-H X-Goog-FieldMask: routes.distanceMeters,routes.duration
Appel REST à computeRouteMatrix
Pour la méthode REST computeRouteMatrix
permettant de calculer une matrice de routage, indiquez dans l'en-tête de renvoyer originIndex
, destinationIndex
et duration
pour chaque combinaison de points 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:
- Diminue les temps de traitement pour que vos résultats soient renvoyés avec une latence plus faible.
- Garantit des performances de latence stables si l'API ajoute des champs de réponse supplémentaires à l'avenir, et que ces nouveaux champs nécessitent du temps de calcul supplémentaire. Si vous sélectionnez tous les champs ou 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.
- La taille des réponses est réduite, ce qui se traduit par un débit réseau plus élevé.
- Elle garantit que vous ne demandez pas de données inutiles, ce qui permet d'éviter des temps de traitement inutiles et des frais facturés.
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:
- Définissez
travel_mode
surDRIVING
. - Définissez
routing_preference
surTRAFFIC_AWARE
ouTRAFFIC_AWARE_OPTIMAL
. - Vérifiez qu'aucun de vos points de cheminement n'est défini sur
via
. - Spécifiez le masque de champ du jeton de routage :
-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 une route à un seul point de départ et à destination unique, qui 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.