Uploads recuperáveis

Nesta página, descrevemos 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 interromper 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 de rede ou alguma outra falha de transmissão é alta (por exemplo, se você estiver fazendo upload de um arquivo de um app para dispositivos móveis).

Os uploads recuperáveis também podem reduzir o uso da largura de banda quando há uma falha de rede, porque você não precisa reiniciar os uploads de arquivos grandes desde o início.

Etapa 1: iniciar uma sessão de upload

Inicie uma sessão de upload retomável enviando uma solicitação POST para https://photoslibrary.googleapis.com/v1/uploads. Usando o URL de upload retomável retornado nesta solicitação, faça upload do arquivo.

A solicitação POST precisa incluir os seguintes cabeçalhos:

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 bem-sucedida, a solicitação POST vai retornar um código de status HTTP 200 OK, incluindo o 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, precisam ser feitos 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 bytes restantes.

O campo de cabeçalho X-Goog-Upload-URL contém um URL exclusivo que precisa ser usado para concluir o upload em 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 o upload do arquivo

Há duas formas de fazer o upload de um arquivo com uma sessão retomável:

1. Em uma única solicitação: Essa abordagem geralmente é a melhor, porque requer menos solicitações e, portanto, tem melhor desempenho.

2. Em várias partes: Nessa abordagem, os uploads são feitos em várias solicitações, dividindo os dados. Os dados são divididos em múltiplos de x-goog-upload-chunk-granularity. Se necessário, as solicitações fragmentadas podem ser tentadas novamente.

   use esta abordagem nos casos a seguir:

   • Você precisa reduzir a quantidade de dados transferidos em uma única solicitação. Talvez seja necessário fazer isso quando houver um limite de tempo fixo para solicitações individuais.
   • Você precisa fornecer um indicador personalizado que mostre o andamento do upload.
   • Você precisa saber quando é seguro descartar dados.

Exemplo

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]

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

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]

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]

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

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]

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]

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 se você receber um código de status HTTP diferente de 200, consulte o servidor para descobrir o 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.