Maski pól to sposób na podanie przez wywołujących interfejs API listy pól, które żądanie powinno zwrócić lub zaktualizować. Korzystanie z FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pola jest używana w metodach odczytu i aktualizacji w interfejsie Google Sheets API.
Odczytywanie z maską pola
Arkusze kalkulacyjne mogą być duże i często nie potrzebujesz wszystkich części zasobu Spreadsheet zwróconego przez żądanie odczytu. Za pomocą parametru URL fields możesz ograniczyć zakres zwracanych danych w odpowiedzi interfejsu Sheets API. Aby uzyskać najlepsze wyniki,
w odpowiedzi podaj 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 rozdzielanych przecinkami, a pola podrzędne są rozdzielane kropkami. Nazwy pól mogą być podane w sposób wielka_litera_z_małą lub oddzielone_podkreśleniem. Dla wygody możesz podać w nawiasach wiele pól podrzędnych tego samego typu.
Ten przykład zapytania spreadsheets.get używa maski pola sheets.properties(sheetId,title,sheetType,gridProperties), aby pobrać tylko identyfikator arkusza, tytuł, SheetType i GridProperties obiektuSheetProperties w 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"
}
}
]
}
Aktualizacja za pomocą maski pola
Czasami trzeba zaktualizować tylko niektóre pola obiektu, pozostawiając inne bez zmian. Żądania aktualizowania w ramach operacji spreadsheets.batchUpdate używają masek pól, aby poinformować interfejs API, które pola mają zostać zmienione. Żądanie aktualizacji ignoruje pola, które nie są określone w masce pola, pozostawiając ich bieżące wartości.
Możesz też zresetować pole, nie określając go w zaktualizowanej wiadomości, ale dodając do maski. Spowoduje to usunięcie wartości, która była wcześniej w polu.
Składnia mask pól do aktualizowania jest taka sama jak w przypadku mask pól do odczytu.
W tym przykładzie używamy funkcji AddSheetRequest, aby dodać nowy arkusz typu Grid, zablokować pierwszy wiersz i nadać karminową barwę karcie 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
}
}
}
}
}
]
}