Las máscaras de campo son una forma en que los llamadores de la API pueden enumerar los campos que una solicitud debe devolver o actualizar. El uso de un 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 Docs.
Lectura con una máscara de campo
Los documentos pueden ser grandes y, a menudo, no necesitas todas las partes del recurso Document que devuelve una solicitud de lectura. Puedes limitar lo que se devuelve en una respuesta de la API de Docs 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 el de la codificación JSON de un FieldMask. En resumen, los diferentes campos se separan con comas y los subcampos, con puntos. Los nombres de los campos se pueden especificar en 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 documents.get, se usa una máscara de campo de title,tabs(documentTab(body.content(paragraph))),revisionId para recuperar el title del documento, el Paragraph de un objeto Body (de todas las pestañas) y el revisionId del documento dentro de un documento:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
La respuesta a esta llamada de método es un objeto Document que contiene los componentes solicitados en la máscara de campo:
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}Actualiza con una máscara de campo
A veces, solo necesitas actualizar ciertos campos en un objeto y no modificar los otros campos. Las solicitudes de actualización dentro de una operación documents.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 especifican en la máscara de campo y los deja con sus valores actuales.
También puedes anular la configuración de un campo si no lo especificas en el mensaje actualizado, pero lo agregas a la máscara. Esto borrará cualquier valor que el campo haya tenido 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 UpdateTextStyleRequest para aplicar el estilo de negrita a las palabras "API de Google Docs" en el documento dentro de range 5-20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
}
}
],
}