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"
}
}
]
}