Używanie masek pól

Maski pól umożliwiają wywołującym interfejs API wyświetlenie listy pól, które powinny zostać zwrócone lub zaktualizowane w żądaniu. Użycie FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pól jest używana zarówno w metodach odczytu, jak i aktualizacji w interfejsie Google Sheets API.

Odczyt z maską pól

Arkusz kalkulacyjny może być duży, a często nie potrzebujesz wszystkich części zasobu Spreadsheet zwracanych 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 wyraźnie wymień tylko te pola, których potrzebujesz.

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

Poniższy spreadsheets.get przykład żądania używa maski pól sheets.properties(sheetId,title,sheetType,gridProperties)aby pobrać tylko identyfikator arkusza, tytuł, SheetType, i GridProperties 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 Spreadsheet obiekt zawierający komponenty żądane w masce pól. Pamiętaj, że 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"
      }
    }
  ]
}

Aktualizacja z maską pól

Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, a pozostałe pozostawić bez zmian. Żądania aktualizacji w 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 pól, pozostawiając je z ich bieżącymi wartościami.

Możesz też usunąć ustawienie pola, nie określając go w zaktualizowanej wiadomości, ale dodając pole do maski. Spowoduje to usunięcie dotychczasowej wartości pola.

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

Poniższy przykład używa AddSheetRequest, aby dodać nowy arkusz typu Grid, zablokować pierwszy wiersz i pokolorować kartę nowego arkusza na czerwono:

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