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. Avec 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 Sheets.

Lire avec un masque de champ

Les feuilles de calcul peuvent être volumineuses et, bien souvent, vous n'avez pas besoin de toutes les parties Spreadsheet ressource renvoyée par une requête de lecture. Vous pouvez limiter ce qui est renvoyé Réponse de l'API Sheets, à l'aide du paramètre d'URL fields. Pour un meilleur les performances, n'indiquer explicitement que les champs dont vous avez besoin. dans la réponse.

Le format du paramètre "fields" est identique à celui du paramètre 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 champs peuvent être spécifiés en camelCase ou separated_by_underscores. Pour plus de commodité, plusieurs sous-champs du même peut être indiqué entre parenthèses.

Les éléments suivants : Demande spreadsheets.get l'exemple utilise un masque de champ de sheets.properties(sheetId,title,sheetType,gridProperties) pour récupérer uniquement l'ID, le titre, SheetType GridProperties d'un SheetProperties. sur toutes les feuilles d'une feuille de calcul:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

La réponse à cet appel de méthode Spreadsheet contenant les composants demandés dans le masque de champ. Notez que sheetType=OBJECT ne contient pas gridProperties:

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

Mettre à jour avec un masque de champ

Parfois, vous ne devez mettre à jour que certains champs d'un objet tout en laissant et les autres champs restent inchangés. Les requêtes de mise à jour dans un spreadsheets.batchUpdate opération utilise des masques de champ pour indiquer à l'API quels champs sont modifiés. La "update request" ignore les champs non spécifiés dans le masque de champ. en leur laissant leurs valeurs actuelles.

Vous pouvez aussi annuler la définition d'un champ en ne le spécifiant pas dans le message mis à jour, en ajoutant le champ au masque. La valeur du champ précédente est effacée dont il disposait.

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 de * est traité comme un caractère générique. et permet de spécifier chaque champ dans un message. La syntaxe du caractère générique peut produire des résultats indésirables si l'API est mise à jour ultérieurement, car l'accès et ceux qui viennent d'être ajoutés peuvent provoquer des erreurs. Pour les applications de production, Indiquez toujours les champs spécifiques mis à jour dans des masques de champ et évitez d'utiliser *. et utiliser des caractères génériques.

L'exemple suivant utilise la classe AddSheetRequest pour ajouter une nouvelle feuille de type Grid, figez la première ligne et colorez la nouvelle onglet rouge de la feuille:

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate

{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}