Este tópico descreve as melhores práticas para fazer upload de um arquivo no Drive and Photo Service (PDS). Consulte este conteúdo para enviar arquivos ao PDS.
Termos
pasta: arquivo do tipo diretório. Pastas não contêm dados físicos. Para criar uma pasta, chame a operação CreateFile do PDS.
arquivo: arquivo que não é do tipo diretório. Arquivos contêm dados físicos. Para criar um arquivo, envie um arquivo local ao PDS. Este tópico explica como realizar esse envio.
Upload de arquivo
Processo
O upload de um arquivo no PDS envolve três etapas:
Chame a operação CreateFile para criar e inicializar o arquivo. O PDS retorna os metadados do arquivo e uma URL para upload via HTTP.
Envie o arquivo usando a URL retornada na etapa anterior.
Chame a operação CompleteFile para concluir o processo de upload.
Procedimento
O exemplo a seguir demonstra como enviar um arquivo local ao PDS.
1. Criar um arquivo
Chame a operação Create file para criar e inicializar o arquivo.
Configurações dos parâmetros principais:
drive_id = "testDriveId": ID do drive de destino do arquivo.
parent_file_id = "root": diretório de destino do upload. O valor root indica que o arquivo será enviado ao diretório raiz.
name = "testName.jpg": nome do arquivo a ser enviado.
type = "file": tipo do objeto a ser criado. Valores válidos: file e folder.
size = 13381200: tamanho real do arquivo local, em bytes.
part_info_list = [{"part_number":1},{"part_number":2},{"part_number":3}]: partes do arquivo a serem enviadas. Defina a quantidade de partes com base no tamanho total do arquivo e no tamanho de cada parte configurado no cliente. Especifique várias partes para aumentar a taxa de sucesso e permitir o upload resumível. Neste exemplo, o arquivo tem cerca de 13 MB e cada parte tem 5 MB, resultando em três partes.
Exemplo de corpo da requisição:
{
"drive_id":"testDriveId",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13381200,
"type":"file"
}Exemplo de corpo da resposta:
{
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1,
"upload_url":"https://xxxx1"
},
{
"part_number":2,
"upload_url":"https://xxxx2"
},
{
"part_number":3,
"upload_url":"https://xxxx3"
}
],
"upload_id":"testUploadId",
"rapid_upload":false,
"type":"file",
"file_id":"testFileId",
"revision_id":"testRevisionId",
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"file_name":"testName.jpg"
}Parâmetros principais da resposta:
file_id: ID exclusivo que o PDS atribui ao arquivo. Cada arquivo possui um ID único dentro de um drive.
upload_id: ID que o PDS atribui ao processo de upload. Utilize este identificador nas etapas seguintes, como na conclusão do upload.
part_info_list: URLs de upload que o PDS atribui a cada parte. A quantidade de URLs corresponde exatamente ao número de partes solicitadas, com uma URL por parte.
2. Enviar o arquivo
Percorra a lista e envie as partes do arquivo usando as URLs retornadas na Etapa 1. Este exemplo utiliza o método HTTP PUT.
Código Java de exemplo:
// Traverse all the parts of the file to be uploaded.
for (PartInfo uploadPartInfo : partInfoList) {
// Calculate the serial numbers of the parts in the local file.
int number = uploadPartInfo.getPartNumber();
long pos = (number - 1) * partSize;
long size = Math.min(length - pos, partSize);
byte[] partContent = new byte[(int) size];
// Read the data of the parts from the local file to the memory.
RandomAccessFile randomAccessFile = new RandomAccessFile(localFile, "r");
randomAccessFile.seek(pos);
randomAccessFile.readFully(partContent, 0, (int) size);
randomAccessFile.close();
// Upload the parts.
RequestBody body = RequestBody.create(null, partContent);
Request request = new Request.Builder()
.url(uploadPartInfo.getUploadUrl())
.header("Content-Length", String.valueOf(size))
.put(body)
.build();
OkHttpClient okHttpClient = new OkHttpClient.Builder().build();
Response response = okHttpClient.newCall(request).execute();
// Determine whether the parts are uploaded.
if (!response.isSuccessful()) {
System.out.println(response.body().string() + "\n");
Assert.fail("upload part failed, partNumber:" + number);
return "";
}
System.out.println("upload part success, partNumber:" + number);
}3. Concluir o processo de upload
Após enviar todas as partes, chame a operação CompleteFile para finalizar o upload do arquivo.
Configurações dos parâmetros principais:
drive_id = "testDriveId": ID do drive de destino do arquivo.
file_id = "testFileId": ID do arquivo. Use o valor do parâmetro file_id retornado na Etapa 1.
upload_id = "testUploadId": ID do processo de upload. Use o valor do parâmetro upload_id retornado na Etapa 1.
Exemplo de corpo da requisição:
{
"drive_id":"testDriveId",
"file_id":"testFileId",
"upload_id":"testUploadId"
}Um código de status HTTP 200 confirma que o upload foi concluído com sucesso.
Exemplo de corpo da resposta:
{
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"file_id":"testFileId",
"parent_file_id":"root",
"type":"file",
"file_extension":"jpg",
"name":"testName.jpg",
"size":13381200,
"status":"available",
"content_hash":"xxxxx",
"created_at":"2023-01-16T11:55:12.166Z",
"updated_at":"2023-01-16T11:55:13.368Z"
}Upload resumível
Cenários
Durante o upload, você pode pausar temporariamente a transferência. Por exemplo, se desejar enviar arquivos apenas via Wi-Fi, interrompa o processo quando a rede estiver indisponível e retome-o assim que a conexão for restabelecida.
Implementação
O upload de arquivos grandes ocorre mediante a divisão do conteúdo em múltiplas partes.
Considere um arquivo de 50 MB com tamanho de parte definido em 5 MB pelo cliente: o sistema dividirá o arquivo em 10 partes.
Suponha que o cliente já tenha enviado as seis primeiras partes ao PDS e pare durante o envio da sétima. Nesse caso, o cliente deve armazenar informações intermediárias do processo, como dados do arquivo e progresso atual. Um banco de dados local é uma opção viável para persistir esses dados.
Ao retomar o upload, o sistema descarta quaisquer dados parciais da sétima parte enviados anteriormente. O cliente reinicia o envio a partir da sétima parte incompleta. As URLs das partes restantes podem expirar durante a pausa, gerando o código de erro 403. Se isso ocorrer, chame a operação ListUploadedParts para obter novas URLs de upload para as partes pendentes.
Se a suspensão do upload ultrapassar 10 dias, a retomada não será mais possível. Nessa situação, chame a operação CreateFile para iniciar um novo processo e reenvie o arquivo local desde o início.
Transferência instantânea de arquivo
Visão geral
O PDS oferece deduplicação de arquivos no nível do domínio. Ao tentar enviar um arquivo que já existe no domínio do PDS, não é necessário realizar o upload completo. Basta calcular o hash SHA-1 (Secure Hash Algorithm 1) do arquivo para que o sistema o registre em segundos.
Cenários
Imagine que o Usuário A enviou um filme para um drive no PDS. O Usuário B pode usar a transferência instantânea para enviar o mesmo filme para outro drive no mesmo domínio, sem precisar fazer o upload completo novamente. Isso agiliza o processo e economiza tráfego de rede.
O arquivo registrado pelo Usuário B via transferência instantânea é totalmente independente do arquivo do Usuário A, garantindo a segurança e o isolamento dos dados.
Usar a transferência instantânea de arquivo
Antes de utilizar a transferência instantânea, calcule o hash SHA-1 do arquivo. Ao chamar a operação Create file, defina o parâmetro content_hash com o valor SHA-1 calculado.
Configurações dos parâmetros principais:
content_hash_name = "sha1": algoritmo usado para validação instantânea. Apenas SHA-1 é suportado.
content_hash = "xxxx": valor do hash SHA-1 calculado para o arquivo.
size = 13381200: tamanho total do arquivo.
Os demais parâmetros seguem a mesma configuração descrita na seção "Upload de arquivo" deste tópico.
Exemplo de corpo da requisição:
{
"drive_id":"testDriveId",
"name":"testName.jpg",
"parent_file_id":"root",
"content_hash":"xxxxx",
"content_hash_name":"sha1",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13381200,
"type":"file"
}Código Java de exemplo para cálculo do hash SHA-1:
public static String getFileHash(File file) throws IOException {
return Hex.encodeHexString((getFileHashBytes(file)));
}
public static byte[] getFileHashBytes(File file) throws IOException {
byte[] sha1;
try {
MessageDigest digest = MessageDigest.getInstance("SHA1");
byte[] buffer = new byte[10 * 1024];
FileInputStream is = new FileInputStream(file);
int len;
while ((len = is.read(buffer)) != -1) {
digest.update(buffer, 0, len);
}
is.close();
sha1 = digest.digest();
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException("SHA1 algorithm not found.");
}
return sha1;
}Exemplo de corpo da resposta:
{
"domain_id":"testDomainId",
"drive_id":"testDriveId",
"parent_file_id":"root",
"upload_id":"testUploadId",
"rapid_upload":true,
"type":"file",
"file_id":"testFileId",
"revision_id":"testRevisionId",
"file_name":"testName.jpg"
}Parâmetros principais da resposta:
rapid_upload: indica se a transferência instantânea foi aplicada.
O valor true significa que a transferência instantânea ocorreu com sucesso. O PDS identificou um arquivo existente no mesmo domínio com dados idênticos, baseado no hash SHA-1 fornecido. Assim, a resposta não inclui URLs de upload, e o cliente não precisa executar as etapas subsequentes de envio e conclusão.
O valor false indica que a transferência instantânea não foi possível. A resposta conterá as URLs de upload das partes, e o cliente deverá prosseguir com o fluxo normal de upload e finalização.
Usar o recurso de pré-hash para melhorar a precisão
Calcular o hash SHA-1 completo antes do upload pode ser custoso, especialmente para clientes com capacidade computacional limitada ou arquivos muito grandes. Além disso, se não houver correspondência no domínio PDS, todo o esforço de cálculo é desperdiçado, aumentando o tempo total de upload.
Para otimizar esse processo, o PDS oferece o recurso de pré-hash. Em vez de processar o arquivo inteiro, calcule o SHA-1 apenas dos primeiros 1 KB de dados. Ao chamar a operação CreateFile, defina o parâmetro pre_hash com esse valor parcial. O servidor verificará rapidamente se há dados correspondentes no domínio.
Configurações dos parâmetros principais:
pre_hash = "xxxxx": hash SHA-1 dos primeiros 1 KB do arquivo.
Os demais parâmetros seguem a mesma configuração descrita na seção "Upload de arquivo" deste tópico.
Exemplo de corpo da requisição:
{
"drive_id":"10530",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"pre_hash":"xxxx",
"size":13381200,
"type":"file"
}Análise da resposta:
Status HTTP 409: existe uma correspondência para os primeiros 1 KB no domínio, sugerindo que o arquivo pode já existir. Nesse caso, o cliente deve calcular o hash SHA-1 completo, chamar a operação Create file novamente e tentar a transferência instantânea. Lembre-se de que o pré-hash não garante correspondência exata, pois diferentes arquivos podem compartilhar os mesmos 1 KB iniciais.
Status HTTP 201: não há correspondência para os primeiros 1 KB no domínio, confirmando que o arquivo é inédito. As URLs de upload das partes são retornadas sincronamente, permitindo que o cliente prossiga com o fluxo normal de envio.
O cálculo do pré-hash ocorre de forma assíncrona em segundo plano e pode levar alguns minutos para ser refletido. Se você tentar enviar um arquivo duplicado logo após o upload original, a transferência instantânea pode não estar disponível imediatamente.
Fluxograma
Upload de arquivo em modo de sobrescrita
O PDS permite substituir um arquivo existente durante o upload. Para isso, defina o parâmetro file_id com o ID do arquivo alvo ao chamar a operação Create file. Em seguida, siga o fluxo padrão de upload.
Exemplo de corpo da requisição:
{
"drive_id":"testDriveId",
"file_id":"testFileId",
"name":"testName.jpg",
"parent_file_id":"root",
"part_info_list":[
{
"part_number":1
},
{
"part_number":2
},
{
"part_number":3
}
],
"size":13373603,
"type":"file"
}Pontos importantes:
O ID do arquivo permanece inalterado após a sobrescrita. Continue usando o mesmo identificador para operações futuras.
Em cenários de concorrência onde múltiplos clientes sobrescrevem o mesmo arquivo, prevalece a versão enviada pelo último cliente a chamar a operação CompleteFile.
Para preservar versões anteriores à sobrescrita, ative o recurso de versionamento histórico. Para mais detalhes, consulte ListRevision.
FAQ
O que fazer se as URLs de upload das partes expirarem?
As URLs de upload têm validade de uma hora. Tentativas de envio após esse período retornarão o erro 403. Isso é comum em uploads resumíveis pausados por mais de uma hora. Para resolver, chame a operação ListUploadedParts para obter novas URLs das partes restantes antes de retomar o envio.
Quais limites devo observar ao fazer upload de arquivos?
Cada parte do arquivo pode ter no máximo 5 GB.
Como o servidor calcula o hash SHA-1 em streaming, as partes devem ser enviadas sequencialmente. Uploads concorrentes de partes do mesmo arquivo não são permitidos.
Não é possível sobrescrever partes individuais de um arquivo.
Qual é o prazo de validade de um processo de upload?
Todo processo de upload deve ser concluído em até 10 dias. Caso contrário, o sistema descartará o processo incompleto. Será necessário chamar a operação CreateFile para gerar um novo registro no PDS e reiniciar o upload do arquivo local.