Maski pól umożliwiają wywołującym interfejs API listę pól, które żądanie powinno zwrócić lub zaktualizować. Użycie FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pola służy 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 potrzebujesz wszystkich części zasobu Spreadsheet zwracanych w odpowiedzi na żądanie odczytu. Możesz ograniczyć zawartość zwracaną w odpowiedzi interfejsu Arkuszy Google za pomocą parametru adresu URL fields. Aby uzyskać najlepsze wyniki, wymień w odpowiedzi tylko te pola, których potrzebujesz.
Format parametru fields jest taki sam jak kodowanie JSON elementu FieldMask. Krótko mówiąc: wiele różnych pól jest rozdzielonych przecinkami, a pola podrzędne rozdzielone kropkami. Nazwy pól można podawać w formacie camelCase lub Separate_by_underscores. Dla wygody w nawiasach można podać kilka pól podrzędnych tego samego typu.
Ten przykład żądania spreadsheets.get używa maski pola sheets.properties(sheetId,title,sheetType,gridProperties) do pobrania tylko identyfikatora arkusza, tytułu 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)
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 wystarczy zaktualizować tylko niektóre pola w obiekcie, a pozostałe pola pozostawić bez zmian. Żądania aktualizacji w operacji spreadsheets.batchUpdate wykorzystują maski 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, i pozostawia je z bieżącymi wartościami.
Aby cofnąć ustawienie pola, możesz też nie określać go w zaktualizowanej wiadomości, tylko dodać pole do maski. Powoduje to wyczyszczenie wartości, której poprzednio miało pole.
Składnia masek pól aktualizacji jest taka sama jak masek do odczytu.
Poniższy przykład pokazuje użycie właściwości AddSheetRequest do dodania nowego arkusza typu Grid, zablokowania pierwszego wiersza i pokolorowania karty 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
}
}
}
}
}
]
}