A API Google Docs permite criar e modificar documentos.
Os apps podem ser integrados à API Docs para criar documentos refinados com dados fornecidos pelo usuário e pelo sistema. Com a API, você pode fazer o seguinte:
- Automatizar processos
- Criar documentação em massa
- Gerar faturas ou contratos
Visão geral da API
O recurso documents usa os métodos que você usa para invocar a API Docs.
Métodos da API
Os métodos a seguir permitem criar, ler e atualizar os Documentos Google:
- Use documents.create para criar um documento.
- Use documents.get para recuperar o conteúdo de um documento especificado.
- Use documents.batchUpdate para executar atomicamente um conjunto de atualizações em um documento especificado.
Os métodos get e batchUpdate exigem um documentId (veja abaixo) como um parâmetro para especificar o documento de destino. O método create retorna uma instância
do documento criado, do qual você pode ler o ID.
Atualizações em lote
O método batchUpdate pega uma lista de objetos de solicitação e faz atualizações
de acordo com a mesma ordem em que aparecem na solicitação em lote. As atualizações
em lote são aplicadas atomicamente. Ou seja, se alguma solicitação não for válida, toda a atualização não terá êxito e nenhuma das alterações (potencialmente dependentes) será aplicada.
O método batchUpdate retorna uma lista de objetos de resposta. Os objetos nesta
lista ocupam a mesma ordem de índice da solicitação correspondente.
Consulte práticas recomendadas de solicitação em lote para saber como reunir chamadas de API em lote e consulte a documentação de referência do batchUpdate para os tipos de solicitação e resposta.
ID do documento
Os IDs de documentos fazem referência a um documento e podem ser derivados do URL:
https://docs.google.com/document/d/documentId/edit
O documentId é uma string exclusiva que contém letras, números e alguns caracteres
especiais. A expressão regular a seguir pode ser usada para extrair o ID do documento de um URL do Documentos Google:
/document/d/([a-zA-Z0-9-_]+)
Se você conhece a API Google Drive, o documentId corresponde ao
ID do recurso Arquivo.
Locais em um documento: índices
Quando você atualiza o conteúdo de um documento, cada atualização ocorre em um local ou em um intervalo do documento. Esses locais e intervalos são especificados usando índices, que representam um deslocamento dentro de um segmento de documento. Para saber mais sobre índices e como usá-los, consulte o guia conceitual Estrutura de um arquivo do Documentos Google.
Fluxo de trabalho de atualização do documento
Criar e preencher um novo documento é simples, já que não há nenhum conteúdo para se preocupar e não há colaboradores que podem alterar o estado do documento. Conceitualmente, isso funciona como mostrado no diagrama de sequência a seguir:
Atualizar um documento é mais complexo. Antes de fazer chamadas relevantes para atualizar um documento, você precisa saber o estado atual dele: quais elementos compõem, qual conteúdo está nesses elementos e onde todos esses itens estão localizados no documento. O diagrama de sequência a seguir mostra como isso funciona:
Esse diagrama não considera fluxos de trabalho em que são feitas atualizações simultâneas por outros colaboradores no mesmo documento. Consulte Planejar a colaboração para uma discussão desse tópico.