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. Uma pasta 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
Para enviar um arquivo ao PDS, execute as três etapas a seguir:
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 mostra como enviar um arquivo local ao PDS.
1. Criar um arquivo
Chame a operação CreateFile para criar e inicializar o arquivo.
Configurações dos parâmetros principais:
drive_id = "testDriveId": ID do drive de destino do upload.
parent_file_id = "root": diretório de destino do upload. O valor root indica envio para o diretório raiz.
name = "testName.jpg": nome do arquivo a ser enviado.
type = "file": tipo do arquivo a ser enviado. Valores válidos: file e folder.
size = 13381200: tamanho real do arquivo local. Unidade: bytes.
part_info_list = [{"part_number":1},{"part_number":2},{"part_number":3}]: partes do arquivo a serem enviadas. Especifique o número de partes com base no tamanho do arquivo e no tamanho de cada parte definido pelo cliente. É possível especificar várias partes para aumentar a taxa de sucesso do upload e permitir uploads retomáveis. Neste exemplo, o arquivo tem cerca de 13 MB e o tamanho de cada parte definido pelo cliente é de 5 MB. Portanto, três partes são enviadas.
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 do arquivo. Esse ID é utilizado nas etapas subsequentes, como na conclusão do upload.
part_info_list: URLs de upload que o PDS atribui a cada parte. A quantidade de URLs corresponde ao número de partes a serem enviadas. O PDS atribui uma URL de upload específica para cada parte.
2. Enviar o arquivo
Percorra e envie as partes do arquivo usando as URLs retornadas na Etapa 1. Neste exemplo, utiliza-se o método HTTP PUT.
Exemplo de código Java:
// 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 do arquivo, chame a operação CompleteFile para finalizar o upload.
Configurações dos parâmetros principais:
drive_id = "testDriveId": ID do drive para o qual o arquivo foi enviado.
file_id = "testFileId": ID do arquivo. Defina este parâmetro com o valor de file_id retornado na Etapa 1.
upload_id = "testUploadId": ID do processo de upload. Defina este parâmetro com o valor de upload_id retornado na Etapa 1.
Exemplo de corpo da requisição:
{
"drive_id":"testDriveId",
"file_id":"testFileId",
"upload_id":"testUploadId"
}Se o código de status HTTP 200 for retornado, o upload do arquivo 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 retomável
Cenários
Durante o upload de um arquivo, você pode interromper temporariamente a transferência. Por exemplo, se desejar fazer upload apenas via Wi-Fi, pause o processo quando a rede estiver indisponível e retome assim que a conexão for restabelecida.
Implementação
Ao fazer upload de um arquivo, divida-o em múltiplas partes.
Por exemplo, para enviar um arquivo de 50 MB com tamanho de parte definido em 5 MB, o cliente divide o arquivo em 10 partes.
Suponha que o cliente já tenha enviado as seis primeiras partes ao PDS e o upload seja interrompido durante o envio da sétima parte. Nesse caso, o cliente precisa armazenar informações intermediárias do processo, como dados do arquivo e progresso do upload. Essas informações podem ser salvas em um banco de dados.
Ao retomar o upload, os dados parciais da sétima parte enviados anteriormente ao PDS serão descartados. O cliente reinicia o envio a partir da sétima parte incompleta. Ao retomar, as URLs de upload das partes restantes podem ter expirado, resultando no código de erro 403. Nessa situação, chame a operação ListUploadedParts para obter novas URLs de upload para as partes restantes.
Se o processo de upload ficar suspenso por mais de 10 dias, não será possível retomá-lo. Nesse caso, chame a operação CreateFile para criar um novo arquivo e refaça o upload do arquivo local.
Transferência instantânea de arquivos
Visão geral
O PDS oferece capacidade de deduplicação de arquivos no nível de domínio. Ao tentar enviar um arquivo que já existe em um domínio do PDS, não é necessário realizar o processo completo de upload. Basta calcular o valor de hash SHA-1 (Secure Hash Algorithm 1) do arquivo para que ele seja transferido ao PDS em segundos.
Cenários
Se o Usuário A já enviou um filme para um drive no PDS, o Usuário B pode enviar o mesmo filme para outro drive no mesmo domínio utilizando a transferência instantânea. O Usuário B não precisa executar o fluxo completo de upload, o que aumenta a eficiência e economiza tráfego de rede.
O arquivo enviado pelo Usuário B via transferência instantânea é independente do arquivo existente no drive do Usuário A, garantindo a segurança dos dados.
Usar a transferência instantânea
Antes de utilizar a transferência instantânea, calcule o valor de hash SHA-1 do arquivo. Ao chamar a operação CreateFile, defina o parâmetro content_hash com o valor SHA-1 calculado.
Configurações dos parâmetros principais:
content_hash_name = "sha1": algoritmo de cálculo para transferência instantânea. Apenas SHA-1 é suportado.
content_hash = "xxxx": valor de hash SHA-1 calculado para o arquivo.
size = 13381200: tamanho do arquivo.
As demais configurações de parâmetros seguem o descrito 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"
}Exemplo de código Java para calcular o hash SHA-1 do arquivo:
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 o arquivo foi enviado usando a transferência instantânea.
O valor true significa que o upload utilizou a transferência instantânea. Com base no hash SHA-1 fornecido, o PDS identificou um arquivo existente com os mesmos dados no mesmo domínio. Assim, as URLs de upload das partes não são retornadas, e o cliente não precisa executar as etapas subsequentes de upload e conclusão.
O valor false indica que a transferência instantânea não ocorreu. Nesse cenário, o corpo da resposta contém as URLs de upload das partes. O cliente deve prosseguir com as etapas normais de upload e conclusão do processo.
Usar pré-hash para melhorar a precisão
Para usar a transferência instantânea, é necessário calcular o hash SHA-1 do arquivo. Contudo, clientes geralmente têm capacidade computacional limitada, tornando o cálculo do SHA-1 completo demorado para arquivos grandes. Além disso, se nenhum dado correspondente for encontrado no domínio do PDS, a transferência instantânea falha, desperdiçando recursos do cliente e aumentando o tempo total de upload.
Para resolver isso e aumentar a precisão, o PDS oferece o recurso de pré-hash. Calcule apenas o SHA-1 dos primeiros 1 KB de dados do arquivo. Ao chamar a operação CreateFile, defina o parâmetro pre_hash com esse valor. O servidor verificará se existem dados correspondentes no domínio do PDS.
Configurações dos parâmetros principais:
pre_hash = "xxxxx": valor de hash SHA-1 dos primeiros 1 KB de dados do arquivo.
As demais configurações de parâmetros seguem o descrito 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:
Se o código de status HTTP 409 for retornado, existem dados no mesmo domínio que correspondem ao SHA-1 dos primeiros 1 KB. Isso sugere que pode haver um arquivo idêntico no domínio. O cliente deve então calcular o SHA-1 completo, chamar a operação CreateFile novamente e tentar a transferência instantânea. Note que o pré-hash não garante correspondência exata, pois os primeiros 1 KB de arquivos diferentes podem coincidir.
Se o código de status HTTP 201 for retornado, não há correspondência para os primeiros 1 KB no domínio, indicando que não existe arquivo idêntico. As URLs de upload das partes são retornadas sincronamente, permitindo que o cliente prossiga com o fluxo normal de upload.
O valor de pré-hash é calculado de forma assíncrona em segundo plano e pode levar alguns minutos para ser atualizado. Se você tentar enviar um arquivo duplicado logo após o upload original, a transferência instantânea pode não funcionar imediatamente.
Fluxograma
Upload de arquivo em modo de sobrescrita
O PDS permite fazer upload de um arquivo sobrescrevendo um existente. Para isso, defina o parâmetro file_id com o ID do arquivo existente ao chamar a operação CreateFile. Em seguida, siga o processo 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:
Após a sobrescrita, o ID do arquivo permanece inalterado. Você pode continuar usando o mesmo ID para operar o arquivo.
Quando múltiplos clientes sobrescrevem o mesmo arquivo simultaneamente, a versão do cliente que chamar a operação CompleteFile por último será considerada a versão mais recente.
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 das partes têm validade de uma hora. Se você tentar enviar partes após esse período chamando a operação CreateFile, receberá o código de erro 403. Por exemplo, ao retomar um upload pausado após uma hora, o erro ocorrerá. Nessa situação, chame a operação ListUploadedParts para obter novas URLs antes de continuar o upload retomável.
Quais limites devo observar ao fazer upload de arquivos?
Cada parte do arquivo pode ter no máximo 5 GB.
O servidor calcula o hash SHA-1 em modo streaming. Por isso, as partes de um único arquivo devem ser enviadas sequencialmente, sem uploads simultâneos.
Não é possível sobrescrever partes individuais de um arquivo.
Qual é o prazo de validade de um processo de upload?
O processo de upload deve ser concluído em até 10 dias. Caso contrário, ele será descartado. Se isso acontecer, chame a operação CreateFile para criar um novo arquivo no PDS e reinicie o upload do arquivo local.