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 jest używana do metod odczytu i aktualizowania w interfejsie API Prezentacji Google.
Odczyt z maską pola
Prezentacje mogą być duże i często nie potrzebujesz wszystkich części zasobu Presentation zwracanych w odpowiedzi na żądanie odczytu. Możesz ograniczyć zawartość zwracaną w odpowiedzi interfejsu Slides API, używając 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 presentations.get używa maski pola slides.pageElements(objectId,size,transform) do pobrania tylko identyfikatora obiektu Size oraz przekształcenia obiektu pageElement na wszystkich slajdach prezentacji:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Odpowiedź na to wywołanie metody to obiekt Presentation zawierający komponenty żądane 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"
}
}
]
}
]
}
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 presentations.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.
W poniższym przykładzie użyto UpdateShapePropertiesRequest do zmiany wypełnienia kolorem kształtu na kolor motywu DARK1 i cofnięcia jego konspektu:
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"
}
}
]
}