Como executar um upload retomável

Nesta página, descrevemos como fazer uma solicitação de upload retomável na API Street View Publish. Esse protocolo permite retomar uma operação de upload quando uma falha de comunicação interrompe o fluxo de dados. Use essa opção se:

  • Você está fazendo upload de arquivos grandes.
  • A probabilidade de interrupção da rede ou 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 retomáveis também podem reduzir o uso da largura de banda quando há uma falha de rede, porque não é necessário reiniciar os uploads de arquivos grandes desde o início.

Caso esteja enviando arquivos pequenos por meio de uma conexão de rede confiável, use um upload simples.

Como iniciar uma sessão de upload retomável

Depois de conseguir um uploadUrl, é possível iniciar uma sessão de upload retomável:

  1. Crie uma solicitação POST para uploadUrl.

  2. Adicione os cabeçalhos HTTP a seguir:

    • Defina X-Goog-Upload-Protocol como resumable.
    • X-Goog-Upload-Header-Content-Length: definido como o número total de bytes dos dados do arquivo, que serão transferidos em solicitações subsequentes.
    • X-Goog-Upload-Header-Content-Type: definido como o tipo MIME dos dados do arquivo.
    • Defina X-Goog-Upload-Command como start.

  3. Envie a solicitação.

Exemplo: como iniciar uma sessão de upload retomável

O exemplo a seguir mostra como iniciar uma sessão retomável para fazer upload de um novo arquivo. Neste caso, o arquivo é uma imagem e o número total de bytes no arquivo é 4.200.000. Observe que o corpo da solicitação está vazio. Portanto, o cabeçalho Content-Length está definido como 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Como salvar o URL da sessão retomável descreve como processar a resposta da solicitação para iniciar a sessão de upload retomável.

Como salvar o URL da sessão retomável

Para a solicitação enviada para iniciar uma sessão de upload retomável, o servidor vai responder com um código de status HTTP 200 OK, incluindo o seguinte cabeçalho:

  • X-Goog-Upload-URL: um URL exclusivo que precisa ser usado para concluir o upload em todas as solicitações restantes.

Copie e salve o URL da sessão retomável para usá-lo em solicitações subsequentes.

Exemplo: como salvar o URL da sessão retomável

O exemplo a seguir mostra uma resposta que inclui um URL de sessão de upload retomável e um requisito de granularidade de tamanho.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Como fazer 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: geralmente, esta abordagem é a ideal porque requer menos solicitações e, portanto, tem melhor desempenho.
  2. Em várias partes: Use essa abordagem se:
    • Se você precisar reduzir a quantidade de dados transferidos em uma única solicitação. Por exemplo, talvez seja necessário adotar esta abordagem quando há um limite de tempo fixo para as solicitações individuais.
    • Se você precisar fornecer um indicador personalizado que mostre o andamento do upload.
    • É preciso saber quando é seguro descartar dados.

Solicitação única

Para fazer upload do arquivo em uma única solicitação, faça o seguinte:

  1. Crie uma solicitação POST para o URL da sessão retomável.
  2. Adicione os dados do arquivo ao corpo da solicitação.

  3. Adicione os cabeçalhos HTTP a seguir:

    • Content-Length: defina como o número de bytes no arquivo.
    • Defina X-Goog-Upload-Command como upload, finalize.

  4. Envie a solicitação.

Se a solicitação de upload for interrompida ou você receber uma resposta 5xx, siga o procedimento em Como retomar um upload interrompido.

Vários pedaços

Para fazer upload do arquivo em várias partes, faça o seguinte:

  1. Crie uma solicitação POST para o URL da sessão retomável.
  2. Adicione os dados de cada parte ao corpo da solicitação. Crie partes com tamanho em múltiplos de 2 MiB (mebibytes), exceto a parte final que conclui o upload. Esse tamanho precisa ser o maior possível para que o upload seja eficiente.

  3. Adicione os cabeçalhos HTTP a seguir:

    • Content-Length: defina como o número de bytes no bloco.
    • Defina X-Goog-Upload-Command como upload. Para o último bloco, defina como upload, finalize.
    • X-Goog-Upload-Offset: defina como o deslocamento em que os bytes devem ser gravados. Os bytes precisam ser enviados em série.

  4. Envie a solicitação. Se a solicitação de upload for interrompida ou você receber uma resposta 5xx, siga o procedimento em Como retomar um upload interrompido.

  5. Repita as etapas 1 a 4 para cada parte restante do arquivo.

Exemplo: como fazer upload do arquivo

Solicitação única

O exemplo abaixo mostra uma solicitação retomável para fazer o upload de um arquivo JPEG inteiro com 4,2 milhões de bytes em uma única solicitação, usando o URL da sessão retomável obtido na etapa anterior:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Se a solicitação for bem-sucedida, você vai receber um código de status HTTP 200 OK.

Vários pedaços

O exemplo a seguir mostra uma solicitação retomável para fazer o upload de um arquivo JPEG de 4.200.000 bytes em vários blocos, usando o URL da sessão retomável e a granularidade de tamanho obtida na etapa anterior. Este exemplo usa um tamanho de parte de 2097000 bytes, que é um múltiplo de 2 MiB (mebibytes).

Primeiro trecho: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Segundo trecho: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Último trecho: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Como retomar um upload interrompido

Se a solicitação de upload for interrompida ou se você receber um código de status HTTP não 200, consulte o servidor para saber quanto do upload foi concluído:

  1. Crie uma solicitação POST para o URL da sessão retomável.
  2. Defina X-Goog-Upload-Command como query.
  3. Envie a solicitação.

O servidor vai responder com 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

Em seguida, retome o upload nesse ponto. Você precisa retomar no deslocamento fornecido pelo servidor, a menos que 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, o upload já terá sido encerrado.