Como executar um upload retomável

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

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: 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: defina 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 abaixo 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 é 4200000. 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 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

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 nas solicitações posteriores.

Exemplo: como salvar o URL de 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 única solicitação. Talvez seja necessário fazer isso quando houver um limite de tempo fixo para solicitações individuais.
    • Se você precisar fornecer um indicador personalizado que mostre o andamento 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: definido 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árias partes

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 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 o deslocamento em que os bytes serão 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: upload do arquivo

Solicitação única

O exemplo abaixo mostra uma solicitação retomável para fazer upload de um arquivo JPEG inteiro de 4,2 milhões de bytes em uma única solicitação, usando o URL de sessão retomável recebido 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árias partes

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 fragmentos, usando o URL de sessão retomável e a granularidade de tamanho obtida na etapa anterior. Este exemplo usa um tamanho de bloco de 2097000 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]

Segundo 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: 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 diferente de 200, consulte o servidor para descobrir o 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 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

Depois, 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, o upload já terá sido encerrado.