Faça carregamentos retomáveis

Overview

Esta página descreve como fazer um pedido de carregamento retomável nas APIs JSON e XML do Cloud Storage. Este protocolo permite-lhe retomar uma operação de carregamento depois de uma falha de comunicação interromper o fluxo de dados.

Para obter informações sobre a utilização de carregamentos retomáveis na CLI Google Cloud e nas bibliotecas de cliente, consulte o artigo Como as ferramentas e as APIs usam carregamentos retomáveis.

Funções necessárias

Para receber as autorizações necessárias para fazer um carregamento retomável, peça ao seu administrador que lhe conceda uma das seguintes funções:

  • Para carregamentos que incluam um bloqueio de retenção de objetos, peça ao seu administrador para lhe conceder a função de IAM de administrador de objetos de armazenamento (roles/storage.objectAdmin) para o contentor.

  • Para todos os outros casos, peça ao administrador que lhe conceda a função de IAM de utilizador do objeto de armazenamento (roles/storage.objectUser) para o contentor.

Estas funções predefinidas contêm as autorizações necessárias para carregar um objeto para um contentor para os respetivos casos. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

  • storage.objects.create
  • storage.objects.delete
    • Esta autorização só é necessária para carregamentos que substituam um objeto existente.
  • storage.objects.setRetention
    • Esta autorização só é necessária para carregamentos que incluam um bloqueio de retenção de objetos.

Também pode obter estas autorizações com outras funções predefinidas ou funções personalizadas.

Para ver informações sobre a concessão de funções em contentores, consulte o artigo Use o IAM com contentores.

Inicie uma sessão de carregamento retomável

