Les masques de champ permettent aux appelants de l'API de lister les champs qu'une requête doit renvoyer ou mettre à jour. L'utilisation d'un FieldMask permet à l'API d'éviter les tâches inutiles et d'améliorer les performances. Un masque de champ est utilisé à la fois pour les méthodes de lecture et de mise à jour dans l'API Google Slides.
Lire avec un masque de champ
Les présentations peuvent être volumineuses, et vous n'avez souvent pas besoin de toutes les parties de la ressource Presentation renvoyée par une requête de lecture. Vous pouvez limiter ce qui est renvoyé dans une réponse de l'API Slides à l'aide du paramètre d'URL fields. Pour de meilleures performances, n'indiquez explicitement que les champs dont vous avez besoin dans la réponse.
Le format du paramètre fields est identique à l'encodage JSON d'un FieldMask. En résumé, plusieurs champs différents sont séparés par une virgule et les sous-champs sont séparés par un point. Les noms de champ peuvent être spécifiés en CamelCase ou en separated_by_underscores. Pour plus de commodité, plusieurs sous-champs du même type peuvent être listés entre parenthèses.
L'exemple de requête presentations.get suivant utilise un masque de champ slides.pageElements(objectId,size,transform) pour ne récupérer que l'ID de l'objet, Size, et la transformation d'un objet pageElement sur toutes les diapositives d'une présentation:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
La réponse à cet appel de méthode est un objet Presentation contenant les composants demandés dans le masque de champ:
{
"slides": [
{
"pageElements": [
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311708,
"translateY": 744575,
"unit": "EMU"
}
},
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311700,
"translateY": 2834125,
"unit": "EMU"
}
}
]
}
]
}Mettre à jour avec un masque de champ
Parfois, vous ne devez mettre à jour que certains champs d'un objet en laissant les autres inchangés. Les requêtes de mise à jour dans une opération presentations.batchUpdate utilisent des masques de champ pour indiquer à l'API les champs qui sont modifiés. La requête de mise à jour ignore les champs non spécifiés dans le masque de champ, en conservant leurs valeurs actuelles.
Vous pouvez également ne pas définir un champ en ne le spécifiant pas dans le message mis à jour, mais en ajoutant le champ au masque. La valeur précédente du champ est effacée.
La syntaxe des masques de champ de mise à jour est la même que celle des masques de champ de lecture.
L'exemple suivant utilise UpdateShapePropertiesRequest pour remplacer la couleur de remplissage d'une forme par la couleur de thème DARK1 et ne définir pas le contour de la forme:
POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{
"requests": [
{
"updateShapeProperties": {
"objectId": OBJECT_ID,
"shapeProperties": {
"shapeBackgroundFill": {
"solidFill": {
"color": {
"themeColor": "DARK1"
}
}
}
},
"fields": "shapeBackgroundFill.solidFill.color,outline"
}
}
]
}