Développeurs de l'Espace économique européen (EEE)

Choisir les champs à renvoyer

Lorsque vous demandez un itinéraire ou une matrice d'itinéraires, vous devez utiliser un masque de champ pour spécifier les informations que la réponse doit renvoyer. Il n'existe pas de liste par défaut de champs renvoyés. Si vous ne spécifiez pas de masque de champ, les méthodes renvoient une erreur.

L'utilisation d'un masque de champ vous permet également de ne pas demander de données inutiles, ce qui contribue à réduire la latence de la réponse et à éviter de renvoyer des informations dont votre système n'a pas besoin.

Vous spécifiez la liste des champs dont vous avez besoin dans un masque de champ de réponse. Vous transmettez ensuite le masque de champ de réponse à l'une ou l'autre 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.

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 d'accès spécifie un champ unique dans le message de réponse. Le chemin d'accès commence par le message de réponse de premier niveau et utilise un chemin d'accès séparé par un point vers le champ spécifié.

Créez et spécifiez un chemin d'accès à un champ comme suit :

  1. Recherchez les champs contenant les informations dont vous avez besoin. Pour en savoir plus, consultez Références de champ.
  2. Déterminez les chemins d'accès aux 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.

  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 de l'itinéraire, ainsi que la durée de chaque étape de l'itinéraire, saisissez les deux valeurs, séparées 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 spécifiez 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 plus d'informations, consultez les sections suivantes.

Références de champ

Pour afficher les champs que vous pouvez demander dans une réponse via des masques de champ, consultez les références Compute Routes ou Compute Route Matrix de l'API Routes, dont les liens figurent dans la liste suivante. Spécifiez les champs en camel case, comme indiqué dans la référence. Par exemple, routePreference.

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 en savoir plus sur l'obtention de la hiérarchie des champs, consultez Déterminer le masque de champ à utiliser.

  • Masque de champ Compute Routes
    • 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 Compute Route Matrix

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 *.
  2. Examinez la hiérarchie des champs dans la réponse pour les champs souhaités.

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

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

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

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

Si vous ne souhaitez renvoyer que le champ distanceMeters pour l'étape de l'itinéraire, 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 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 d'accès aux masques de champ

Cette section contient d'autres exemples sur la façon de spécifier un chemin d'accès à un 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 à la computeRoutes méthode 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 faire précéder le nom du champ de routes.

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, 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"
)

Points à prendre en compte concernant les chemins d'accès aux champs

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

  • 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 vous sélectionnez tous les champs ou tous les champs de premier niveau, vous risquez de constater une dégradation des performances lorsque de nouveaux champs sont ajoutés et inclus automatiquement dans votre réponse.
  • Réduit la taille de la réponse, ce qui se traduit par un débit réseau plus élevé.
  • Vous permet de ne pas demander de données inutiles, ce qui contribue à réduire le temps de traitement et les frais facturés.

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