Neste guia, apresentamos 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 usados para invocar a API Docs. Os métodos a seguir permitem
criar, ler e atualizar documentos do Documentos:
- Use o método
documents.create
para criar um documento. - Use o método
documents.get
para recuperar o conteúdo de um documento especificado. - Use o método
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. 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. Ela é uma string específica que contém letras, números e alguns caracteres especiais. Os IDs dos documentos são estáveis, mesmo se o nome do documento
for alterado.
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 dos 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 são armazenados no Google Drive, nosso serviço de armazenamento
baseado em nuvem. Embora a API Docs tenha os próprios métodos independentes, muitas vezes é necessário usar também os métodos da API Google Drive para interagir com os arquivos de documentos de um usuário. Por exemplo, para copiar arquivos do Documentos, use o método files.copy
da API Drive. Para mais informações, consulte Copiar um documento
atual.
Por padrão, quando você usa 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 Documentos
Para recuperar um documento do Meu Drive de um usuário, geralmente
é necessário usar o método
files.list
do Drive para recuperar o
ID de um arquivo. Chamar o método sem nenhum parâmetro retorna uma lista de todos
os 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 MIME
dos Documentos é 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 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 strings de consulta, consulte Pesquisar arquivos e pastas.
Depois de conhecer o documentId
, use o método
documents.get
para extrair
uma instância completa do documento especificado. Para mais informações, consulte Solicitações e respostas.
Para exportar o conteúdo de bytes do 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.
Compare os métodos Get
e List
A tabela a seguir descreve as diferenças entre os métodos do Drive e dos Documentos, além dos 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 . |
Acessa o documento de um ID de documento específico. |
Fluxo de trabalho de criação de documentos
Criar e preencher um novo documento é simples, já que não há conteúdo com que se preocupar e não há colaboradores que possam alterar o estado dele. Conceitualmente, isso funciona conforme mostrado no diagrama de sequência abaixo:
Na Figura 1, um usuário interagindo com o recurso
documents
tem o seguinte
fluxo de informações:
- Um app chama o método
documents.create
em um servidor da Web. - O servidor da Web envia uma resposta HTTP que contém uma instância do
documento criado como um recurso
documents
. - 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 dados. - 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 existente é mais complexo. Antes de fazer chamadas significativas para atualizar um documento, você precisa conhecer o estado atual dele: quais elementos o compõem, qual conteúdo está nesses elementos e a ordem deles. O diagrama de sequência a seguir mostra como isso funciona:
Na Figura 2, um usuário interagindo com o recurso documents
tem o
seguinte fluxo de informações:
- Um app chama o método
documents.get
em um servidor da Web, com odocumentId
do arquivo a ser encontrado. - 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. - O app analisa o JSON para que o usuário possa determinar qual conteúdo ou formato atualizar.
- O app chama o método
documents.batchUpdate
para executar atomicamente um conjunto de solicitações de edição para atualizar o documento. - 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 por outros colaboradores são feitas no mesmo documento. Para saber mais, consulte a seção de práticas recomendadas, Planejar a colaboração.
Temas relacionados
- Estrutura de um arquivo do Documentos Google
- Solicitações e respostas
- Regras e comportamento de edição estrutural
- Práticas recomendadas para melhores resultados