Les masques de champ permettent aux appelants d'API de lister les champs qu'une requête doit renvoyer ou mettre à jour. L'utilisation d'un FieldMask permet à l'API d'éviter tout travail inutile et d'améliorer les performances. Un masque de champ est utilisé pour les méthodes de lecture et de mise à jour dans l'API Google Docs.
Lire avec un masque de champ
Les documents peuvent être volumineux, et vous n'avez souvent pas besoin de chaque partie de la ressource Document renvoyée par une requête de lecture. Vous pouvez limiter les éléments renvoyés dans une réponse de l'API Docs à l'aide du paramètre d'URL fields. Pour des performances optimales, listez explicitement uniquement 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 bref, plusieurs champs différents sont séparés par des virgules et les sous-champs sont séparés par des points. Les noms de champs peuvent être spécifiés au format camelCase ou 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 documents.get suivant utilise un masque de champ title,tabs(documentTab(body.content(paragraph))),revisionId pour extraire le title du document, le Paragraph d'un objet Body (à partir de tous les onglets) et le revisionId du document dans un document :
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(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",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}Mettre à jour avec un masque de champ
Il arrive que vous deviez mettre à jour uniquement certains champs d'un objet en laissant les autres inchangés. Les requêtes de mise à jour dans une opération documents.batchUpdate utilisent des masques de champ pour indiquer à l'API les champs qui doivent être 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 annuler la définition d'un champ en ne le spécifiant pas dans le message mis à jour, mais en l'ajoutant au masque. La valeur précédente du champ est effacée.
La syntaxe des masques de champ de mise à jour est identique à celle des masques de champ de lecture.
L'exemple suivant utilise UpdateTextStyleRequest pour mettre en gras les mots "API Google Docs" dans le document, dans les range 5 à 20 :
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"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
},
}
}
],
}