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

Sélectionner 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 des champs renvoyés. Si vous ne spécifiez pas de masque de champ, les méthodes renvoient une erreur.

Le masquage de champ vous permet également de ne pas demander de données inutiles, ce qui contribue à réduire la latence des réponses 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 méthode à 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 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 des points vers le champ spécifié.

Créez et spécifiez un chemin de 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 que vous souhaitez utiliser.

  3. Combinez les masques de champ pour tous les champs dont vous avez besoin, en les séparant par une virgule. Par exemple, pour demander la distanceMeters de l'étape de l'itinéraire, ainsi que la durée de chaque étape de l'itinéraire, saisissez les deux, 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 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 plus de détails, consultez les sections suivantes.

Références de champ

Pour voir 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 Compute Routes ou Compute Route Matrix, accessibles via les liens de la liste suivante. Spécifiez les champs en camelCase, 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 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 que vous souhaitez utiliser.

  • Masque de champ de calcul d'itinéraire
    • 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 à renvoyer dans la réponse.
  • 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 en utilisant la hiérarchie des champs indiquée à l'étape précédente, au 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 souhaitez ne 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 plutôt renvoyer le champ distanceMeters pour chaque étape de l'é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 de spécification d'un chemin de champ dans 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 méthode computeRoutes pour calculer un itinéraire. Dans cet exemple, vous spécifiez des masques de champ dans l'en-tête pour renvoyer les champs d'itinéraire distanceMeters et duration dans la réponse. N'oubliez pas de faire précéder le nom du champ par 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, spécifiez dans l'en-tête que vous souhaitez renvoyer originIndex, destinationIndex et duration pour chaque combinaison de point de départ et de destination :

X-Goog-FieldMask: originIndex,destinationIndex,duration

Appel gRPC vers computeRoutes

Pour la méthode gRPC computeRoutes utilisée pour calculer un itinéraire, définissez une variable contenant le masque de champ de réponse afin de renvoyer les champs distanceMeters, duration et de polyligne encodée de l'itinéraire dans la réponse. Vous pouvez ensuite transmettre cette variable à la requête :

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

Appel gRPC vers computeRouteMatrix

Pour la méthode gRPC computeRouteMatrix utilisée pour calculer une matrice d'itinéraires, définissez une variable contenant le masque de champ de réponse pour spécifier le renvoi de originIndex, destinationIndex et duration pour chaque combinaison de point de départ et de destination. Vous pouvez ensuite transmettre cette variable à la requête :

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

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 dont vous avez besoin :

  • Réduction des temps de traitement, ce qui permet de renvoyer les résultats avec une latence plus faible.
  • Garantit des performances de latence stables. Si vous sélectionnez tous les champs, ou si vous sélectionnez tous les champs au niveau supérieur, vous risquez de constater une dégradation des performances lorsque de nouveaux champs sont ajoutés, puis automatiquement inclus dans votre réponse.
  • Réduit la taille de la réponse, ce qui se traduit par un débit réseau plus élevé.
  • S'assurer que vous ne demandez pas de données inutiles, ce qui permet d'éviter des temps de traitement et des frais de facturation inutiles.

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