Com a API Google Drive, você pode fazer upload de dados de arquivos ao criar ou atualizar um File
. Para informações sobre como criar um
arquivo somente de metadados, como uma pasta, consulte Criar arquivos somente de metadados.
Você pode fazer três tipos de upload:
Upload simples (
uploadType=media
): use esse tipo para transferir um arquivo de mídia pequeno (5 MB ou menos) sem fornecer metadados. Para realizar um upload simples, consulte Executar um upload simples.Upload de várias partes (
uploadType=multipart
): "use esse tipo de upload para transferir um arquivo pequeno (5 MB ou menos) com metadados que descrevem o arquivo em uma única solicitação. Para realizar um upload de várias partes, consulte Executar um upload de várias partes.Upload retomável (
uploadType=resumable
): use esse tipo para arquivos grandes (com mais de 5 MB) e quando houver uma grande chance de interrupção de rede, como ao criar um arquivo de um app para dispositivos móveis. Os uploads retomáveis também são uma boa opção para a maioria dos apps, porque também funcionam para arquivos pequenos com um custo mínimo de uma solicitação HTTP extra por upload. Para executar um upload retomável, consulte Executar um upload retomável.
As bibliotecas de cliente das APIs do Google implementam pelo menos um desses tipos de upload. Consulte a documentação da biblioteca de cliente para mais detalhes sobre como usar cada um dos tipos.
Usar PATCH
x PUT
Como lembrete, o verbo HTTP PATCH
aceita uma atualização parcial de recurso de arquivo,
enquanto o verbo HTTP PUT
aceita substituição completa de recursos. Observe que PUT
pode introduzir alterações interruptivas ao adicionar um novo campo a um recurso atual.
Ao fazer o upload de um recurso de arquivo, use as seguintes diretrizes:
- Use o verbo HTTP documentado na referência da API para a solicitação inicial de um upload retomável ou para a única solicitação de upload simples ou de várias partes.
- Use
PUT
para todas as solicitações subsequentes de um upload retomável depois que a solicitação for iniciada. Essas solicitações fazem upload do conteúdo, independentemente do método chamado.
Realizar um upload simples
Para fazer um upload simples, use o
método files.create
com
uploadType=media
.
A seguir, mostramos como realizar um upload simples:
HTTP
Crie uma solicitação
POST
para o URI de /upload do método com o parâmetro de consulta deuploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Adicione os dados do arquivo ao corpo da solicitação.
Adicione estes cabeçalhos HTTP:
Content-Type
. Defina de acordo com o tipo de mídia MIME do objeto que está sendo enviado.Content-Length
. Defina conforme o número de bytes do upload. Se você usar a codificação de transferência em partes, esse cabeçalho não será necessário.
Envie a solicitação. Se a solicitação for bem-sucedida, o servidor retornará o código de status
HTTP 200 OK
com os metadados do arquivo. {HTTP}
Quando você faz um upload simples, metadados básicos são criados e alguns atributos
são inferidos do arquivo, como o tipo MIME ou modifiedTime
. Você pode usar
um upload simples nos casos em que tem arquivos pequenos e os metadados dos arquivos não são
importantes.
Realizar um upload de várias partes
Uma solicitação de upload de várias partes permite enviar metadados e dados na mesma solicitação. Use essa opção se os dados enviados forem pequenos o suficiente para que o upload possa ser feito novamente, se a conexão falhar.
Para fazer um upload de várias partes, use o
método files.create
com
uploadType=multipart
.
Confira a seguir como realizar um upload de várias partes:
Java
Python
Node.js
PHP
.NET
HTTP
Crie uma solicitação
POST
para o URI de /upload do método com o parâmetro de consulta deuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Crie o corpo da solicitação. Formate o corpo de acordo com o tipo de conteúdo relacionado a várias partes RFC 2387, que contém duas partes:
- Metadados. Os metadados precisam vir primeiro e ter um cabeçalho
Content-Type
definido comoapplication/json;
charset=UTF-8
. Adicione os metadados do arquivo no formato JSON. - Mídia. A mídia precisa vir depois e ter um cabeçalho
Content-Type
de qualquer tipo MIME. Adicione os dados do arquivo à parte de mídia.
Identifique cada parte com uma string limite, precedida por dois hifens. Além disso, adicione dois hifens após a última string limite.
- Metadados. Os metadados precisam vir primeiro e ter um cabeçalho
Adicione estes cabeçalhos HTTP de nível superior:
Content-Type
. Defina comomultipart/related
e inclua a string limite que você está usando para identificar as diferentes partes da solicitação. Por exemplo:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Defina com o número total de bytes no corpo da solicitação.
Envie a solicitação.
Para criar ou atualizar somente a parte de metadados, sem os dados associados, envie uma solicitação POST
ou PATCH
para o endpoint de recurso padrão: https://www.googleapis.com/drive/v3/files
Se a solicitação for bem-sucedida, o servidor retornará o código de status HTTP 200 OK
com os metadados do arquivo.
Ao criar arquivos, eles precisam especificar uma extensão de arquivo no campo name
. Por exemplo, ao criar um arquivo JPEG de foto, é possível especificar algo
como "name": "photo.jpg"
nos metadados. As chamadas subsequentes para files.get
retornam a propriedade fileExtension
somente leitura que contém a extensão especificada originalmente no campo name
.
Executar um upload retomável
Um upload retomável permite retomar uma operação de upload após uma falha de comunicação interromper o fluxo de dados. Como não é necessário reiniciar os uploads de arquivos grandes desde o início, os uploads retomáveis também podem reduzir o uso da largura de banda em caso de falha de rede.
Os uploads retomáveis são úteis quando os tamanhos dos arquivos podem variar muito ou quando há um limite de tempo fixo para solicitações, como tarefas em segundo plano do SO para dispositivos móveis e determinadas solicitações do App Engine. Também é possível usar uploads retomáveis quando você quer mostrar uma barra de progresso de upload.
Um upload retomável consiste em várias etapas de alto nível:
- Envie a solicitação inicial e recupere o URI de sessão retomável.
- Fazer upload dos dados e monitorar o estado de upload.
- (opcional) Se houver problemas durante o upload, retome-o.
Enviar a solicitação inicial
Para iniciar um upload retomável, use o
método files.create
com
uploadType=resumable
.
HTTP
Crie uma solicitação
POST
para o URI de /upload do método com o parâmetro de consulta deuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Se a solicitação de início for bem-sucedida, a resposta incluirá um código de status HTTP
200 OK
. Além disso, ela inclui um cabeçalhoLocation
que especifica o URI da sessão retomável:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Salve o URI da sessão retomável para fazer upload dos dados do arquivo e consultar o status do upload. Um URI de sessão retomável expira após uma semana.
Se você tiver metadados para o arquivo, adicione-os ao corpo da solicitação no formato JSON. Caso contrário, deixe o corpo em branco.
Adicione estes cabeçalhos HTTP:
X-Upload-Content-Type
: opcional. Defina como o tipo MIME dos dados de arquivo, que serão transferido nas solicitações subsequentes. Se o tipo MIME dos dados não for especificado nos metadados ou por meio desse cabeçalho, o objeto será exibido comoapplication/octet-stream.
.X-Upload-Content-Length
: opcional. Defina conforme o número de bytes dos dados do arquivo, que são transferidos nas solicitações subsequentes.Content-Type
: obrigatório se você tiver os metadados do arquivo. Defina comoapplication/json;
charset=UTF-8
.Content-Length
: obrigatório, a menos que você use a codificação de transferência em partes. Defina conforme o número de bytes no corpo dessa solicitação inicial.
Envie a solicitação. Se a solicitação de início da sessão for bem-sucedida, a resposta incluirá um código de status
200 OK HTTP
. Além disso, a resposta inclui um cabeçalhoLocation
que especifica o URI da sessão retomável. Use o URI da sessão retomável para fazer upload dos dados do arquivo e consultar o status do upload. Um URI de sessão retomável expira após uma semana.Copie e salve o URL da sessão retomável.
Continue para Fazer upload do conteúdo.
Fazer upload do conteúdo
Há duas formas de fazer o upload de um arquivo com uma sessão retomável:
- Fazer upload de conteúdo em uma única solicitação: use essa abordagem quando o arquivo puder ser enviado em uma solicitação, se não houver um limite de tempo fixo para cada solicitação ou se você não precisar exibir um indicador de progresso de upload. Essa abordagem é melhor porque requer menos solicitações e resulta em uma performance melhor.
Faça upload do conteúdo em vários fragmentos: use essa abordagem se precisar reduzir a quantidade de dados transferidos em uma única solicitação. Talvez seja necessário reduzir os dados transferidos quando houver um limite de tempo fixo para solicitações individuais, como é o caso de determinadas classes de solicitações do App Engine. Essa abordagem também é útil quando você precisa fornecer um indicador personalizado para mostrar o progresso do upload.
HTTP - solicitação única
- Crie uma solicitação
PUT
para o URI da sessão retomável. - Adicione os dados do arquivo ao corpo da solicitação.
- Adicione um cabeçalho HTTP Content-Length definido como o número de bytes no arquivo.
- Envie a solicitação. Se a solicitação de upload for interrompida ou se você receber uma
resposta
5xx
, siga o procedimento em Retomar um upload interrompido.
HTTP - várias solicitações
Crie uma solicitação
PUT
para o URI da sessão retomável.Adicione os dados de cada parte ao corpo da solicitação. Crie blocos em múltiplos de 256 KB (256 x 1.024 bytes), exceto o fragmento final que conclui o upload. Mantenha o tamanho do fragmento o maior possível para que o upload seja eficiente.
Adicione estes cabeçalhos HTTP:
Content-Length
: defina como o número de bytes na parte atual.Content-Range
. Defina para mostrar de quais bytes no arquivo você vai fazer upload. Por exemplo,Content-Range: bytes 0-524287/2000000
mostra que você faz upload dos primeiros 524.288 bytes (256 x 1.024 x 2) em um arquivo de 2 milhões de bytes.
Envie a solicitação e processe a resposta. Se a solicitação de upload for interrompida ou se você receber uma resposta
5xx
, siga o procedimento em Retomar um upload interrompido.Repita as etapas de 1 a 4 para cada fragmento que permanece no arquivo. Use o cabeçalho
Range
na resposta para determinar onde iniciar a próxima parte. Não suponha que o servidor recebeu todos os bytes enviados na solicitação anterior.
Quando o upload do arquivo inteiro for concluído, você receberá uma resposta 200 OK
ou
201 Created
, além de todos os metadados associados ao recurso.
Retomar um upload interrompido
Se uma solicitação de upload for encerrada antes de uma resposta ou você receber uma resposta 503
Service Unavailable
, será preciso retomar o upload interrompido.
HTTP
Para saber o status do upload, crie uma solicitação
PUT
vazia para o URI de sessão retomável.Adicione um cabeçalho
Content-Range
para indicar que a posição atual no arquivo é desconhecida. Por exemplo, definaContent-Range
como*/2000000
se o tamanho total do arquivo for de 2.000.000 bytes. Se você não souber o tamanho total do arquivo, definaContent-Range
como*/*
.Envie a solicitação.
Processe a resposta:
- Uma resposta
200 OK
ou201 Created
indica que o upload foi concluído e não é necessário realizar qualquer outra ação. - Uma resposta
308 Resume Incomplete
indica que é preciso continuar o upload do arquivo. - Uma resposta
404 Not Found
indica que a sessão de upload expirou e que o upload precisa ser reiniciado desde o início.
- Uma resposta
Se você recebeu uma resposta
308 Resume Incomplete
, processe o cabeçalhoRange
da resposta para determinar quais bytes o servidor recebeu. Se a resposta não tiver um cabeçalhoRange
, nenhum byte foi recebido. Por exemplo, um cabeçalhoRange
debytes=0-42
indica que os primeiros 43 bytes do arquivo foram recebidos e que o próximo fragmento para upload começaria com o byte 44.Agora que você sabe em que ponto retomar o upload, continue com o upload do arquivo começando pelo próximo byte. Inclua um cabeçalho
Content-Range
para indicar qual parte do arquivo você vai enviar. Por exemplo,Content-Range: bytes 43-1999999
indica que você envia os bytes 44 a 2.000.000.
Processar erros de upload de mídia
Ao fazer upload de mídia, siga estas práticas recomendadas para lidar com erros:
- Para erros
5xx
, retome ou repita os uploads que falharem devido a interrupções de conexão. Para mais informações sobre como lidar com erros5xx
, consulte erros 500, 502, 503 e 504. - No caso de erros
403 rate limit
, tente fazer o upload novamente. Para mais informações sobre como lidar com erros403 rate limit
, consulte o erro 403:rateLimitExceeded
. - Para quaisquer erros
4xx
(incluindo403
) durante um upload retomável, reinicie o upload. Esses erros indicam que a sessão de upload expirou e precisa ser reiniciada solicitando um novo URI de sessão. As sessões de upload também expiram após uma semana de inatividade.
Tipos de importação para o Documentos Google
Ao criar um arquivo no Drive, talvez você queira convertê-lo em um tipo de arquivo do Google Workspace, como Documentos ou Planilhas Google. Por exemplo, talvez você queira transformar um documento do seu processador de texto favorito em um documento para aproveitar os recursos dele.
Para converter um arquivo em um tipo específico do Google Workspace, especifique o
mimeType
do Google Workspace ao criar o arquivo.
Confira a seguir como converter um arquivo CSV em uma planilha do Google Workspace:
Java
Python
Node.js
PHP
.NET
Para ver se uma conversão está disponível, verifique a matriz importFormats
do recurso about
antes de criar o arquivo.
As conversões compatíveis estão disponíveis dinamicamente nessa matriz. Alguns formatos
de importação comuns são:
De | Para |
---|---|
Microsoft Word, Texto OpenDocument, HTML, RTF, texto simples | Documentos Google |
Microsoft Excel, planilha OpenDocument, CSV, TSV, texto simples | Planilhas Google |
Microsoft PowerPoint, apresentação OpenDocument | Apresentações Google |
JPEG, PNG, GIF, BMP e PDF | Documentos Google (incorpora a imagem em um documento) |
Texto simples (tipo MIME especial), JSON | Google Apps Script |
Quando você faz upload e converte mídia durante uma solicitação update
em um arquivo do Documentos, Planilhas ou Apresentações, todo o conteúdo do documento é substituído.
Quando você converte uma imagem em um documento Google, o Drive usa o reconhecimento óptico de caracteres (OCR, na sigla em inglês) para converter a imagem em texto. É possível melhorar a qualidade do algoritmo de OCR especificando o código de idioma BCP
47 aplicável no parâmetro
ocrLanguage
. O texto extraído aparece no documento ao lado da imagem incorporada.
Usar um ID pré-gerado para fazer upload de arquivos
A API Drive permite recuperar uma lista de IDs de arquivos pré-gerados usados para fazer upload e criar recursos. As solicitações de upload e criação de arquivos podem usar esses IDs pré-gerados. Defina o campo id
nos metadados do arquivo.
Para criar IDs pré-gerados, chame
files.generateIds
com o
número de IDs a serem criados.
Você pode repetir com segurança os uploads com IDs pré-gerados se houver um erro de servidor
indeterminado ou o tempo limite. Se o arquivo tiver sido criado com êxito, as tentativas subsequentes
retornarão um erro HTTP 409
e não vão criar arquivos duplicados.
Definir texto indexável para tipos de arquivo desconhecidos
Os usuários podem usar a interface do Drive para encontrar o conteúdo de um documento. Você também pode
usar files.list
e o campo fullText
para pesquisar conteúdo do seu app. Para saber mais, consulte Pesquisar
arquivos e pastas.
O Drive indexa automaticamente documentos para pesquisa quando reconhece o tipo de arquivo, incluindo documentos de texto, PDFs, imagens com texto e outros tipos comuns. Se o app salvar outros tipos de arquivo, como desenhos, vídeos e atalhos, você poderá melhorar a descoberta fornecendo
texto indexável no campo contentHints.indexableText
do arquivo.
Para mais informações sobre texto indexável, consulte Gerenciar metadados de arquivo.