Używanie masek pól

Maski pól umożliwiają wywołującym interfejs API wyświetlanie listy pól, które powinny być zwracane lub aktualizowane przez żądanie. Użycie FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. W przypadku metod odczytu i aktualizacji w interfejsie Google Sheets API używana jest maska pola.

Odczytywanie za pomocą maski pola

Arkusz kalkulacyjny może być duży, a często nie potrzebujesz wszystkich części zasobu Spreadsheet zwracanego przez żądanie odczytu. Możesz ograniczyć to, co jest zwracane w odpowiedzi interfejsu Sheets API, za pomocą parametru URL fields. Aby uzyskać najlepszą wydajność, w odpowiedzi wymień tylko te pola, których potrzebujesz.

Format parametru fields jest taki sam jak kodowanie JSON elementu FieldMask. Krótko mówiąc, różne pola są rozdzielone przecinkami, a pola podrzędne – kropkami. Nazwy pól można podawać w formacie camelCase lub separated_by_underscores. Dla wygody wiele pól podrzędnych tego samego typu można umieścić w nawiasach.

Ten przykład żądania spreadsheets.get używa maski pola sheets.properties(sheetId,title,sheetType,gridProperties), aby pobrać tylko identyfikator arkusza, tytuł,SheetType iGridProperties obiektu SheetProperties we wszystkich arkuszach w arkuszu kalkulacyjnym:

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

Odpowiedzią na to wywołanie metody jest obiekt Spreadsheet zawierający komponenty żądane w masce pola. Uwaga:sheetType=OBJECT nie zawiera gridProperties:

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

Aktualizowanie za pomocą maski pola

Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, pozostawiając inne pola bez zmian. Żądania aktualizacji w ramach operacji spreadsheets.batchUpdate używają masek pól, aby poinformować interfejs API, które pola są zmieniane. Żądanie aktualizacji ignoruje wszystkie pola, które nie są określone w masce pola, i pozostawia w nich bieżące wartości.

Możesz też usunąć pole, nie określając go w zaktualizowanej wiadomości, ale dodając je do maski. Spowoduje to usunięcie wartości, która była wcześniej w tym polu.

Składnia masek pól aktualizacji jest taka sama jak w przypadku masek pól odczytu.

W poniższym przykładzie użyto elementu AddSheetRequest do dodania nowego arkusza typu Grid, zablokowania pierwszego wiersza i pokolorowania na czerwono karty nowego arkusza:

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
            }
          }
        }
      }
    }
  ]
}