Używanie masek pól

Maski pól umożliwiają wywołującym interfejs API listę pól, które powinny zostać wysłane przez żądanie zwrócić lub zaktualizować aplikację. Za pomocą FieldMask umożliwia interfejsowi API unikanie zbędnej pracy i zwiększa wydajność. Maska pola jest używany zarówno do odczytu, jak i do aktualizacji w interfejsie API Arkuszy Google.

Odczyt z maską pola

Arkusze mogą być duże i często nie trzeba Spreadsheet zasobu zwróconego przez żądanie odczytu. Możesz ograniczyć zakres informacji zwracanych w Odpowiedź interfejsu API Arkuszy przy użyciu parametru adresu URL fields. Najlepszy wynik skuteczność reklam, wymieniać tylko te pola, których potrzebujesz. w odpowiedzi.

Format parametru pól jest taki sam jak Kodowanie JSON pola FieldMask. Krótko mówiąc: wiele różnych pól jest rozdzielonych przecinkami, a pola podrzędne są są rozdzielane kropkami. Nazwy pól można podawać w formacie camelCase lub separated_by_underscores. Dla wygody kilka pól podrzędnych z tego samego należy podać w nawiasach.

Poniżej Prośba o: spreadsheets.get przykład użycia maski pola sheets.properties(sheetId,title,sheetType,gridProperties) do pobierz tylko identyfikator arkusza, tytuł SheetType oraz GridProperties z SheetProperties obiekt na wszystkich arkuszach w arkuszu kalkulacyjnym:

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

Odpowiedź na wywołanie tej metody jest Spreadsheet obiekt zawierający komponenty żądane w masce pola. 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"
      }
    }
  ]
}

Zaktualizuj za pomocą maski pola

Czasami wystarczy zaktualizować tylko niektóre pola obiektu, pozostawiając nie zmieniono innych pól. Żądania aktualizacji w tagu spreadsheets.batchUpdate operacji używają masek pól, aby informować interfejs API, które pola są zmieniane. żądanie aktualizacji ignoruje wszystkie pola, które nie zostały określone w masce pola, pozostawiając w nich obecne wartości.

Możesz też cofnąć ustawienie pola, nie określając go w zaktualizowanej wiadomości. przez dodanie pola do maski. Spowoduje to wyczyszczenie wartości pola poprzednio jakie mieliśmy.

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

W poniższym przykładzie użyto parametru AddSheetRequest aby dodać nowy arkusz typu Grid, zablokować pierwszy wiersz i pokolorować nowy czerwona karta 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
            }
          }
        }
      }
    }
  ]
}