O Object Storage Service (OSS) oferece um recurso de upload multipart para objetos grandes. Esse processo divide o objeto em partes menores, envia cada uma independentemente e, em seguida, chama a API CompleteMultipartUpload para combinar as partes em um único objeto. Isso permite retomar uploads interrompidos.
Observações
Este tópico usa o endpoint público da região China (Hangzhou). Para acessar o OSS a partir de outros serviços da Alibaba Cloud na mesma região, use um endpoint interno. Para obter detalhes sobre regiões e endpoints compatíveis, consulte Regiões e endpoints.
Neste tópico, as credenciais de acesso são obtidas de variáveis de ambiente. Para mais informações, consulte Configurar credenciais de acesso.
Este tópico demonstra como criar uma instância OSSClient com um endpoint do OSS. Para configurações alternativas, como uso de domínio personalizado ou autenticação com credenciais do Security Token Service (STS), consulte Configuração do cliente.
O upload multipart utiliza InitiateMultipartUpload, UploadPart e CompleteMultipartUpload. Você deve ter a permissão
oss:PutObject. Consulte Conceder políticas de acesso personalizadas a um usuário RAM.
Processo de upload multipart
O upload multipart envolve três etapas:
-
Inicialize um upload multipart.
Chame ossClient.initiateMultipartUpload. O OSS retorna um ID de upload globalmente único.
-
Envie as partes.
Chame ossClient.uploadPart para enviar os dados da parte.
NotaO número da parte identifica sua posição dentro do objeto. Enviar dados com o mesmo número de parte sobrescreve a parte existente.
O OSS retorna o hash MD5 dos dados da parte recebida no cabeçalho ETag da resposta.
O OSS calcula o hash MD5 dos dados enviados e o compara com o hash calculado pelo SDK. Se houver incompatibilidade, o código de erro InvalidDigest será retornado.
-
Conclua o upload multipart.
Após enviar todas as partes, chame ossClient.completeMultipartUpload para mesclar as partes em um objeto completo.
Código de exemplo
O exemplo a seguir mostra o processo completo de upload multipart:
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.internal.Mimetypes;
import com.aliyun.oss.model.*;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
public class Demo {
public static void main(String[] args) throws Exception {
// Use the endpoint of the China (Hangzhou) region as an example. Specify the actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// Specify the bucket name, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object, for example, exampledir/exampleobject.txt. The full path cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// The path of the local file to upload.
String filePath = "D:\\localpath\\examplefile.txt";
// Specify the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou.
String region = "cn-hangzhou";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release resources.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// Create an InitiateMultipartUploadRequest object.
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
// Create an ObjectMetadata object and set the Content-Type.
ObjectMetadata metadata = new ObjectMetadata();
if (metadata.getContentType() == null) {
metadata.setContentType(Mimetypes.getInstance().getMimetype(new File(filePath), objectName));
}
System.out.println("Content-Type: " + metadata.getContentType());
// Bind the metadata to the upload request.
request.setObjectMetadata(metadata);
// Initialize the multipart upload.
InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
// Return the upload ID.
String uploadId = upresult.getUploadId();
// partETags is a collection of PartETag objects. A PartETag object consists of the ETag and part number of a part.
List<PartETag> partETags = new ArrayList<PartETag>();
// The size of each part. This is used to calculate the number of parts. Unit: bytes.
// The minimum part size is 100 KB, and the maximum part size is 5 GB. The size of the last part can be smaller than 100 KB.
// Set the part size to 1 MB.
final long partSize = 1 * 1024 * 1024L;
// Calculate the number of parts based on the size of the data to upload. The following code provides an example of how to obtain the size of the data to upload from a local file using File.length().
final File sampleFile = new File(filePath);
long fileLength = sampleFile.length();
int partCount = (int) (fileLength / partSize);
if (fileLength % partSize != 0) {
partCount++;
}
// Traverse the parts and upload them.
for (int i = 0; i < partCount; i++) {
long startPos = i * partSize;
long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
UploadPartRequest uploadPartRequest = new UploadPartRequest();
uploadPartRequest.setBucketName(bucketName);
uploadPartRequest.setKey(objectName);
uploadPartRequest.setUploadId(uploadId);
// Set the stream of the part to upload.
// The following code provides an example of how to create a FileInputStream object from a local file and skip the specified data using the InputStream.skip() method.
InputStream instream = new FileInputStream(sampleFile);
instream.skip(startPos);
uploadPartRequest.setInputStream(instream);
// Set the part size.
uploadPartRequest.setPartSize(curPartSize);
// Set the part number. Each uploaded part has a part number that ranges from 1 to 10,000. If the part number is not in the range, OSS returns the InvalidArgument error code.
uploadPartRequest.setPartNumber(i + 1);
// Parts do not need to be uploaded in sequence. They can even be uploaded from different clients. OSS sorts the parts by part number to create a complete object.
UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
// After each part is uploaded, the OSS response includes a PartETag. The PartETag is saved in partETags.
partETags.add(uploadPartResult.getPartETag());
// Close the stream.
instream.close();
}
// Create a CompleteMultipartUploadRequest object.
// When you complete the multipart upload, you must provide all valid partETags. After OSS receives the submitted partETags, it verifies the validity of each part. After all parts are verified, OSS combines these parts into a complete object.
CompleteMultipartUploadRequest completeMultipartUploadRequest =
new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
// Complete the multipart upload.
CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
System.out.println("Upload successful, ETag: " + completeMultipartUploadResult.getETag());
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught a ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}Cenários comuns
Definir metadados ao inicializar um upload multipart
Definir permissões de acesso ao objeto ao concluir um upload multipart
Processar automaticamente ETags de partes ao concluir um upload multipart
Cancele um evento de upload multipart
Listar partes enviadas
Listar eventos de upload multipart
Realizar upload multipart para fluxos de rede ou fluxos de dados
Referências
Código de exemplo completo: Exemplo no GitHub.
-
Um upload multipart envolve três operações de API:
Inicializar um upload multipart: InitiateMultipartUpload.
Enviar uma parte: UploadPart.
Concluir um upload multipart: CompleteMultipartUpload.
Cancelar um upload multipart: AbortMultipartUpload.
Listar partes enviadas: ListParts.
Listar uploads multipart em andamento: ListMultipartUploads.