Uploads recuperáveis

Nesta página, você conhecerá os uploads recuperáveis do Cloud Storage na API JSON e API XML. Para saber como executar um upload recuperável, consulte Como fazer uploads recuperáveis. Como não é necessário reiniciar os uploads de arquivos grandes desde o início, os uploads recuperáveis reduzem o uso da largura de banda quando há uma falha de rede. Um upload retomável é considerado uma operação de classe A.

Introdução

O Cloud Storage fornece um recurso de transferência de dados recuperável que permite retomar as operações de upload após uma falha de comunicação ter interrompido o fluxo de dados. Os uploads recuperáveis serão úteis se você estiver transferindo arquivos grandes, uma vez que probabilidade de uma interrupção de rede ou alguma outra falha de transmissão é alta. Através do recurso de upload recuperável, é possível reduzir o uso da largura de banda, uma vez que não é necessário reiniciar os uploads de grandes arquivos desde o início. Para obter dicas sobre como fazer o upload para o Cloud Storage, consulte as práticas recomendadas .

As APIs JSON e XML do Cloud Storage fornecem dois métodos HTTP padrão para fazer o upload de dados: POST Object e PUT Object. Para implementar um upload recuperável, use os dois métodos em conjunto com diversos cabeçalhos e parâmetros de string de consulta.

Caso esteja enviando arquivos pequenos por meio de uma conexão de rede confiável, use um upload simples.

Saiba mais sobre URIs de solicitação

Importante: ao iniciar uma sessão de upload recuperável, é retornado um URI de sessão usado para criar e retomar uploads. Esse URI da sessão atua como um token de autenticação, por isso as solicitações PUT para upload não precisam ser assinadas. Seja criterioso ao compartilhar o URI da sessão e transmita-o apenas por HTTPS, uma vez que pode ser usado por qualquer pessoa para fazer o upload de dados para o bucket de destino sem ser necessário nenhuma outra autenticação.

Ao fazer o upload de objetos com a API JSON, é utilizado um URI especial que difere do URI usado na maioria das solicitações da API JSON, incluindo solicitações de upload de metadados de objeto:

• Para fazer uploads de objetos, use o URI /upload. O formato do endpoint /upload é o URI de recurso padrão com um prefixo /upload. Use esse URI ao transferir os dados de objeto.

  Por exemplo, no caso de um bucket chamado myBucket:

  POST /upload/storage/v1/b/myBucket/o

• Para outras solicitações, use o URI de recurso padrão. Isso inclui adicionar ou atualizar valores de metadados de um objeto existente.

  Por exemplo, para um patch de metadados de um objeto chamado myObject em um bucket chamado myBucket:

  PATCH /storage/v1/b/myBucket/o/myObject

Tipo de conteúdo em XML

Inclua um cabeçalho de solicitação Content-Type caso queira especificar um tipo de conteúdo para o arquivo que está enviando. Se você não especificar um tipo de conteúdo, o sistema do Cloud Storage definirá o tipo como application/octet-stream ao veicular o objeto que você está enviando.

O cabeçalho x-goog-resumable é um cabeçalho de extensão (personalizado) do Cloud Storage. O cabeçalho notifica o sistema do Cloud Storage que você quer iniciar um upload recuperável. É possível usar o cabeçalho somente com uma solicitação POST Object e apenas para uploads recuperáveis.

Além disso, use o nome de host padrão do Cloud Storage na solicitação e autentique a solicitação POST Object da mesma forma que você faria com qualquer solicitação autenticada. Para mais informações, consulte Endpoints de solicitação e Autenticação.

Uploads recuperáveis de tamanho desconhecido

O mecanismo de upload recuperável suporta transferências cujo tamanho do arquivo não é conhecido com antecedência. Isso pode ser útil para casos como a compactação de um objeto durante o upload, uma vez que é difícil prever o tamanho exato do arquivo compactado no início de uma transferência. O mecanismo é útil caso queira fazer o streaming de uma transferência que pode ser retomada após ser interrompida ou se a codificação de transferência fragmentada não funcionar em seu aplicativo.

Práticas recomendadas

• Um URI de sessão expira após uma semana. Recomendamos iniciar um upload recuperável assim que obtiver o URI da sessão e recuperar um upload interrompido logo após a interrupção.

• Caso use um URI de sessão expirada em uma solicitação, receberá um código de status 400 Bad Request. Nesse caso, será necessário iniciar um novo upload recuperável, obter um novo URI de sessão e iniciar o upload desde o início usando o novo URI de sessão.

• Após iniciar uma sessão de upload recuperável, é retornado um URI de sessão para criação e recuperação de uploads. Esse URI da sessão atua como um token de autenticação, por isso as solicitações PUT para upload não precisam ser assinadas. Seja criterioso ao compartilhar o URI da sessão e transmita-o apenas por HTTPS, uma vez que pode ser usado por qualquer pessoa para fazer o upload de dados para o bucket de destino sem ser necessário nenhuma outra autenticação.

• Além disso, tente novamente quaisquer solicitações que retornem estes códigos de status:

  • 408 Request Timeout
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

• Ao executar um upload recuperável, trate os erros 404 Not Found iniciando o upload completo desde o início.

Ao realizar solicitações de repetição, use a espera exponencial truncada.

• Além disso, recomendamos a verificação da integridade do objeto final enviado para se certificar de que ele corresponda ao arquivo de origem. Isso pode ser feito calculando o resumo MD5 do arquivo de origem e adicionando-o ao cabeçalho da solicitação Content-MD5. A verificação da integridade do arquivo enviado é especialmente importante se você estiver fazendo upload de um arquivo grande durante um longo período, devido à maior probabilidade de o arquivo de origem ser modificado durante a operação de upload.

• Os uploads recuperáveis são fixados na região em que são iniciados. Por exemplo, se você criar um URL de upload recuperável nos EUA e fornecê-lo a um cliente na Ásia, o upload ainda passará pelos EUA. A realização de um upload recuperável em uma região onde ele não foi iniciado pode resultar em lentidão.

• Se você usa instâncias do Compute Engine com processos que enviam POST para o Cloud Storage para iniciar um upload recuperável, use instâncias do Compute Engine nos mesmos locais que seus buckets do Cloud Storage. Em seguida, é possível usar um serviço de IP geográfico para escolher a região do Compute Engine para onde você encaminha solicitações de clientes, o que ajudará a manter o tráfego localizado em uma região geográfica.

Otimização opcional

Se você receber uma resposta 308 Resume Incomplete sem o cabeçalho Range, alguns bytes podem ter sido recebidos pelo Cloud Storage, mas não foram mantidos quando o Cloud Storage recebeu a consulta. Nesse caso, retransmitir desde o início do arquivo é um pouco desnecessário. Para reduzir a probabilidade desse caso, aguarde alguns segundos após a primeira resposta 308 e, em seguida, consulte novamente. Nesse momento, talvez você receba um cabeçalho Range, dispensando a retransmissão desde o início do arquivo. Caso não receba um cabeçalho Range nesta segunda tentativa, não espere mais e tente uma terceira vez, uma vez que continuar repetindo a pesquisa pode levar a um upload "interrompido", caso o Cloud Storage realmente não tenha recebido nenhum dado para o upload.