Introdução

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:

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:

Fluxo de trabalho para criar e preencher um novo documento.

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:

Fluxo de trabalho para atualizar um documento.

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.