Choisir les informations à renvoyer
Lorsque vous appelez une méthode pour calculer une route ou une matrice de routage, vous devez spécifier les informations souhaitées en répertoriant les champs 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
masque de champ de réponse à l'une ou l'autre des méthodes en utilisant le paramètre d'URL $fields
ou
fields
, ou à l'aide de l'en-tête HTTP ou gRPC X-Goog-FieldMask
.
L'utilisation d'un masque de champ est une bonne pratique de conception pour s'assurer que vous ne demandez pas données inutiles, ce qui permet d'éviter le temps de traitement et les frais facturés.
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 path spécifie un champ unique dans le message de réponse. Le chemin commence à partir du message de réponse de niveau supérieur et utilise un un chemin d'accès au champ spécifié, séparé par un point.
Créez et spécifiez un chemin d'accès de champ comme suit:
- Recherchez les champs qui contiennent les informations dont vous avez besoin dans l'API Routes. Pour en savoir plus, consultez Références de champ.
- Déterminez les chemins d'accès des champs dont vous avez besoin et créez les masques de champ correspondants: pour en savoir plus, consultez Déterminer le masque de champ à utiliser.
Combinez les masques de champ pour tous les champs dont vous avez besoin, en les séparant par une virgule. Par exemple, pour demander le
distanceMeters
pour la section de l'itinéraire ainsi que la durée de chaque étape de l'itinéraire, saisissez les deux informations, séparées par une virgule, sans espaces:routes.legs.distanceMeters,routes.legs.steps.duration
Envoyez le masque de champ avec votre requête API. Par exemple, dans une requête cURL, vous devez spécifier le masque de champ avec
-H
etX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Références de champ
Pour connaître les champs que vous pouvez demander dans une réponse à l'aide de masques de champ, consultez les documentations de référence de l'API Routes, dont le lien figure dans la liste suivante. Spécifiez les champs en Camel Case ("casse de chameau"), comme indiqué dans la documentation de référence. Par exemple, routePreference
.
Ces références incluent les champs disponibles : Toutefois, vous devez vous référer à la hiérarchie des champs pour déterminer le chemin d'accès au masque de champ complet. Pour savoir comment obtenir la hiérarchie des champs, consultez Déterminer le masque de champ à utiliser.
- Calculer le masque de champ de route <ph type="x-smartling-placeholder">
- Calculer les masques de champ de la matrice de routes
<ph type="x-smartling-placeholder">
- </ph>
- REST: spécifie les champs du Corps de la réponse à renvoyer.
- gRPC: spécifie les champs du RouteMatrixElement dans la réponse à renvoyer.
Déterminer les masques de champ à utiliser
Voici comment déterminer les champs que vous souhaitez utiliser et créer les masques de champ correspondants:
- Demandez tous les champs à l'aide d'un masque de champ de
*
. - Examinez la hiérarchie des champs dans la réponse de la les champs que vous souhaitez.
Créez vos masques de champ en utilisant la hiérarchie des champs présentée à l'étape précédente, en utilisant le format suivant:
topLevelField[.secondLevelField][.thirdLevelField][...]
Par exemple, pour cette réponse partielle à partir d'une route:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Si vous souhaitez ne renvoyer que le champ distanceMeters
pour la section de l'itinéraire, c'est-à-dire le dernier distanceMeters
de l'échantillon précédent, votre masque de champ se présente comme suit:
routes.legs.distanceMeters
Si vous souhaitez plutôt renvoyer le champ distanceMeters
pour chaque étape de la section de l'itinéraire, c'est-à-dire, distanceMeters
sous steps
dans l'exemple précédent, votre masque de champ se présente comme suit:
routes.legs.steps.distanceMeters
Si vous souhaitez renvoyer les deux, avec le résultat ci-dessus, votre masque de champ se présente comme suit:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Exemples de chemins d'accès au masque de champ
Cette section contient d'autres exemples sur la façon de spécifier un chemin d'accès de champ dans le cadre d'un masque de champ de réponse dans les appels REST et gRPC.
Appel REST à computeRoutes
Dans le premier exemple, vous utilisez un appel REST pour
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 distanceMeters
et duration
de l'itinéraire dans la réponse. N'oubliez pas d'ajouter le préfixe routes
au nom du champ.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
Appel REST à computeRouteMatrix
Pour l'API REST computeRouteMatrix
utilisée pour calculer une matrice de routage, dans l'en-tête, spécifier pour renvoyer
originIndex
, destinationIndex
et duration
pour chaque combinaison d'origines
et destination:
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 des champs
Incluez uniquement les champs dont vous avez besoin dans la réponse pour renvoyer uniquement les dont vous avez besoin:
- Réduit les temps de traitement afin que les résultats soient renvoyés avec une latence plus faible.
- Garantit des performances de latence stables. Si vous sélectionner tous les champs, ou si vous sélectionnez tous les champs au niveau supérieur, vous pouvez les performances se dégradent lorsque de nouveaux champs sont ajoutés automatiquement inclus dans votre réponse.
- La taille de réponse est réduite, ce qui se traduit par un débit réseau plus élevé.
- Elle vous permet de ne pas demander de données inutiles, ce qui permet d'éviter des délais de traitement et des frais facturés inutiles.
Pour en savoir plus sur la création d'un masque de champ, consultez les field_mask.proto.
Demander un jeton de routage
Pour demander que l'API Routes renvoie des jetons de route pour les routes générées, procédez comme suit:
- Définissez les paramètres suivants, qui sont obligatoires pour renvoyer un jeton de route:
<ph type="x-smartling-placeholder">
- </ph>
- Définissez
travelMode
surDRIVE
. - Définissez
routingPreference
surTRAFFIC_AWARE
ouTRAFFIC_AWARE_OPTIMAL
.
- Définissez
- Vérifiez qu'aucun point de cheminement de votre itinéraire n'est
via
. - Spécifiez le masque de champ
routes.routeToken
pour renvoyer un jeton de route:X-Goog-FieldMask: routes.routeToken
Vous pouvez utiliser le jeton d'itinéraire pour 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 point de départ et une destination uniques à l'aide de masques de champ pour demander un jeton d'itinéraire, ainsi que l'itinéraire polyligne de durée, de distance et d'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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
Pour en savoir plus, consultez les Documentation de référence de l'API Compute Routes