Les masques de champ permettent aux appelants d'API de répertorier les champs qu'une requête doit renvoyer ou mettre à jour. L'utilisation de FieldMask permet à l'API d'éviter des tâches inutiles et d'améliorer les performances. Un masque de champ est utilisé pour les méthodes de lecture et de mise à jour de l'API Google Docs.
Lire avec un masque de champ
Les documents peuvent être volumineux et, bien souvent, vous n'avez pas besoin que chaque partie de la ressource Document soit renvoyée par une requête de lecture. Vous pouvez limiter ce qui est renvoyé dans une réponse de l'API Docs à l'aide du paramètre d'URL fields. Pour des performances optimales, n'indiquez explicitement que les champs dont vous avez besoin dans la réponse.
Le format du paramètre "fields" est identique à celui de l'encodage JSON d'un paramètre FieldMask. En bref, plusieurs champs différents sont séparés par une virgule et les sous-champs sont séparés par un point. Les noms des champs peuvent être spécifiés en camelCase ou en Separate_by_underscores. Pour plus de commodité, vous pouvez placer plusieurs sous-champs du même type entre parenthèses.
L'exemple de requête documents.get suivant utilise un masque de champ title,body.content(paragraph),revisionId pour extraire la title du document, le Paragraph d'un objet Body et le revisionId du document dans un document:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
La réponse à cet appel de méthode est un objet Document contenant les composants demandés dans le masque de champ:
{
"title": ""TITLE",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
Mettre à jour avec un masque de champ
Parfois, vous ne devez 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 documents.batchUpdate utilisent des masques de champ pour indiquer à l'API quels champs sont modifiés. La requête de mise à jour ignore tous les champs qui ne sont pas spécifiés dans le masque de champ, et les conserve avec leurs valeurs actuelles.
Vous pouvez également annuler la définition d'un champ en l'ajoutant au masque plutôt qu'en le spécifiant dans le message mis à jour. Cette opération efface la valeur précédemment attribuée au champ.
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 UpdateTextStyleRequest pour appliquer un style aux mots "API Google Docs" dans le document en gras entre les range 5–20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}