Las máscaras de campo permiten que los llamadores de API enumeren los campos que una solicitud debe mostrar o actualizar. El uso de una FieldMask permite que la API evite trabajos innecesarios y mejore el rendimiento. Se usa una máscara de campo para los métodos de lectura y actualización en la API de Presentaciones de Google.
Realiza operaciones de lectura con una máscara de campo
Las presentaciones pueden ser grandes y, a menudo, no necesitas que cada parte del recurso Presentation muestre una solicitud de lectura. Puedes limitar lo que se muestra en una respuesta de la API de Presentaciones con el parámetro de URL fields. Para obtener el mejor rendimiento, en la respuesta, enumera de forma explícita solo los campos que necesitas.
El formato del parámetro de campos es el mismo que la codificación JSON de una FieldMask. Dicho de manera breve, varios campos diferentes se separan con comas y los subcampos se separan con puntos. Los nombres de los campos se pueden especificar con el formato camelCase o separados_por_guiones_bajos. Para mayor comodidad, se pueden enumerar varios subcampos del mismo tipo entre paréntesis.
En el siguiente ejemplo de solicitud presentations.get, se usa una máscara de campo de slides.pageElements(objectId,size,transform) para recuperar solo el ID de objeto, la 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 de método es un objeto Presentation 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"
}
}
]
}
]
}
Actualiza con una máscara de campo
A veces, solo necesitas actualizar ciertos campos de un objeto y no modificar los demás. Las solicitudes de actualización dentro de una operación presentations.batchUpdate usan máscaras de campo para indicarle a la API qué campos se están cambiando. La solicitud de actualización ignora los campos que no se especifiquen en la máscara de campo, lo que deja sus valores actuales.
También puedes dejar de configurar un campo si no lo especificas en el mensaje actualizado, sino que lo agregas a la máscara. Esto borra cualquier valor que el campo tenía anteriormente.
La sintaxis de las máscaras de campo de actualización es la misma que la de las máscaras de campo de lectura.
En el siguiente ejemplo, se usa UpdateShapePropertiesRequest para cambiar el relleno de color de una forma al color de tema DARK1 y desactivar 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"
}
}
]
}