Como fazer uploads recuperáveis

Acessar conceitos

Nesta página, descrevemos 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.

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. Consiga um token de acesso de autorização do OAuth 2.0 Playground (em inglês). Configure o Playground para usar suas credenciais do OAuth.
  2. Outra opção é criar um arquivo .json com os metadados que você quer definir no objeto que está enviando.

  3. Use cURL para chamar a API JSON com uma solicitação de POST Objeto:

    curl -i -X POST --data-binary @METADATA_LOCATION \
        -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Type: application/json" \
        -H "Content-Length: INITIAL_REQUEST_LENGTH" \
        "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

    Em que:

    • METADATA_LOCATION é o caminho local do arquivo JSON que contém os metadados opcionais especificados na etapa anterior. Se você não estiver incluindo um arquivo de metadados, exclua esse caminho, junto com --data-binary @ e o cabeçalho Content-Type.
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • INITIAL_REQUEST_LENGTH é o número de bytes no corpo dessa solicitação inicial, por exemplo, 79. Não é obrigatório em caso de uso da codificação de transferência fragmentada.
    • BUCKET_NAME é o nome do bucket de upload do objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome que você quer dar ao objeto. Por exemplo, pets/dog.png. Isso não será necessário se você tiver incluído um name no arquivo de metadados do objeto na Etapa 2.

    Se você tiver ativado o Compartilhamento de recursos entre origens, também deverá incluir um cabeçalho Origin nessa solicitação de upload e nas próximas.

    Entre os cabeçalhos opcionais que podem ser adicionados à solicitação estão X-Upload-Content-Type e X-Upload-Content-Length.

    Se a operação for bem-sucedida, a resposta incluirá um código de status 200.

  4. Salve o URI da sessão retomável fornecido no cabeçalho Location da resposta à sua solicitação de objeto POST.

    Esse URI é usado em solicitações subsequentes para fazer upload dos dados do objeto.

API XML

  1. Consiga um token de acesso de autorização do OAuth 2.0 Playground (em inglês). Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API XML com uma solicitação de objeto POST com um corpo vazio:

    curl -i -X POST -H "Authorization: Bearer OAUTH2_TOKEN" \
        -H "Content-Length: 0" \
        -H "Content-Type: OBJECT_CONTENT_TYPE" \
        -H "x-goog-resumable: start" \
        "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • OBJECT_CONTENT_TYPE é o tipo de conteúdo do objeto. Por exemplo, image/png. Se você não especificar um tipo de conteúdo, o sistema do Cloud Storage definirá os metadados Content-Type do objeto como application/octet-stream.
    • BUCKET_NAME é o nome do bucket em que você fará o upload do objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome que você quer dar ao objeto. Por exemplo, pets/dog.png.

    Se você tiver ativado o Compartilhamento de recursos entre origens, também deverá incluir um cabeçalho Origin nessa solicitação de upload e nas próximas.

    Se a operação for bem-sucedida, a resposta incluirá uma mensagem de status 201.

  3. Salve o URI da sessão retomável fornecido no cabeçalho Location da resposta à sua solicitação de objeto POST.

    Esse URI é usado em solicitações subsequentes para fazer upload dos dados do objeto.

Como fazer upload do arquivo

Depois de iniciar um upload retomável, há duas maneiras de fazer upload dos dados do objeto:

  • Em uma única solicitação: essa abordagem costuma ser melhor, já que requer menos solicitações e, portanto, tem melhor desempenho.
  • Em vários blocos: use essa abordagem se você precisar reduzir a quantidade de dados transferidos em qualquer solicitação única, como quando há um limite de tempo fixo para solicitações individuais ou quando você não sabe o tamanho total do upload no momento do envio.

Upload de solicitação única

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

API JSON

  1. Use cURL para chamar a API JSON com uma solicitação de objeto PUT.

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • OBJECT_LOCATION é o caminho local do objeto. Por exemplo, Desktop/dog.png.
    • OBJECT_SIZE é o número de bytes no objeto. Por exemplo, 20000000.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

API XML

  1. Use cURL para chamar a API XML com uma solicitação de objeto PUT.

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
        -H "Content-Length: OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • OBJECT_LOCATION é o caminho local do objeto. Por exemplo, Desktop/dog.png.
    • OBJECT_SIZE é o número de bytes no objeto. Por exemplo, 20000000.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