Para iniciar uma sessão de carregamento retomável:

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Opcionalmente, crie um ficheiro JSON que contenha os metadados que quer definir no objeto que está a carregar. Por exemplo, o ficheiro JSON seguinte define os metadados contentType do objeto que quer carregar para image/png:

    {
    "contentType": "image/png"
}

  3. Use cURL para chamar a API JSON com um pedido de POST objeto:

    curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer $(gcloud auth print-access-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"

    Onde:

    • METADATA_LOCATION é o caminho local para o ficheiro JSON que contém os metadados opcionais especificados no passo anterior. Se não estiver a incluir um ficheiro de metadados, exclua esta opção, juntamente com --data-binary @ e o cabeçalho Content-Type.
    • INITIAL_REQUEST_LENGTH é o número de bytes no corpo deste pedido inicial, por exemplo, 79.
    • BUCKET_NAME é o nome do contentor para o qual está a carregar o seu objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome com codificação URL que quer dar ao objeto. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png. Isto não é necessário se tiver incluído um name no ficheiro de metadados do objeto no passo 2.

    Se ativou a partilha de recursos de origem cruzada, também deve incluir um cabeçalho Origin neste e nos pedidos de carregamento subsequentes.

    Os cabeçalhos opcionais que pode adicionar ao pedido incluem X-Upload-Content-Type e X-Upload-Content-Length.

    Se for bem-sucedido, a resposta inclui um código de estado 200 e tem um aspeto semelhante ao seguinte:

    HTTP/2 200
content-type: text/plain; charset=utf-8
x-guploader-uploadid: ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
location: https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=cat-pic.jpeg&upload_id=ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
date: Mon, 07 Jul 2025 14:57:21 GMT
vary: Origin
vary: X-Origin
cache-control: no-cache, no-store, max-age=0, must-revalidate
expires: Mon, 01 Jan 1990 00:00:00 GMT
pragma: no-cache
content-length: 0
server: UploadServer
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000

  4. Guarde o URI da sessão retomável indicado no cabeçalho location da resposta ao seu pedido de objeto POST.

    Este URI é usado em pedidos subsequentes para carregar os dados do objeto.

API XML

  1. Ter a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API XML com um pedido de POST objeto que tenha um corpo vazio:

    curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Onde:

    • OBJECT_CONTENT_TYPE é o tipo de conteúdo do objeto. Por exemplo, image/png. Se não especificar um tipo de conteúdo, o sistema do Cloud Storage define os metadados Content-Type do objeto como application/octet-stream.
    • BUCKET_NAME é o nome do contentor para o qual está a carregar o seu objeto. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome com codificação URL que quer dar ao seu objeto. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.

    Se ativou a partilha de recursos de origem cruzada, também deve incluir um cabeçalho Origin neste e nos pedidos de carregamento subsequentes.

    Se for bem-sucedido, a resposta inclui uma mensagem de estado 201.

  3. Guarde o URI da sessão retomável indicado no cabeçalho location da resposta ao seu pedido de objeto POST.

    Este URI é usado em pedidos subsequentes para carregar os dados do objeto.

Carregue os dados

Depois de iniciar um carregamento retomável, existem duas formas de carregar os dados do objeto:

  • Num único bloco: esta abordagem é geralmente a melhor, uma vez que requer menos pedidos e, por isso, tem um melhor desempenho.
  • Em vários blocos: use esta abordagem se precisar de reduzir a quantidade de dados transferidos num único pedido, como quando existe um limite de tempo fixo para pedidos individuais ou se não souber o tamanho total do carregamento no momento em que este começa.

Carregamento de fragmento único

Para carregar os dados num único bloco:

API JSON

  1. Use cURL para chamar a API JSON com um PUT pedido de objeto:

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

    Onde:

    • OBJECT_LOCATION é o caminho local para o seu objeto. Por exemplo, Desktop/dog.png.
    • OBJECT_SIZE é o número de bytes no seu objeto. Por exemplo, 20000000.
    • SESSION_URI é o valor devolvido no cabeçalho location quando iniciou o carregamento retomável.

    Opcionalmente, pode incluir cabeçalhos com o prefixo X-Goog-Meta- para adicionar metadados personalizados para o objeto como parte deste pedido.

API XML

  1. Use cURL para chamar a API XML com um PUT pedido de objeto:

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

    Onde:

    • OBJECT_LOCATION é o caminho local para o seu objeto. Por exemplo, Desktop/dog.png.
    • OBJECT_SIZE é o número de bytes no seu objeto. Por exemplo, 20000000.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

Se o carregamento for concluído na íntegra, recebe uma resposta 200 OK ou 201 Created, juntamente com todos os metadados associados ao recurso.

Se o pedido de carregamento for interrompido ou se receber uma resposta 5xx , siga o procedimento em Retomar um carregamento interrompido.

Carregamento de vários fragmentos

Para carregar os dados em vários blocos:

API JSON

  1. Crie um bloco de dados a partir dos dados gerais que quer carregar.

    O tamanho do fragmento deve ser um múltiplo de 256 KiB (256 x 1024 bytes), exceto se for o último fragmento que conclui o carregamento. Normalmente, os tamanhos dos blocos maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória. Recomendamos que use, pelo menos, 8 MiB para o tamanho do fragmento.

  2. Use cURL para chamar a API JSON com um PUT pedido de objeto:

    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"

    Onde:

    • CHUNK_LOCATION é o caminho local para o fragmento que está a carregar atualmente.
    • CHUNK_SIZE é o número de bytes que está a carregar no pedido atual. Por exemplo, 8388608.
    • CHUNK_FIRST_BYTE é o byte inicial no objeto geral que o fragmento que está a carregar contém.
    • CHUNK_LAST_BYTE é o byte final no objeto geral que o fragmento que está a carregar contém.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que está a carregar. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

    Um exemplo de Content-Range é Content-Range: bytes 0-8388607/20000000. Consulte Content-Range para mais informações acerca deste cabeçalho.

    Se o pedido for bem-sucedido, o servidor responde com 308 Resume Incomplete. A resposta contém um cabeçalho Range.

  3. Repita os passos acima para cada parte restante dos dados que quer carregar, usando o valor superior contido no cabeçalho Range de cada resposta para determinar onde começar cada parte sucessiva. Não deve presumir que o servidor recebeu todos os bytes enviados num determinado pedido.

    Opcionalmente, no pedido final do carregamento retomável, pode incluir cabeçalhos com o prefixo X-Goog-Meta- para adicionar metadados personalizados para o objeto.

API XML

  1. Crie um bloco de dados a partir dos dados gerais que quer carregar.

    O tamanho do fragmento deve ser um múltiplo de 256 KiB (256 x 1024 bytes), exceto se for o último fragmento que conclui o carregamento. Normalmente, os tamanhos dos blocos maiores tornam os carregamentos mais rápidos, mas tenha em atenção que existe uma compensação entre a velocidade e a utilização de memória. Recomendamos que use, pelo menos, 8 MiB para o tamanho do fragmento.

  2. Use cURL para chamar a API XML com um PUT pedido de objeto:

    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"

    Onde:

    • CHUNK_LOCATION é o caminho local para o fragmento que está a carregar atualmente.
    • CHUNK_SIZE é o número de bytes que está a carregar no pedido atual. Por exemplo, 8388608.
    • CHUNK_FIRST_BYTE é o byte inicial no objeto geral que o fragmento que está a carregar contém.
    • CHUNK_LAST_BYTE é o byte final no objeto geral que o fragmento que está a carregar contém.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que está a carregar. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

    Um exemplo de Content-Range é Content-Range: bytes 0-8388607/20000000. Consulte Content-Range para mais informações acerca deste cabeçalho.

    Se o pedido for bem-sucedido, o servidor responde com 308 Resume Incomplete. A resposta contém um cabeçalho Range.

  3. Repita os passos acima para cada parte restante dos dados que quer carregar, usando o valor superior contido no cabeçalho Range de cada resposta para determinar onde começar cada parte sucessiva. Não deve presumir que o servidor recebeu todos os bytes enviados num determinado pedido.

Assim que o carregamento estiver totalmente concluído, recebe uma resposta 200 OK ou 201 Created, juntamente com todos os metadados associados ao recurso.

Se algum dos carregamentos de blocos for interrompido ou se receber uma resposta 5xx , deve reenviar o bloco interrompido na íntegra ou retomar o carregamento interrompido a partir do ponto em que parou.

Verifique o estado de um carregamento retomável

Se o carregamento retomável for interrompido ou não tiver a certeza de que o carregamento foi concluído, pode verificar o estado do carregamento:

API JSON

  1. Use cURL para chamar a API JSON com um PUT pedido de objeto:

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

    Onde:

    • OBJECT_SIZE é o número total de bytes no seu objeto. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

API XML

  1. Use cURL para chamar a API XML com um PUT pedido de objeto:

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

    Onde:

    • OBJECT_SIZE é o número total de bytes no seu objeto. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

Uma resposta 200 OK ou 201 Created indica que o carregamento foi concluído e não é necessária nenhuma ação adicional.

Uma resposta 308 Resume Incomplete indica que tem de continuar a carregar os dados.

  • Se o armazenamento na nuvem ainda não tiver persistido nenhum byte, a resposta 308 não tem um cabeçalho Range. Neste caso, deve iniciar o carregamento desde o início.
  • Caso contrário, a resposta 308 tem um cabeçalho Range, que especifica os bytes que o Cloud Storage persistiu até agora. Use este valor quando retomar um carregamento interrompido.

Retome um carregamento interrompido

Se um pedido de carregamento for terminado antes de receber uma resposta ou se receber uma resposta 503 ou 500, tem de retomar o carregamento interrompido a partir do ponto em que ficou. Para retomar um carregamento interrompido:

API JSON

  1. Verifique o estado do carregamento retomável.

  2. Guarde o valor superior do cabeçalho Range contido na resposta à verificação do estado. Se a resposta não tiver um cabeçalho Range, o Cloud Storage ainda não persistiu nenhum byte e deve fazer o carregamento desde o início.

  3. Certifique-se de que os dados do objeto que está prestes a carregar começam no byte a seguir ao valor superior no cabeçalho Range.

  4. Se o pedido interrompido continha cabeçalhos com o prefixo X-Goog-Meta-, inclua esses cabeçalhos no pedido para retomar o carregamento.

  5. Use cURL para chamar a API JSON com um PUT pedido de objeto que é iniciado no byte seguinte ao 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"

    Onde:

    • PARTIAL_OBJECT_LOCATION é o caminho local para a parte restante dos dados que quer carregar.
    • UPLOAD_SIZE_REMAINING é o número de bytes que está a carregar no pedido atual. Por exemplo, carregar o resto de um objeto com um tamanho total de 20 000 000 que foi interrompido após o carregamento dos bytes 0 a 42 teria um UPLOAD_SIZE_REMAINING de 19999957.
    • NEXT_BYTE é o número inteiro seguinte ao valor que guardou no passo 2. Por exemplo, se 42 for o valor superior no passo 2, o valor de NEXT_BYTE é 43.
    • LAST_BYTE é o byte final contido neste pedido PUT. Por exemplo, para concluir o carregamento de um objeto cujo tamanho total é 20000000, o valor de LAST_BYTE é 19999999.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que está a carregar. Por exemplo, 20000000. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

API XML

  1. Verifique o estado do carregamento retomável.

  2. Guarde o valor superior do cabeçalho Range contido na resposta à verificação do estado. Se a resposta não tiver um cabeçalho Range , o Cloud Storage ainda não persistiu nenhum byte e deve carregar desde o início.

  3. Certifique-se de que os dados do objeto que está prestes a carregar começam no byte a seguir ao valor superior no cabeçalho Range.

  4. Use cURL para chamar a API XML com um pedido de objeto PUT que é processado no byte a seguir ao 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"

    Onde:

    • PARTIAL_OBJECT_LOCATION é o caminho local para a parte restante dos dados que quer carregar.
    • UPLOAD_SIZE_REMAINING é o número de bytes que está a carregar no pedido atual. Por exemplo, carregar o resto de um objeto com um tamanho total de 20 000 000 que foi interrompido após o carregamento dos bytes 0 a 42 teria um UPLOAD_SIZE_REMAINING de 19999957.
    • NEXT_BYTE é o número inteiro seguinte ao valor que guardou no passo 2. Por exemplo, se 42 for o valor superior no passo 2, o valor de NEXT_BYTE é 43.
    • LAST_BYTE é o byte final contido neste pedido PUT. Por exemplo, para concluir o carregamento de um objeto cujo tamanho total é 20000000, o valor de LAST_BYTE é 19999999.
    • TOTAL_OBJECT_SIZE é o tamanho total do objeto que está a carregar. Por exemplo, 20000000. Se não souber o tamanho total do objeto, use * para este valor.
    • SESSION_URI é o valor devolvido no cabeçalho Location quando iniciou o carregamento retomável.

Pode retomar os carregamentos as vezes que forem necessárias enquanto o URI da sessão estiver ativo. O URI da sessão expira após uma semana. Quando os dados são carregados com êxito, o Cloud Storage responde com um código de estado 200 OK ou 201 created.

Cancele um carregamento

Para cancelar um carregamento retomável incompleto e impedir qualquer ação adicional no mesmo:

API JSON

  1. Use cURL para chamar a API JSON com um DELETE pedido:

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

    Onde:

Se for bem-sucedido, a resposta contém um código de estado 499. As tentativas futuras de consultar ou retomar o carregamento resultam numa resposta 4xx.

API XML

  1. Use cURL para chamar a API XML com um DELETE pedido:

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

    Onde:

Se for bem-sucedido, a resposta contém um código de estado 204, e as tentativas futuras de consultar ou retomar o carregamento também resultam numa resposta 204.

Processamento de falhas

Em circunstâncias raras, um pedido para retomar um carregamento interrompido pode falhar com um erro "4xx" não repetível porque as autorizações no contentor foram alteradas ou porque a verificação de integridade no objeto carregado final detetou uma incompatibilidade. Se isto ocorrer, tente novamente o carregamento iniciando uma nova sessão de carregamento retomável.

O que se segue?