Choisir les informations à renvoyer

Lorsque vous appelez une méthode pour calculer un itinéraire ou une matrice d'itinéraires, vous devez spécifier les informations souhaitées en listant 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 de champs en créant un masque de champ de réponse. Vous transmettez ensuite le masque de champ de réponse à l'une des méthodes à l'aide du paramètre d'URL $fields ou fields, ou à l'aide de l'en-tête HTTP ou gRPC X-Goog-FieldMask.

Le masquage de champ est une bonne pratique à appliquer pour vous assurer de ne pas demander de données inutiles. Vous pourrez ainsi réduire le temps de traitement et les 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 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 des points.

Créez et spécifiez un chemin de champ comme suit:

1. Recherchez les champs contenant les informations dont vous avez besoin dans l'API Routes. Pour en savoir plus, consultez Références de champ.
2. Déterminez les chemins 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 que vous souhaitez utiliser.

3. Combinez les masques de champ pour tous les champs dont vous avez besoin, en les séparant par des virgules. Par exemple, pour demander le distanceMeters de l'étape du parcours, ainsi que la durée de chaque étape du parcours, saisissez-les tous les deux, séparés par une virgule, sans espace:

   routes.legs.distanceMeters,routes.legs.steps.duration

4. 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 et X-Goog-FieldMask:

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

Pour obtenir des exemples et en savoir plus, consultez les sections suivantes.

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 références de l'API Routes indiquées dans la liste suivante. Spécifiez les champs en casse camel, comme indiqué dans la documentation de référence. Par exemple, routePreference.

En revanche, vous devez saisir les valeurs des paramètres comme indiqué. Par exemple, pour routingPreference, vous devez saisir TRAFFIC_AWARE.

Ces références incluent les champs disponibles. Toutefois, vous devez vous reporter à la hiérarchie des champs pour déterminer le chemin d'accès complet du masque de champ. Pour savoir comment obtenir la hiérarchie des champs, consultez Déterminer le masque de champ que vous souhaitez utiliser.

• Calculer le masque de champ de route
  • REST: spécifie les champs de l'objet Route dans la réponse à renvoyer, préfixés par routes., par exemple routes.distanceMeters.
  • gRPC: spécifie les champs de l'objet Route dans la réponse à renvoyer.
• Compute route matrix field masks
  • 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.

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:

1. Demandez tous les champs à l'aide d'un masque de champ *.
   Attention:Vous pouvez utiliser ce masque de champ générique en phase de développement pour déterminer les champs dont vous avez besoin, mais ne l'utilisez pas en production. Demander tous les champs en production entraîne des coûts plus élevés et des temps de réponse plus longs. Vos coûts peuvent également augmenter de manière inattendue à mesure que des fonctionnalités avancées sont ajoutées, car ce masque de champ les inclut automatiquement. Demandez plutôt uniquement les champs dont vous avez besoin pour réduire vos coûts et le temps de réponse de votre requête.
2. Recherchez les champs souhaités dans la hiérarchie des champs de la réponse.

3. Créez vos masques de champ en utilisant la hiérarchie des champs affichée à l'étape précédente, selon le format suivant:

   topLevelField[.secondLevelField][.thirdLevelField][...]

   Remarque:N'utilisez pas d'espaces dans la liste des chemins de champ.

Par exemple, pour cette réponse partielle d'un parcours:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Si vous ne souhaitez renvoyer que le champ distanceMeters pour l'étape du parcours, c'est-à-dire le dernier distanceMeters de l'exemple précédent, votre masque de champ est le suivant:

routes.legs.distanceMeters

Si vous souhaitez plutôt renvoyer le champ distanceMeters pour chaque étape de l'itinéraire, c'est-à-dire le distanceMeters sous steps dans l'exemple précédent, votre masque de champ est le suivant:

routes.legs.steps.distanceMeters

Si vous souhaitez renvoyer les deux, avec le résultat ci-dessus, votre masque de champ est le suivant:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Exemples de chemins de masque de champ

Cette section contient d'autres exemples sur la façon de spécifier un chemin de champ dans un masque de champ de réponse dans les appels REST et gRPC.

Appel REST vers 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 distanceMeters et duration de l'itinéraire dans la réponse. N'oubliez pas de préfixer le nom du champ par routes.

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

Appel REST vers computeRouteMatrix

Pour la méthode REST computeRouteMatrix utilisée pour calculer une matrice de calcul d'itinéraires, dans l'en-tête, spécifiez de renvoyer originIndex, destinationIndex et duration pour chaque combinaison d'origine et de 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 aux champs

N'incluez que les champs dont vous avez besoin dans la réponse pour renvoyer uniquement les champs dont vous avez besoin:

• Réduit les temps de traitement, ce qui permet de renvoyer vos résultats avec une latence plus faible.
• Assure des performances de latence stables. 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 de nouveaux champs sont ajoutés et automatiquement inclus dans votre réponse.
• Résulte en une taille de réponse plus petite, ce qui se traduit par un débit réseau plus élevé.
• Vous assurez de ne pas demander de données inutiles, ce qui permet de réduire le temps de traitement et les frais facturés.

Remarque:Lorsqu'un message de réponse est analysé et qu'un champ du message de réponse contient sa valeur par défaut, le champ peut être omis de la réponse, même si vous l'avez spécifié dans le masque de champ de la réponse. Pour en savoir plus, consultez le guide du langage (proto3). Par exemple, lorsque vous calculez une matrice de calcul d'itinéraires, le champ distanceMeters de la réponse peut contenir la valeur 0, sa valeur par défaut. Étant donné que 0 est la valeur par défaut de distanceMeters, il est omis de la réponse.

Pour en savoir plus sur la création d'un masque de champ, consultez field_mask.proto.

Demander un jeton de parcours

Pour demander à l'API Routes de renvoyer des jetons de parcours pour les parcours générés, procédez comme suit:

1. Définissez les paramètres suivants, qui sont obligatoires pour renvoyer un jeton de parcours :
   • Définissez travelMode sur DRIVE.
   • Définissez routingPreference sur TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
2. Vérifiez qu'aucun de vos points de cheminement de route n'est un point de cheminement via.
3. Spécifiez le masque de champ routes.routeToken pour renvoyer un jeton de parcours:

   X-Goog-FieldMask: routes.routeToken

Remarque:En raison des conditions routières dynamiques, les itinéraires générés avec un jeton donné peuvent différer de l'itinéraire planifié. Pour minimiser les différences, utilisez le jeton dans les minutes qui suivent sa génération.

Vous pouvez utiliser le jeton de route 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 itinéraire à une seule origine et une seule destination, utilisant 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.routeToken,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.