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 uma documento.

Métodos da API

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

  • Usar o documents.create para criar um documento.
  • Usar o método documents.get para recuperar o conteúdo de um documento especificado.
  • Usar o documents.batchUpdate para executar 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. Método documents.create retorna uma instância do documento criado, a partir do qual é possível ler o documentId. Para mais informações sobre solicitações da API Docs e métodos de resposta, consulte Solicitações e de resposta.

ID do documento

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

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 Documentos Google:

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

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

Gerencie documentos no Google Drive

Os arquivos dos Documentos Google ficam no Google Drive, nosso armazenamento baseado na nuvem. serviço. Embora a API Docs tenha seus próprios métodos independentes, muitas vezes é também é necessário usar os métodos da API Google Drive para interagir com o Documentos. Por exemplo, para copiar arquivos do Documentos, use files.copy da API Drive . Para mais informações, consulte Copiar uma documento.

Por padrão, ao usar a API Docs, um novo documento é salvo no 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 Documentos

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

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

Para pesquisar por tipo MIME apenas arquivos do Documentos em "Meu" Drive, 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 conhecer o documentId, use o Método documents.get 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 Documento do Google Workspace .

Compare os métodos Get e List

A tabela a seguir descreve as diferenças entre o Drive e 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 recurso files. Acessa os metadados de um arquivo específico.
drive.files.list Recebe os arquivos de um usuário. Retorna uma lista de arquivos. Receba uma lista de arquivos de usuário quando não tiver certeza de qual arquivo precisa ser modificado.
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. Receba o documento de um ID específico.

Fluxo de trabalho de criação de documentos

Criar e preencher um novo documento é simples, pois não há conteúdo existente com os quais se preocupar e não há colaboradores que possam alterar o estado do documento. Conceitualmente, isso funciona conforme mostrado na sequência a seguir diagrama:

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 recurso documents tem o seguinte fluxo de informações:

  1. Um app chama O método documents.create está ativado um servidor da Web.
  2. O servidor da Web envia uma resposta HTTP que contém uma instância do criou o documento como um recurso documents.
  3. Opcionalmente, o app chama o método documents.batchUpdate para executar atomicamente um conjunto de solicitações de edição para preencher o documento com os 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 mostram uma resposta vazia.

Fluxo de trabalho de atualização de documentos

Atualizar um documento existente é mais complexo. Antes de poder fazer sentido para atualizar um documento, você deve saber seu estado atual: quais elementos fazem qual conteúdo está nesses elementos e a ordem deles o 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 as seguinte fluxo de informações:

  1. Um app chama Método documents.get em uma 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 de documentos.
  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 executar 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 enquanto outros exibem uma resposta vazia.

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