Documento

Este guia apresenta conceitos como os principais métodos que compõem a API Google Docs, como acessar um documento e o fluxo de trabalho ao criar um documento.

Métodos da API

O recurso documents fornece métodos que você usa para invocar a API Docs. Os métodos a seguir permitem criar, ler e atualizar documentos do Docs:

  • Use o documents.create método para criar um documento.
  • Use o documents.get método para recuperar o conteúdo de um documento especificado.
  • Use o documents.batchUpdate método para realizar atomicamente um conjunto de atualizações em um documento especificado.

Os métodos documents.get e documents.batchUpdate exigem um documentId como parâmetro para especificar o documento de destino. O método documents.create retorna uma instância do documento criado, em que é possível ler o documentId. Para mais informações sobre solicitações e métodos de resposta da API Docs, consulte Solicitações e respostas.

ID do documento

O documentId é o identificador exclusivo do documento e pode ser derivado do URL de um documento. É uma string específica que contém letras, números e alguns caracteres especiais. Os IDs de documentos são estáveis, mesmo que o nome do documento mude.

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

A expressão regular a seguir pode ser usada para extrair o documentId de um URL do Google Docs:

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

Se você estiver familiarizado com a API Google Drive, o documentId corresponde a id no recurso files.

Gerenciar documentos no Google Drive

Os arquivos do Docs são armazenados no Google Drive, nosso serviço de armazenamento em nuvem. Embora a API Docs tenha seus próprios métodos independentes, muitas vezes é necessário usar também os métodos da API Google Drive para interagir com os arquivos do Docs de um usuário. Por exemplo, para copiar arquivos do Docs, use o método files.copy da API Drive. Para mais informações, consulte Copiar um documento.

Por padrão, ao usar a API Docs, um novo documento é salvo na pasta raiz do usuário no Drive. Há opções para salvar um arquivo em uma pasta do Drive. Para mais informações, consulte Trabalhar com pastas do Google Drive.

Trabalhar com arquivos do Docs

Para recuperar um documento do Meu Drive de um usuário, muitas vezes é necessário usar primeiro o método files.list do Drive para recuperar o ID de um arquivo. Chamar o método sem parâmetros retorna uma lista de todos os arquivos e pastas, incluindo os IDs, do usuário.

O tipo MIME de um documento indica o tipo e o formato dos dados. O formato do tipo MIME para o Docs é application/vnd.google-apps.document. Para uma lista de tipos MIME, consulte Tipos MIME compatíveis com o Google Workspace e o Google Drive.

Para pesquisar apenas arquivos do Docs no Meu Drive por tipo MIME, anexe o seguinte filtro de string de consulta:

q: mimeType = 'application/vnd.google-apps.document'

Para mais informações sobre filtros de string de consulta, consulte Pesquisar arquivos e pastas.

Depois de saber o documentId, use o documents.get método para recuperar uma instância completa do documento especificado. Para mais informações, consulte Solicitações e respostas.

Para exportar o conteúdo de bytes de um documento do Google Workspace, use o método files.export do Drive com o documentId do arquivo a ser exportado e o tipo MIME de exportação correto. Para mais informações, consulte Exportar conteúdo de documentos do Google Workspace.

Comparar os métodos Get e List

A tabela a seguir descreve as diferenças entre os métodos do Drive e do Docs e os dados retornados com cada um deles:

Operador Descrição Uso
drive.files.get Recebe os metadados de um arquivo por ID. Retorna uma instância do files recurso. Recebe os metadados de um arquivo específico.
drive.files.list Recebe os arquivos de um usuário. Retorna uma lista de arquivos. Recebe uma lista de arquivos do usuário quando você não tem certeza de qual arquivo precisa modificar.
docs.documents.get Recebe a versão mais recente do documento especificado, incluindo toda a formatação e o texto. Retorna uma instância do recurso documents. Recebe o documento de um ID específico.

Fluxo de trabalho de criação de documentos

Criar e preencher um novo documento é simples, já que não há conteúdo existente e não há colaboradores que possam 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.
Figura 1. Fluxo de trabalho para criar e preencher um novo documento.

Na Figura 1, um usuário que interage com o documents recurso tem o seguinte fluxo de informações:

  1. Um app chama o documents.create método em um servidor da Web.
  2. O servidor da Web envia uma resposta HTTP que contém uma instância do documento criado como um recurso documents.
  3. Opcionalmente, o app chama o documents.batchUpdate método para realizar atomicamente um conjunto de solicitações de edição para preencher o documento com dados.
  4. O servidor da Web envia uma resposta HTTP. Alguns métodos documents.batchUpdate fornecem um corpo de resposta com informações sobre as solicitações aplicadas, enquanto outros exibem uma resposta vazia.

Fluxo de trabalho de atualização de documentos

Atualizar um documento é mais complexo. Antes de fazer chamadas significativas para atualizar um documento, é necessário saber o estado atual dele: quais elementos o compõem, qual conteúdo está nesses elementos e a ordem dos elementos no documento. O diagrama de sequência a seguir mostra como isso funciona:

Fluxo de trabalho para atualizar um documento.
Figura 2. Fluxo de trabalho para atualizar um documento.

Na Figura 2, um usuário que interage com o recurso documents tem o seguinte fluxo de informações:

  1. Um app chama o documents.get método em um servidor da Web, com o documentId do arquivo a ser encontrado.
  2. O servidor da Web envia uma resposta HTTP que contém uma instância do documento especificado como um recurso documents. O JSON retornado contém o conteúdo, a formatação e outros recursos do documento.
  3. O app analisa o JSON para que o usuário possa determinar qual conteúdo ou formato atualizar.
  4. O app chama o método documents.batchUpdate para realizar atomicamente um conjunto de solicitações de edição para atualizar o documento.
  5. O servidor da Web envia uma resposta HTTP. Alguns métodos documents.batchUpdate fornecem um corpo de resposta com informações sobre as solicitações aplicadas, enquanto outros exibem uma resposta vazia.

Este diagrama não considera fluxos de trabalho em que atualizações simultâneas de outros colaboradores são feitas no mesmo documento. Para mais informações, consulte a seção de práticas recomendadas Planejar a colaboração.