Como fazer uploads retomáveis

Nesta página, você aprenderá como fazer uma solicitação de upload retomável nas APIs JSON e XML do Cloud Storage. Com esse protocolo, é possível retomar operações de upload quando uma falha de comunicação interrompe o fluxo de dados. Para mais detalhes sobre esse recurso e quando usá-lo, consulte Uploads retomáveis.

Como iniciar uma sessão de upload retomável

Para iniciar uma sessão de upload retomável, siga estas etapas, siga estas etapas:

API JSON

  1. Crie uma solicitação POST para o URI https://storage.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/o.
  2. Adicione o parâmetro de consulta uploadType=resumable. Por exemplo, no caso de um intervalo chamado myBucket:

    POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable
  3. Se você não tiver os metadados do arquivo, adicione um parâmetro de consulta name para identificar a que recurso o upload está associado. Por exemplo, para especificar que o nome de um objeto é myObject:

    POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&name=myObject
  4. Se você tiver os metadados do arquivo, adicione-os ao corpo da solicitação no formato JSON. Caso contrário, deixe o corpo em branco.

  5. Adicione os cabeçalhos HTTP a seguir:

    • X-Upload-Content-Type: opcional. Defina como o tipo MIME dos dados de arquivo, que serão transferido nas solicitações subsequentes. Se esse tipo não for especificado nos metadados ou neste cabeçalho, o objeto será exibido como application/octet-stream (em inglês).
    • X-Upload-Content-Length: opcional. Defina como o número de bytes dos dados do arquivo, que serão transferidos nas solicitações subsequentes.
    • Content-Type: obrigatório se você tiver os metadados do arquivo. Defina como application/json; charset=UTF-8.
    • Content-Length: obrigatório, exceto se você estiver usando codificação de transferência em partes (em inglês). Defina como o número de bytes no corpo dessa solicitação inicial.
    • Origin: se o Compartilhamento de recursos entre origens estiver ativado, você também precisará usar este cabeçalho nas solicitações de upload subsequentes.
  6. Envie a solicitação.

Exemplo

O exemplo abaixo mostra como iniciar uma sessão retomável usando um intervalo chamado myBucket. Use o OAuth 2.0 Playground (em inglês) para receber um token de acesso de autorização.

POST https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable HTTP/1.1
  Authorization: Bearer [YOUR_AUTH_TOKEN]
  Content-Length: 38
  Content-Type: application/json; charset=UTF-8
  X-Upload-Content-Type: image/jpeg
  X-Upload-Content-Length: 2000000
  {
    "name": "myObject"
  }

Na próxima seção, você verá como processar a resposta.

API XML

Para iniciar um upload retomável, envie uma solicitação POST Object para o Cloud Storage. A solicitação POST Object não contém o arquivo que você está enviando. Na verdade, ela contém alguns cabeçalhos que informam ao sistema do Cloud Storage que você quer fazer um upload retomável. Especificamente, a solicitação POST Object precisa ter estes elementos:

Exemplo O exemplo abaixo mostra como iniciar o upload retomável de um arquivo chamado music.mp3, que está sendo enviado para um intervalo com o nome example.

    POST /music.mp3 HTTP/1.1
    Host: example.storage.googleapis.com
    Date: Fri, 01 Oct 2010 21:56:18 GMT
    Content-Length: 0
    Content-Type: audio/mpeg
    x-goog-resumable: start
    Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
    

Como salvar o URI da sessão retomável

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

API JSON

Se a solicitação para iniciar a sessão for bem-sucedida, a resposta incluirá um código de status HTTP 200 OK. Além disso, ela incluirá um cabeçalho Location que especifica o URI da sessão retomável. Use esse URI para fazer upload dos dados do arquivo e consultar o status da operação.

Exemplo

O exemplo abaixo mostra uma resposta que inclui um URI de sessão de upload retomável para um intervalo chamado myBucket:

HTTP/1.1 200 OK
  Location: https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2
  Content-Length: 0

API XML

Depois que você inicia o upload retomável com uma solicitação POST Object, o Cloud Storage responde com uma mensagem de status 201 Created. Essa mensagem inclui um cabeçalho Location, que tem como valor o URI da sessão retomável. Salve esse URI porque ele será usado em todas as demais solicitações durante a operação de upload.

Exemplo O exemplo abaixo mostra a resposta à solicitação Post Object exibida em "Como iniciar uma sessão de upload retomável".

  HTTP/1.1 201 Created
  Location: https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 0
  Content-Type: audio/mpeg
  

