Cómo usar máscaras de campo

Las máscaras de campo son una forma para 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 mejora 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.

Realiza operaciones de lectura con una máscara de campo

Los documentos pueden ser de gran tamaño y, a menudo, no necesitas cada parte del recurso Document que se muestra en una solicitud de lectura. Con el parámetro de URL fields, puedes limitar lo que se muestra en una respuesta de la API de Documentos. Para obtener el mejor rendimiento, lista de forma explícita solo los campos que necesitas en la respuesta.

El formato del parámetro de los campos es el mismo que la codificación JSON de una FieldMask. Dicho en pocas palabras, varios campos diferentes están separados por comas y los subcampos se separan con puntos. Los nombres de los campos se pueden especificar en camelCase o separate_by_guion 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,body.content(paragraph),revisionId para recuperar el title del documento, el Paragraph de un objeto Body y el revisionId del documento dentro de un documento:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,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",
  "body": {
    "content": [
      {},
      {
        "paragraph": {
          "elements": [
            {
              "startIndex": 1,
              "endIndex": 59,
              "textRun": {
                "content": ""CONTENT",
                "textStyle": {}
              }
            }
          ],
          "paragraphStyle": {
            "namedStyleType": "NORMAL_TEXT",
            "direction": "LEFT_TO_RIGHT"
          }
        }
      }
    ]
  },
  "revisionId": "REVISION_ID"
}

Actualiza con una máscara de campo

A veces, solo necesitas actualizar ciertos campos de un objeto y debes dejar los otros campos sin modificar. 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 cambian. La solicitud de actualización ignora los campos que no se especifiquen en la máscara de campo, lo que los deja con sus valores actuales.

También puedes quitar un campo si no lo especificas en el mensaje actualizado y lo agregas a la máscara. Esto borra cualquier valor que el campo tenía antes.

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 estilo a las palabras “API de Documentos de Google” del documento en negrita dentro del range 5-20:

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
  "title": "TITLE",
  "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
   },
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID"
}