Como executar um upload retomável

Esta página descreve como fazer uma solicitação de upload retomável na API Street View Publishing. 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 o 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 retomá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.

Se você estiver enviando arquivos pequenos por uma conexão de rede confiável, use um upload simples.

Como iniciar uma sessão de upload retomável

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

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

  2. Adicione os cabeçalhos HTTP a seguir:

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

  3. Envie a solicitação.

Exemplo: 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. Nesse caso, o arquivo é uma imagem, e o número total de bytes no arquivo é 4200000. 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

Salvar o URL da sessão retomável descreve como lidar com a resposta da solicitação para iniciar a sessão de upload retomável.

Como salvar o URL da sessão retomável

No caso da solicitação enviada para iniciar uma sessão de upload retomável, o servidor 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 de resiliência retomável para poder usá-lo nas solicitações subsequentes.

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

O exemplo a seguir mostra uma resposta que inclui um URL de sessão 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: Essa abordagem geralmente é a melhor, porque requer menos solicitações e, portanto, tem melhor desempenho.
  2. Em várias partes: Use essa abordagem se:
    • Você precisa reduzir a quantidade de dados transferidos em uma solicitação única. 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 progresso do upload.
    • Você precisa 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 blocos em múltiplos de 2 MiB (mebibytes), exceto o fragmento final que conclui o upload. Mantenha o tamanho das partes no maior tamanho 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 do bloco.
    • Defina X-Goog-Upload-Command como upload. Para a última parte, defina como upload, finalize.
    • X-Goog-Upload-Offset: definido como o deslocamento em que os bytes precisam ser gravados. Observe que é preciso fazer o upload dos bytes 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 a seguir mostra uma solicitação retomável para fazer upload de um arquivo JPEG inteiro de 4.200.000 bytes em uma única solicitação usando o URL da sessão retomável da 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ê 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 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 recebida na etapa anterior. Nesse exemplo, usamos um tamanho de bloco de 2097.000 bytes, que é um múltiplo de 2 MiB (mebibytes).

Primeiro bloco: 

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]

Segunda parte: 

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 bloco: 

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 que não seja 200, consulte o servidor para saber quanto do upload foi bem-sucedido:

  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 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

Depois, você pode retomar o envio nesse deslocamento. É preciso 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, o upload já foi encerrado.