Como fazer upload do arquivo

API JSON

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

  • Em uma única solicitação: geralmente, esta abordagem é a ideal porque requer menos solicitações e, portanto, tem melhor desempenho.
  • Em várias partes: use esta abordagem nos casos a seguir:

    • 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, como ocorre em certas classes de solicitações do Google App Engine.
    • Se você precisar fornecer um indicador personalizado que mostre o andamento do upload.

Uma única solicitação

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

  1. Crie uma solicitação PUT para o URI da sessão retomável.
  2. Adicione os dados do arquivo ao corpo da solicitação.
  3. Inclua um cabeçalho HTTP Content-Length definido como o número de bytes no arquivo.
  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.

Se a solicitação for bem-sucedida, você receberá uma resposta 200 OK ou 201 Created, além de todos os metadados associados ao recurso.

Exemplo O exemplo abaixo mostra uma solicitação retomável para fazer o upload de um arquivo JPEG inteiro com 2 milhões de bytes para myBucket, usando o URI recebido anteriormente:

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg
Content-Range: bytes 0-1999999

Em várias partes

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

  1. Crie uma solicitação PUT para o URI 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 256 KB (256 x 1.024 bytes), exceto a parte final que conclui o upload. Esse tamanho precisa ser o maior possível para que o upload seja eficiente.
  3. Inclua os seguintes cabeçalhos HTTP:
    • Content-Length: defina como o número de bytes na parte atual.
    • Content-Range: configure para mostrar quais bytes do arquivo estão sendo enviados. Por exemplo, Content-Range: bytes 0-524287/2000000 mostra que está sendo feito o upload dos primeiros 524.288 bytes (256 x 1.024 x 2) de um arquivo com 2 milhões de bytes.
  4. Envie a solicitação e processe a resposta. 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. Use o cabeçalho Range na resposta para determinar o início da próxima parte. Não pressuponha que o servidor recebeu todos os bytes enviados na solicitação anterior.

Quando o upload do arquivo inteiro estiver concluído, você receberá uma resposta 200 OK ou 201 Created, além dos metadados associados ao recurso.

Exemplo

O exemplo abaixo mostra uma solicitação que envia os primeiros 524.288 bytes (512 KB) do arquivo para myBucket, usando o URI de sessão retomável recebido anteriormente:

PUT https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
      Content-Length: 524288
      Content-Type: image/jpeg
      Content-Range: bytes 0-524287/2000000 

Se a solicitação for bem-sucedida, a resposta do servidor será 308 Resume Incomplete' along with a, com um cabeçalho Ranger, que identifica o número total de bytes armazenados até o momento:

HTTP/1.1 308 Resume Incomplete
    Content-Length: 0
    Content-Range: bytes=0-524287

Use o valor superior retornado no cabeçalho Range para determinar onde iniciar a próxima parte. Continue fazendo operações PUT para cada parte do arquivo até que ele tenha sido totalmente enviado.

Quando upload estiver completamente concluído, você receberá uma resposta 200 OK ou 201 Created, além de todos os metadados associados ao recurso.

API XML

Implemente uma solicitação PUT Object que envie os blocos do arquivo para o Cloud Storage. Como URI da solicitação PUT, use aquele que você recebeu anteriormente. Essa solicitação também inclui um cabeçalho Content-Length, que você precisará usar para especificar o tamanho do arquivo sendo enviado.

Assim como em POST Object, use o nome de host padrão do Cloud Storage nessa solicitação (storage.googleapis.com). Você não precisa usar explicitamente um token de autenticação porque, na verdade, o URI da sessão já é um.

Exemplo

O exemplo abaixo mostra como enviar o arquivo music.mp3 em uma operação de upload retomável que já foi iniciada:

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 21:56:18 GMT
  Content-Length: 7351375
  

Se a solicitação PUT Object não for interrompida e o upload do arquivo for concluído com sucesso, o Cloud Storage responderá com um código de status 200 OK. Se o upload for interrompido, bastará retomá-lo.

Por meio de outra solicitação PUT Object, faça uma consulta para saber o número de bytes que já foram recebidos. Essa solicitação PUT Object precisa ter os seguintes elementos:

O valor do cabeçalho de solicitação Content-Range precisa estar no seguinte formato:

Content-Range: bytes */<content-length>

Em que &lt;content-length&gt; é o valor do cabeçalho Content-Length especificado na solicitação PUT Object original.

Além disso, use o nome de host padrão do Cloud Storage na solicitação (storage.googleapis.com).

