Máscaras de campo são uma forma de os autores da chamada à API listarem os campos que uma solicitação precisa retornar ou atualizar. O uso de uma FieldMask permite que a API evite trabalho desnecessário 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
retornados 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 extrair o melhor
desempenho possível,
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 os subcampos são separados por pontos. Os nomes dos campos podem ser especificados em camelCase ou separated_by_underscores. Para fins de 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, é preciso atualizar apenas alguns campos de um objeto e deixar
os outros como estão. As solicitações de atualização dentro de 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
estiverem especificados na máscara de campo,
deixando-os com os valores atuais.
Você também pode não definir um campo removendo a definição dele na mensagem atualizada, mas adicionando-o à 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.
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
},
}
}
],
}