Las máscaras de campo son una alternativa para que los emisores de API listen los campos que una solicitud debe proporcionar o actualizar. El uso de un FieldMask permite que la API evite 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 Documentos de Google.
Lee con una máscara de campo
Los documentos pueden ser grandes y, a menudo, no necesitas todas las partes del recurso Document que muestra una solicitud de lectura. Puedes limitar lo que se muestra en una respuesta de la API de Documentos usando el parámetro de URL fields. Para lograr el mejor rendimiento, enumera de forma explícita solo los campos que necesites en la respuesta.
El formato del parámetro de los campos es igual a la codificación JSON de una FieldMask. Dicho en pocas palabras, varios campos diferentes se separan con comas y los subcampos se separan con puntos. Los nombres de campos pueden especificarse en camelCase o separados_por_guiones_bajos. Para una mayor practicidad, varios subcampos del mismo tipo pueden listarse 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 este 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"
}
}
}
]
}
}
}
]
}Actualizar con una máscara de campo
A veces, solo es necesario actualizar determinados campos de un objeto y se deben dejar los demás sin modificaciones. Las solicitudes de actualización dentro de una operación documents.batchUpdate usan máscaras de campo para indicar a la API qué campos se modificarán. 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 dejar un campo sin configurar si no lo especificas en el mensaje actualizado y lo agregas a la máscara. Con esto, se borra cualquier valor que el campo haya contenido.
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 Documentos de Google” en el documento dentro del range de 5 a 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
},
}
}
],
}