Introdução

A API Google Docs permite criar e modificar documentos.

Os apps podem se integrar à API Docs para criar documentos refinados com dados fornecidos pelo usuário e pelo sistema. Com a API, você pode:

  • Automatizar processos.
  • Criar documentação em massa
  • Gerar faturas ou contratos

Visão geral da API

O recurso documents fornece métodos que você usa para invocar a API Docs.

Métodos da API

Os métodos a seguir permitem criar, ler e atualizar arquivos do Documentos Google:

Os métodos get e batchUpdate exigem um documentId (veja abaixo) como parâmetro para especificar o documento de destino. O método create retorna uma instância do documento criado, em que você pode ler o ID.

Atualizações em lote

O método batchUpdate usa uma lista de objetos de solicitação e faz as atualizações de acordo com a mesma ordem em que aparecem na solicitação em lote. As atualizações na atualização em lote são aplicadas atomicamente. Ou seja, se alguma solicitação não for válida, toda a atualização será malsucedida e nenhuma das mudanças (possivelmente dependentes) será aplicada.

O método batchUpdate retorna uma lista de objetos de resposta. Os objetos nessa lista ocupam a mesma ordem de índice que a solicitação correspondente.

Consulte as práticas recomendadas para solicitações em lote para saber como agrupar chamadas de API em lote e a documentação de referência de batchUpdate para os tipos de solicitação e resposta.

ID do documento

Os IDs de documento se referem a um documento e podem ser derivados do URL:

https://docs.google.com/document/d/documentId/edit

A documentId é uma string exclusiva contendo letras, números e alguns caracteres especiais. A expressão regular abaixo pode ser usada para extrair o ID do documento de um URL dos Documentos Google:

/document/d/([a-zA-Z0-9-_]+)

Se você conhece a API Google Drive, o documentId corresponde ao ID do recurso File.

Locais dentro de um documento: índices

Quando você atualiza o conteúdo de um documento, cada atualização ocorre em um local ou em um intervalo dentro 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 sobre Estrutura de um documento do Documentos Google.

Fluxo de trabalho de atualização de documentos

Criar e preencher um novo documento é simples, porque não há conteúdo com que se preocupar e não há colaboradores que possam alterar o estado do documento. Conceitualmente, isso funciona conforme 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 significativas para atualizar um documento, você precisa saber o estado atual dele: quais elementos o 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.

Este diagrama não considera fluxos de trabalho em que atualizações simultâneas de outros colaboradores são feitas no mesmo documento. Consulte Planejar a colaboração para ver uma discussão sobre esse tópico.