Maski pól umożliwiają osobom wywołującym interfejs API wyświetlanie listy pól, które żądanie powinno zwrócić lub zaktualizować. Użycie FieldMask (FieldMask) pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pola jest używana zarówno w metodach odczytu, jak i aktualizacji w interfejsie API Arkuszy Google.
Czytaj z maską pola
Arkusze kalkulacyjne mogą być duże i często nie potrzebujesz wszystkich części zasobu Spreadsheet
zwracanego w odpowiedzi na żądanie odczytu. Możesz ograniczyć dane zwracane w odpowiedzi interfejsu Arkuszy Google przy użyciu parametru adresu URL fields
. Aby uzyskać jak największą wydajność, w odpowiedzi wymień tylko te pola, których potrzebujesz.
Format parametru fields jest taki sam jak kodowanie JSON obiektu FieldMask. Krótko mówiąc, wiele różnych pól jest rozdzielonych przecinkami, a pola podrzędne – kropkami. Nazwy pól można podać w formacie camelCase lub resolution_by_underscores. Dla wygody możesz podać w nawiasach wiele pól podrzędnych tego samego typu.
W tym przykładzie żądania spreadsheets.get
użyto maski pola sheets.properties(sheetId,title,sheetType,gridProperties)
, aby pobrać tylko identyfikator, tytuł, SheetType
i GridProperties
obiektu SheetProperties
ze wszystkich arkuszy w arkuszu kalkulacyjnym:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
Odpowiedź na to wywołanie metody to obiekt Spreadsheet
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 trzeba zaktualizować tylko niektóre pola w obiekcie, a pozostałe pola pozostawić 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, pozostawiając w nich obecne wartości.
Możesz też cofnąć ustawienie pola, nie określając go w zaktualizowanej wiadomości, ale dodając to pole do maski. Powoduje to usunięcie wartości, które wcześniej miało to pole.
Składnia masek pól aktualizacji jest taka sama jak masek pól do odczytu.
W tym przykładzie użyto AddSheetRequest
, aby dodać nowy arkusz typu Grid
, zablokować pierwszy wiersz i kolorować kartę nowego arkusza na czerwony:
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 } } } } } ] }