Se o upload for concluído na íntegra, você receberá uma resposta 200 OK ou 201 Created, com todos os metadados associados ao recurso.

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

Upload de várias partes

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

API JSON

  1. Crie um bloco de dados do arquivo a ser enviado.

    O tamanho do bloco será um múltiplo de 256 KiB (256 x 1.024 bytes), a menos que seja o último bloco que conclui o upload. Blocos de tamanhos maiores normalmente tornam os envios mais eficientes. Recomendamos usar 8 MiB para o tamanho do bloco.

  2. Use cURL para chamar a API JSON com uma solicitação de objeto PUT.

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • CHUNK_LOCATION é o caminho local para o bloco que você está enviando no momento.
    • CHUNK_SIZE é o número de bytes que você está enviando na solicitação atual. Por exemplo, 524288.
    • CHUNK_FIRST_BYTE é o byte inicial no objeto geral contido no bloco que você está enviando.
    • CHUNK_LAST_BYTE é o byte final no objeto geral contido no bloco que você está enviando.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que você está enviando.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

    Um Content-Range de exemplo é Content-Range: bytes 0-524287/2000000. Consulte Content-Range para mais informações sobre esse cabeçalho.

    Se a solicitação for bem-sucedida, o servidor responderá com 308 Resume Incomplete. A resposta contém um cabeçalho Range. Use o valor superior deste cabeçalho para determinar onde iniciar o próximo bloco. Não suponha que o servidor recebeu todos os bytes enviados na solicitação.

  3. Repita as etapas acima para cada bloco restante dos dados que você quer enviar.

API XML

  1. Crie um bloco de dados do arquivo a ser enviado.

    O tamanho do bloco será um múltiplo de 256 KiB (256 x 1.024 bytes), a menos que seja o último bloco que conclui o upload. Blocos de tamanhos maiores normalmente tornam os envios mais eficientes. Recomendamos usar 8 MiB para o tamanho do bloco.

  2. Use cURL para chamar a API XML com uma solicitação de objeto PUT.

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
        -H "Content-Length: CHUNK_SIZE" \
        -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • CHUNK_LOCATION é o caminho local para o bloco que você está enviando no momento.
    • CHUNK_SIZE é o número de bytes que você está enviando na solicitação atual. Por exemplo, 524288.
    • CHUNK_FIRST_BYTE é o byte inicial no objeto geral contido no bloco que você está enviando.
    • CHUNK_LAST_BYTE é o byte final no objeto geral contido no bloco que você está enviando.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que você está enviando.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

    Um Content-Range de exemplo é Content-Range: bytes 0-524287/2000000. Consulte Content-Range para mais informações sobre esse cabeçalho.

    Se a solicitação for bem-sucedida, o servidor responderá com 308 Resume Incomplete. A resposta contém um cabeçalho Range. Use o valor superior deste cabeçalho para determinar onde iniciar o próximo bloco. Não suponha que o servidor recebeu todos os bytes enviados na solicitação.

  3. Repita as etapas acima para cada bloco restante dos dados que você quer enviar.

Depois que o upload for concluído, você receberá uma resposta 200 OK ou 201 Created, com todos os metadados associados ao recurso.

Se algum dos uploads das partes for interrompido, ou se você receber uma resposta 5xx, siga o procedimento em Como retomar um upload interrompido.

Como verificar o status de um upload retomável

Se o upload retomável for interrompido ou você não tiver certeza se ele foi mesmo concluído, verifique o status do upload:

API JSON

  1. Use cURL para chamar a API XML com uma solicitação de objeto PUT.

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • OBEJCT_SIZE é o número total de bytes no objeto. Se você não souber o tamanho total do objeto, use * para esse valor.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

API XML

  1. Use cURL para chamar a API XML com uma solicitação de objeto PUT.

    curl -i -X PUT \
        -H "Content-Length: 0" \
        -H "Content-Range: bytes */OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • OBEJCT_SIZE é o número total de bytes no objeto. Se você não souber o tamanho total do objeto, use * para esse valor.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

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.

  • Se o Cloud Storage ainda não tiver recebido bytes, a resposta 308 não terá um cabeçalho Range. Nesse caso, inicie o upload desde o início.
  • Caso contrário, a resposta 308 terá um cabeçalho Range, que especifica quais bytes o Cloud Storage recebeu até o momento. Use esse valor ao retomar um upload interrompido.

