Les masques de champ permettent aux appelants de l'API de répertorier 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 améliore les performances. Un masque de champ est utilisé 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, dans la plupart des cas, vous n'avez pas besoin de chaque partie de la ressource Presentation
renvoyée par une requête de lecture. Vous pouvez limiter le contenu renvoyé dans une réponse de l'API Slides à l'aide du paramètre d'URL fields
. Pour des performances optimales, répertoriez explicitement les champs dont vous avez besoin dans la réponse.
Le format du paramètre "fields" est identique à l'encodage JSON d'un masque de champ FieldMask. En bref, plusieurs champs différents sont séparés par une virgule et les sous-champs sont séparés par des points. Les noms de champ peuvent être spécifiés au format camelCase ou Separate_by_underscores. Pour plus de commodité, plusieurs sous-champs du même type peuvent être répertoriés entre parenthèses.
L'exemple de requête presentations.get
suivant utilise un masque de champ de slides.pageElements(objectId,size,transform)
pour récupérer uniquement l'ID d'objet, Size
et transform 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 devez ne mettre à jour que certains champs d'un objet tout en laissant les autres champs inchangés. Les requêtes de mise à jour dans une opération presentations.batchUpdate
utilisent des masques de champ pour indiquer à l'API quels champs sont modifiés. La requête de mise à jour ignore les champs qui ne sont pas spécifiés dans le masque de champ et leur attribue leurs valeurs actuelles.
Vous pouvez également annuler la définition d'un champ en le spécifiant au masque, et non en le spécifiant dans le message mis à jour. La valeur précédemment définie pour le champ est alors 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 le remplissage de couleur d'une forme par la couleur de thème DARK1
et annuler la définition du 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"
}
}
]
}