Masques de champ

L'API REST Ad Manager utilise des masques de champ pour les lectures et les écritures partielles. Cela peut améliorer les performances en limitant la quantité de données transférées. Masques de champ sont représentés par une liste de noms de champs séparés par une virgule. Exemple :

startTime,endTime,targeting.geoTargeting

Lire les masques

Les masques de lecture contrôlent les champs présents dans une réponse d'API. Vous pouvez définir un masque de lecture sur votre requête de deux manières:

1. Le paramètre de requête fields:

   curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize
   

2. L'en-tête HTTP X-Goog-FieldMask:

   curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
       https://admanager.googleapis.com/v1/networks/123456/adUnits
   

Remarque :camelCase et snake_case sont tous deux acceptés dans les chaînes de masque de champ.

Masques de lecture par défaut

Certaines méthodes d'API incluent un masque de champ par défaut pour les champs coûteux à renvoyer. Les méthodes de liste en sont un exemple. Par défaut, ils n'incluent pas le totalSize .

Ces champs doivent être explicitement demandés dans le masque de champ, soit par nom, soit par à l'aide du caractère générique *.

Mettre à jour les masques

Les masques de mise à jour contrôlent les champs qui seront modifiés lors d'une mise à jour (PATCH) requête. Lorsqu'un masque de mise à jour est défini, seuls les champs du masque sont mis à jour quels que soient les champs définis dans le corps de la requête.

Les masques de mise à jour sont définis en tant que paramètres de requête. Exemple :

curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName

Balayage de champ

Les masques de champ peuvent spécifier des champs au sein d'une entité à l'aide du caractère . pour le balayage de l'écran. Il s’agit de la même syntaxe utilisée par Filtres :

Les masques de champ sont toujours relatifs à l'objet de réponse. Par exemple, un masque pour la lecture d'un LineItem peut inclure primaryGoal.units. Le masque correspondant pour fiche LineItems est lineItems.primaryGoal.units.

Vous pouvez spécifier un champ dans son ensemble ou l'un de ses sous-champs. Les deux primaryGoal et primaryGoal.units sont des valeurs correctes.

Cela s'applique également aux champs répétés. Un masque de champ LineItem de creativePlaceholders.size est valide et n'inclut que le champ size. pour chaque CreativePlaceholder.

Remarque :Les masques de champ ne permettent pas d'accéder à un élément particulier d'une champ par index. Cela entraîne une erreur INVALID_ARGUMENT.

Caractères génériques

Avertissement :L'utilisation d'un caractère générique dans un masque de mise à jour n'est pas compatible avec le transfert. La générique efface tous les champs que votre client ne reconnaît pas.

Les masques de champ acceptent le caractère *, qui indique tous les champs du message. Les exemples suivants illustrent l'utilisation de caractères génériques pour listing Orders Cette méthode dispose d'un masque de lecture par défaut qui effectue n'incluez pas le champ total_size.

Exemple	Signification
*	Inclut tous les champs, y compris total_size
orders	Inclut uniquement le champ orders et tous ses sous-champs
orders.*	Inclut uniquement le champ orders et tous ses sous-champs

Champs non valides

Si un masque de champ fait référence à une valeur inexistante, l'API répond avec une erreur INVALID_ARGUMENT.