Esta página descreve como fazer uma solicitação de upload retomável para a API Google Photos Library pelo protocolo REST. Esse protocolo permite retomar uma operação de upload após uma falha de comunicação interrompe o fluxo de dados.
Use a opção de upload retomável se:
- Você está fazendo upload de arquivos grandes.
- A probabilidade de interrupção da rede ou alguma outra falha de transmissão é alta (por exemplo, se você estiver enviando um arquivo de um aplicativo móvel).
Os uploads retomáveis também podem reduzir o uso de largura de banda quando há uma rede falha, porque não é preciso reiniciar os uploads de arquivos grandes no desde o início.
Etapa 1: iniciar uma sessão de upload
Iniciar uma sessão de upload retomável enviando uma solicitação POST para
https://photoslibrary.googleapis.com/v1/uploads
: Como usar o upload retomável
URL retornado nessa solicitação, faça o upload do arquivo.
A solicitação POST deve incluir os seguintes cabeçalhos:
Campos de cabeçalho | |
---|---|
Content-Length |
Defina como 0 porque o corpo da solicitação está vazio. |
X-Goog-Upload-Command |
Defina como start . |
X-Goog-Upload-Content-Type |
Defina como o tipo MIME do arquivo, por exemplo,
image/jpeg : |
X-Goog-Upload-Protocol |
Defina como resumable . |
X-Goog-Upload-Raw-Size |
Defina como o número total de bytes dos dados do arquivo a ser transferidos. |
Este é um cabeçalho de solicitação POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
Etapa 2: salvar o URL da sessão
Se for bem-sucedida, a solicitação POST retornará um código de status HTTP 200 OK
, incluindo
no cabeçalho a seguir.
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
O campo de cabeçalho x-goog-upload-chunk-granularity
contém o alinhamento de bytes
e a granularidade de tamanho para todos os blocos de dados enviados pelo cliente. Se o upload for
feito em vários blocos, todos os uploads, exceto o último;
deve ser feita em múltiplos desse valor. Ou seja, os bytes de upload do arquivo
precisam estar alinhados a esse valor. Na última parte, é possível fazer upload dos arquivos
bytes.
O campo de cabeçalho X-Goog-Upload-URL
contém um URL exclusivo que deve ser usado para
conclua o upload com todas as solicitações restantes. Copie e salve este
URL de sessão retomável para poder usá-lo nas solicitações subsequentes.
Etapa 3: fazer upload do arquivo
Há duas formas de fazer o upload de um arquivo com uma sessão retomável:
- Em uma única solicitação: Essa abordagem geralmente é a melhor, porque requer menos solicitações e, portanto, tem melhor desempenho.
-
Em várias partes: Nessa abordagem, os uploads são feitos em várias solicitações ao dividir os dados. Os dados são divididos múltiplos de
x-goog-upload-chunk-granularity
. Se necessário, as solicitações em partes podem ser repetidas.use esta abordagem nos casos a seguir:
- Você precisa reduzir a quantidade de dados transferidos em cada solicitação. Você poderá precisar fazer isso quando houver um limite de tempo fixo para solicitações individuais.
- Você precisa fornecer um indicador personalizado mostrando o upload o progresso.
- Você precisa saber quando é seguro descartar dados.
Solicitação única
Para fazer upload do arquivo em uma única solicitação, faça o seguinte:
- Crie uma solicitação
POST
para o URL da sessão retomável. - Adicione os dados do arquivo ao corpo da solicitação.
Adicione os cabeçalhos HTTP a seguir:
Content-Length
: defina como o número de bytes no .- Defina
X-Goog-Upload-Command
comoupload, finalize
.
Envie a solicitação.
Se a solicitação de upload for interrompida ou você receber uma 5xx
resposta, siga o procedimento em Como retomar uma
upload interrompido.
Se a solicitação for bem-sucedida, você vai receber um código de status HTTP 200 OK
e um token de upload no corpo da resposta.
Criar
o item de mídia usando esse token de upload.
Várias partes
Para fazer upload do arquivo em várias partes, faça o seguinte:
- Crie uma solicitação
POST
para o URL da sessão retomável. -
Adicione os dados de cada parte ao corpo da solicitação.
Exceto pela parte final que conclui o upload, crie a outros pedaços em múltiplos do tamanho aceito de partes. Mantenha o o maior tamanho possível, para que o upload seja eficiente.
-
Adicione os cabeçalhos HTTP a seguir:
Content-Length
: defina como o número de bytes no bloco.- Defina
X-Goog-Upload-Command
comoupload
. Para o último bloco, defina comoupload, finalize
. X-Goog-Upload-Offset
: defina o deslocamento em que o bytes serão gravados. É preciso fazer o upload dos bytes em série. O primeiro deslocamento é0
.
- Envie a solicitação.
Se a solicitação de upload for interrompida ou você receber uma
5xx
resposta, siga o procedimento em Como retomar uma upload interrompido. - Repita essas etapas para cada parte restante do arquivo.
Se a solicitação for bem-sucedida, você receberá um status HTTP 200 OK
e um token de upload no corpo da resposta.
Criar
o item de mídia usando esse token de upload.
Exemplo
Solicitação única
O exemplo a seguir mostra uma solicitação retomável para fazer upload de um arquivo JPEG de 3.039.417 bytes em uma única solicitação.
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
A resposta contém o URL de upload e o tamanho do bloco esperado:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
A última solicitação de upload:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
Várias partes
O exemplo a seguir mostra uma solicitação retomável para fazer upload de um
Arquivo JPEG de 3.039.417 bytes em vários fragmentos, usando a sessão retomável
o URL e a granularidade do tamanho do fragmento aceito obtida na etapa anterior.
Este exemplo usa um bloco de 262.144 bytes que foi retornado no
campo de cabeçalho, x-goog-upload-chunk-granularity
, quando
de upload foi inicializada. Cada upload contém bytes que
estão em múltiplos de 262.144.
Inicializar a sessão de upload para receber o URL de upload e o tamanho do fragmento conforme descrito na etapa anterior:
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
A resposta contém o URL de upload e o tamanho do bloco esperado:
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
Primeira parte:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
Segundo bloco:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
Último bloco:
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
Como retomar um upload interrompido
Se a solicitação de upload for interrompida ou você receber um status HTTP diferente de 200
consulta o servidor para saber quanto do upload foi bem-sucedido.
Aqui está uma solicitação POST
para o URL de sessão retomável. X-Goog-Upload-Command
precisa ser definido como query
.
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
A resposta do servidor inclui um código de status HTTP 200 OK
e o
tamanho atual do upload.
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
Você pode retomar o upload nesse deslocamento. É necessário retomar no deslocamento fornecido pelo servidor, a menos que você envie um comando combinado de upload e finalização. Nesse caso, também é possível retomar no deslocamento 0.
Se o cabeçalho X-Goog-Upload-Status
na resposta HTTP do comando de consulta
estiver presente e o valor não for active
, isso indica que o upload já
foi encerrado.