Las máscaras de campo son una forma para que los llamadores de la API enumeren los campos que una solicitud debe mostrar o actualizar. El uso de FieldMask permite que la API evite el trabajo innecesario y mejore el rendimiento. Se usa una máscara de campo para los métodos de lectura y actualización en la API de Google Slides.
Para obtener una comparación de lo que se muestra en un cuerpo de respuesta cuando no usas una máscara de campo en comparación con cuando lo haces, consulta Cómo trabajar con recursos parciales.
Leer con una máscara de campo
Las presentaciones pueden ser grandes y, a menudo, no necesitas que una solicitud de lectura muestre todas las partes del
presentations
recurso. Puedes limitar lo que se muestra en una respuesta de la API de Slides con el parámetro de URL fields. Para obtener el mejor
rendimiento, enumera explícitamente solo los campos que
necesitas en la respuesta.
El formato del parámetro fields es el mismo que la codificación JSON de un FieldMask. En resumen, varios campos diferentes están separados por comas y los subcampos están separados por puntos. Los nombres de los campos se pueden especificar en camelCase o separated_by_underscores. Para mayor comodidad, se pueden enumerar varios subcampos del mismo tipo entre paréntesis.
En el siguiente
presentations.get
ejemplo de solicitud del método, se usa una máscara de campo de
slides.pageElements(objectId,size,transform)para recuperar solo el ID del objeto,
Size, y la
transformación
de un objeto
pageElement
en todas las diapositivas de una presentación:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
La respuesta a esta llamada al método es un
presentations objeto
que contiene los componentes solicitados en la máscara de campo:
{
"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"
}
}
]
}
]
}Actualizar con una máscara de campo
A veces, necesitas actualizar solo ciertos campos en un objeto y no modificar los otros campos. Las solicitudes de actualización dentro de un
presentations.batchUpdate
método usan máscaras de campo para indicarle a la API qué campos se cambian. La solicitud de actualización ignora los campos que no se especifican en la máscara de campo, y los deja con sus valores actuales.
También puedes anular un campo si no lo especificas en el mensaje actualizado, pero agregas el campo a la máscara. Esto borra cualquier valor que el campo haya tenido anteriormente.
La sintaxis para actualizar las máscaras de campo es la misma que la de las máscaras de campo de lectura.
En el siguiente ejemplo, se usa el
UpdateShapePropertiesRequest
método para cambiar el relleno de color de una forma al color del tema DARK1 y anular el
contorno de la forma:
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"
}
}
]
}