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 Docs.
Lee con una máscara de campo
Los documentos pueden ser grandes y, a menudo, no necesitas cada parte del
Document
recurso que muestra una solicitud de lectura. Puedes limitar lo que se muestra 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 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
documents.get ejemplo
de solicitud, 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 al método es un
Document
objeto 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, necesitas actualizar solo ciertos campos en un objeto y no modificar los otros campos. Las solicitudes de actualización dentro de una
documents.batchUpdate
operación 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 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 estilo a las palabras "API de Google Docs" en el documento como negrita dentro del 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
},
}
}
],
}