Usar máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas de API listar os campos que uma solicitação precisa retornar ou atualizar. O uso de uma FieldMask permite que a API evite trabalhos desnecessários e melhore a performance. Uma máscara de campo é usada para os métodos de leitura e atualização na API Google Docs.

Ler com uma máscara de campo

Os documentos podem ser grandes, e muitas vezes você não precisa de todas as partes do recurso Document retornado por uma solicitação de leitura. É possível limitar o que é retornado em uma resposta da API Docs usando o parâmetro de URL fields. Para melhor desempenho, liste explicitamente apenas os campos necessários na resposta.

O formato do parâmetro fields é igual à codificação JSON de um FieldMask. Resumidamente, vários campos diferentes são separados por vírgulas e os subcampos são separados por pontos. Os nomes dos campos podem ser especificados em camelCase ou separated_by_underscores. Para sua conveniência, vários subcampos do mesmo tipo podem ser listados entre parênteses.

O exemplo de solicitação documents.get a seguir usa uma máscara de campo de title,tabs(documentTab(body.content(paragraph))),revisionId para buscar o title do documento, o Paragraph de um objeto Body (de todas as abas) e o revisionId do documento em um documento:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

A resposta a essa chamada de método é um objeto Document que contém os componentes solicitados na 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"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Atualizar com uma máscara de campo

Às vezes, é necessário atualizar apenas determinados campos em um objeto e deixar os outros campos inalterados. As solicitações de atualização em uma operação documents.batchUpdate usam máscaras de campo para informar à API quais campos estão sendo alterados. A solicitação de atualização ignora todos os campos que não são especificados na máscara de campo, deixando-os com os valores atuais.

Também é possível redefinir um campo sem especificá-lo na mensagem atualizada, mas adicionando o campo à máscara. Isso limpa qualquer valor que o campo tinha anteriormente.

A sintaxe das máscaras de campo de atualização é a mesma das máscaras de campo de leitura.

Uma máscara de campo de * é tratada como um curinga e é uma abreviação para especificar todos os campos em uma mensagem. A sintaxe de curinga pode produzir resultados indesejados se a API for atualizada no futuro, já que campos somente leitura e campos recém-adicionados podem causar erros. Para aplicativos de produção, sempre liste os campos específicos que estão sendo atualizados nas máscaras de campo e evite usar caracteres curinga *.

O exemplo a seguir usa o UpdateTextStyleRequest para estilizar as palavras "API Google Docs" no documento em negrito dentro do 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
        },
      }
    }
  ],
}