O exemplo abaixo mostra como consultar o sistema do Cloud Storage após um upload retomável ser interrompido:

  PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
  Date: Fri, 01 Oct 2010 22:25:53 GMT
  Content-Range: bytes */7351375
  Content-Length: 0
  

Como retomar um upload interrompido

Caso a solicitação de upload seja encerrada antes de você receber uma resposta ou se você receber uma resposta de serviço indisponível 503 ou 500, significará que será necessário retomar o upload. Para retomar um upload interrompido, siga estas etapas:

API JSON

  1. Para saber o status do upload, crie uma solicitação PUT vazia para o URI de sessão retomável.
  2. Inclua um cabeçalho Content-Range indicando que a posição atual no arquivo é desconhecida.

    Por exemplo, defina Content-Range como */2000000 se o tamanho total do arquivo for 2 milhões de bytes.

    Se você não souber o tamanho total do arquivo, defina Content-Range como */*.

  3. Envie a solicitação.

  4. Processe a resposta.

    • Uma resposta 200 OK ou 201 Created indica que o upload foi concluído e não é necessário realizar qualquer outra ação.
    • Uma resposta 308 Resume Incomplete indica que você precisa continuar fazendo o upload do arquivo.
  5. Se você recebeu uma resposta 308 Resume Incomplete, processe o cabeçalho Range, que especifica quais bytes o Cloud Storage recebeu até o momento. Você usará esse número na próxima etapa. A resposta não terá esse cabeçalho Range se o Cloud Storage não tiver recebido nenhum byte.

    Por exemplo, um cabeçalho Range com valor bytes=0-42 indica que os primeiros 43 bytes do arquivo foram recebidos.

  6. Agora que você já sabe em que ponto retomar o upload, continue a operação enviando os dados restantes ou a próxima parte. Inclua um cabeçalho Content-Range indicando qual parte do arquivo está sendo enviada.

    Por exemplo, Content-Range: bytes 43-1999999/2000000 indica que você está enviando os bytes 43 a 1.999.999.

API XML

É possível retomar a operação de upload enviando uma solicitação PUT Object. Essa solicitação PUT Object precisa ter os seguintes elementos:

  • Um corpo de entidade que contenha o intervalo de bytes que ainda precisa ser enviado. Para determinar esse intervalo, subtraia o valor de Range (que você recebeu anteriormente) do valor de Content-Length.
  • Um cabeçalho Content-Length especificando o número de bytes que serão enviados na solicitação atual.
  • Um cabeçalho Content-Range especificando o intervalo de bytes que será enviado na solicitação.
  • Um URI de solicitação igual ao da sessão para o upload retomável.

    É necessário usar o nome de host padrão do Cloud Storage na solicitação (storage.googleapis.com).

Exemplo

O exemplo abaixo mostra uma solicitação PUT Object que retoma o upload do arquivo music.mp3 no intervalo de amostra.

PUT https://example.storage.googleapis.com/music.mp3?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
Date: Fri, 01 Oct 2010 22:25:53 GMT
Content-Range: bytes 2359296-7351374/7351375
Content-Length: 4992079

É possível retomar os uploads quantas vezes forem necessárias. Porém, ao tentar fazer as novas solicitações, use a estratégia de espera exponencial truncada. Por exemplo, veja a implementação boto (em inglês) dessa lógica.

Quando o upload do arquivo for concluído com sucesso, o Cloud Storage responderá com um código de status 200 OK.

Leia mais detalhes sobre a otimização opcional .

Como cancelar um upload

Se você quiser cancelar o upload e impedir qualquer ação futura nele, emita uma solicitação DELETE no URI exclusivo do upload. Depois que a solicitação DELETE for concluída com sucesso, as futuras tentativas de consultar ou retomar o upload resultarão em uma resposta 4xx.

API JSON

Exemplo

O exemplo abaixo mostra como cancelar um upload retomável:

DELETE https://storage.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 0

API XML

Se você quiser cancelar o upload e impedir qualquer ação futura nele, emita uma solicitação DELETE no URI exclusivo do upload. Depois que a solicitação DELETE for concluída com sucesso, as futuras tentativas de consultar ou retomar o upload resultarão em uma resposta 4xx.

Exemplo

O exemplo abaixo mostra como cancelar um upload retomável:

 DELETE https://example.storage.googleapis.com/myFile.zip?upload_id=tvA0ExBntDa...gAAEnB2Uowrot HTTP/1.1
    Content-Length: 0

A seguir