Utiliser des masques de champ

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 un 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 toutes les parties de la Document ressource 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, ne listez explicitement que les champs dont vous avez besoin dans la réponse.

Le format du paramètre "fields" est le même que le encodage JSON d'un 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 de champ peuvent être spécifiés en camelCase ou séparés_par_des_tirets_bas. 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 récupérer 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 Document objet 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

Vous devez parfois ne mettre à jour que certains champs d'un objet en laissant les autres champs inchangés. Les requêtes de mise à jour dans une documents.batchUpdate opération 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 annuler la définition d'un champ en ne le spécifiant pas dans le message mis à jour, mais en l'ajoutant au masque. Cela efface la valeur précédente du champ.

La syntaxe des masques de champ de mise à jour est la même que celle des masques de champ de lecture.

Un masque de champ * est traité comme un caractère générique et est une abréviation pour spécifier chaque champ d'un message. La syntaxe des caractères génériques peut produire des résultats indésirables si l'API est mise à jour à l'avenir, car les champs en lecture seule et les champs nouvellement ajoutés peuvent entraîner des erreurs. Pour les applications de production, listez toujours les champs spécifiques mis à jour dans les masques de champ et évitez d'utiliser des caractères génériques *.

L'exemple suivant utilise les UpdateTextStyleRequest pour mettre en forme les mots "Google Docs API" en gras dans le document dans la 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
        },
      }
    }
  ],
}