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 do odczytu, jak i aktualizacji w interfejsie API Prezentacji Google.
Czytaj z maską pola
Prezentacje mogą być duże i często nie potrzebujesz wszystkich części zasobu Presentation
zwracanego w żądaniu odczytu. Możesz ograniczyć zakres zwracanych danych w odpowiedzi interfejsu Slides API, używając 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 presentations.get
użyto maski pola slides.pageElements(objectId,size,transform)
do pobrania tylko identyfikatora obiektu Size
oraz przekształcenia obiektu pageElement
ze wszystkich slajdów w 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 trzeba zaktualizować tylko niektóre pola w obiekcie, a pozostałe pola pozostawić bez zmian. Żądania aktualizacji w ramach operacji presentations.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 UpdateShapePropertiesRequest
do zmiany wypełnienia koloru kształtu na kolor motywu DARK1
i usunięcia konturu 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"
}
}
]
}