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 des 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 permet également de s'assurer que vous ne demandez pas 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é.

Construisez 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 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.

  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 la distanceMeters de la section de l'itinéraire, ainsi que la durée de chaque étape de la section 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 en savoir plus, consultez les sections suivantes.

Références de champ

Pour afficher les champs que vous pouvez demander dans une réponse à l'aide de masques de champ, consultez les références Compute Routes ou Compute Routes Matrix de l'API Routes, dont les liens figurent dans la liste suivante. Spécifiez les champs en camel case, 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 au masque de champ. Pour savoir comment obtenir la hiérarchie des champs, consultez Déterminer le masque de champ à utiliser.

  • Masque de champ ComputeRoute
    • 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 à 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 trouver les champs qui vous intéressent.

  3. Créez vos masques de champ en utilisant la hiérarchie des champs affiché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 ne souhaitez renvoyer que le champ distanceMeters pour la section 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 du tronçon de route (c'est-à-dire le champ 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 distanceMeters et duration de l'itinéraire 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 de routes, spécifiez dans l'en-tête 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 :

  • Réduit les temps de traitement, ce qui permet de renvoyer vos résultats avec une latence plus faible.
  • Garantit 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 inclus automatiquement dans votre réponse.
  • La taille de la réponse est plus petite, ce qui se traduit par un débit réseau plus élevé.
  • Vous évitez ainsi de demander des données inutiles, ce qui permet de 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 field_mask.proto.