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 Slides API.
Odczytywanie z maską pola
Prezentacje mogą być duże i często nie potrzebujesz wszystkich części zasobu Presentation zwróconego przez żądanie odczytu. Za pomocą parametru URL fields możesz ograniczyć zakres zwracanych danych w odpowiedzi interfejsu Slides 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 żądania presentations.get używa maski pola slides.pageElements(objectId,size,transform), aby pobrać tylko identyfikator obiektu Size i przekształcić obiekt pageElement na wszystkich slajdach w prezentacji:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Odpowiedzią na wywołanie tej metody jest obiekt Presentation zawierający komponenty określone w masce pola:
{
"slides": [
{
"pageElements": [
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311708,
"translateY": 744575,
"unit": "EMU"
}
},
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311700,
"translateY": 2834125,
"unit": "EMU"
}
}
]
}
]
}Aktualizacja za pomocą maski pola
Czasami trzeba zaktualizować tylko niektóre pola obiektu, pozostawiając inne bez zmian. Żądania aktualizowania w ramach operacji presentations.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żyto funkcji UpdateShapePropertiesRequest do zmiany koloru wypełnienia kształtu na kolor motywu DARK1 i usunięcia konturów kształtu:
POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{
"requests": [
{
"updateShapeProperties": {
"objectId": OBJECT_ID,
"shapeProperties": {
"shapeBackgroundFill": {
"solidFill": {
"color": {
"themeColor": "DARK1"
}
}
}
},
"fields": "shapeBackgroundFill.solidFill.color,outline"
}
}
]
}