Como retomar um upload interrompido

Se uma solicitação de upload for encerrada antes de receber uma resposta ou se você receber uma resposta 503 ou 500, será necessário retomar o upload interrompido do ponto em que parou. Para retomar um upload interrompido:

API JSON

  1. Verifique o status do upload retomável.

  2. Salve o valor superior do cabeçalho Range contido na resposta à verificação de status. Se a resposta não tiver um cabeçalho Range, o Cloud Storage ainda não recebeu bytes e você precisará fazer o upload desde o início.

  3. Verifique se os dados do objeto que você está prestes a enviar começam no byte após o valor superior do cabeçalho Range.

  4. Use cURL para chamar a API JSON com uma solicitação de objeto PUT que faz a coleta no byte após o valor superior do cabeçalho Range:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • PARTIAL_OBJECT_LOCATION é o caminho local para a parte restante dos dados que você quer enviar.
    • UPLOAD_SIZE_REMAINING é o número de bytes que você está enviando na solicitação atual. Por exemplo, fazer o upload do restante de um objeto com tamanho total de 20000000 que foi interrompido após o envio de 0-42 bytes terá um UPLOAD_SIZE_REMAINING de 1999957.
    • NEXT_BYTE é o próximo número inteiro após o valor salvo na Etapa 2. Por exemplo, se 42 for o valor superior na Etapa 2, o valor de NEXT_BYTE será 43.
    • LAST_BYTE é o byte final contido nesta solicitação de PUT. Por exemplo, para concluir o upload de um objeto com tamanho total de 20000000, o valor de LAST_BYTE será 1999999.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que você está enviando. Por exemplo, 20000000.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

API XML

  1. Verifique o status do upload retomável.

  2. Salve o valor superior do cabeçalho Range contido na resposta à verificação de status. Se a resposta não tiver um cabeçalho Range, o Cloud Storage ainda não recebeu bytes e você precisará fazer o upload desde o início.

  3. Verifique se os dados do objeto que você está prestes a enviar começam no byte após o valor superior do cabeçalho Range.

  4. Use cURL para chamar a API XML com uma solicitação de objeto PUT que faz a coleta no byte após o valor no cabeçalho Range:

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
        -H "Content-Length: UPLOAD_SIZE_REMAINING" \
        -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
        "SESSION_URI"

    Em que:

    • PARTIAL_OBJECT_LOCATION é o caminho local para a parte restante dos dados que você quer enviar.
    • UPLOAD_SIZE_REMAINING é o número de bytes que você está enviando na solicitação atual. Por exemplo, fazer o upload do restante de um objeto com tamanho total de 20000000 que foi interrompido após o envio de 0-42 bytes terá um UPLOAD_SIZE_REMAINING de 1999957.
    • NEXT_BYTE é o próximo número inteiro após o valor salvo na Etapa 2. Por exemplo, se 42 for o valor superior na Etapa 2, o valor de NEXT_BYTE será 43.
    • LAST_BYTE é o byte final contido nesta solicitação de PUT. Por exemplo, para concluir o upload de um objeto com tamanho total de 20000000, o valor de LAST_BYTE será 1999999.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que você está enviando. Por exemplo, 20000000.
    • SESSION_URI é o valor retornado no cabeçalho Location quando você iniciou o upload retomável.

É possível retomar os uploads quantas vezes forem necessárias enquanto o URI da sessão estiver ativo. O URI da sessão expira após uma semana. Quando o arquivo for carregado, o Cloud Storage responderá com um código de status 200 OK ou 201 created.

Como cancelar um upload

Para cancelar um upload retomável e evitar outras ações nele:

API JSON

  1. Use cURL para chamar a API JSON com uma solicitação DELETE:

    curl -i -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    Em que:

Se funcionar, a resposta conterá o código de status 499. As tentativas futuras de consultar ou retomar o resultado do upload em uma resposta 4xx

API XML

  1. Use cURL para chamar a API XML com uma solicitação DELETE:

    curl -i -X DELETE -H "Content-Length: 0" \
      "SESSION_URI"

    Em que:

Se a resposta for bem-sucedida, ela conterá um código de status 204, e tentativas posteriores de consultar ou retomar o upload também resultarão em uma resposta 204.

A seguir