Usar máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas de API listarem os campos que uma solicitação deve retornar ou atualizar. Usar um FieldMask permite que a API evite trabalho desnecessário e melhore a performance. Uma máscara de campo é usada nos métodos de leitura e atualização da 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 ter o melhor desempenho, liste explicitamente apenas os campos necessários na resposta.

O formato do parâmetro "fields" é o mesmo da codificação JSON de um FieldMask. Em resumo, vários campos diferentes são separados por vírgulas, e subcampos são separados por pontos. Os nomes dos campos podem ser especificados em camelCase ou separados_por_sublinhados. Para facilitar, 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 guias) 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 alguns campos em um objeto e deixar os outros 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 estão especificados na máscara de campo, deixando-os com os valores atuais.

Também é possível remover a definição de um campo não especificando-o na mensagem atualizada, mas adicionando o campo à máscara. Isso limpa qualquer valor que o campo tinha antes.

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 caractere curinga pode gerar resultados indesejados se a API for atualizada no futuro, já que campos somente leitura e recém-adicionados podem causar erros. Para aplicativos de produção, sempre liste os campos específicos que estão sendo atualizados em 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 como negrito no 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
        },
      }
    }
  ],
}