O upload multipart divide arquivos grandes em partes menores para transferência simultânea, permitindo uploads retomáveis e melhor desempenho em redes instáveis.
Como funciona
O upload multipart divide um arquivo grande em partes transferidas independentemente. Se uma parte falhar, apenas ela precisará ser reenviada. Um UploadId identifica a tarefa de upload e associa todas as partes. O processo consiste em três etapas:
Inicializar o upload: Chame a operação InitiateMultipartUpload para criar um upload multipart e obter um UploadId exclusivo, usado para identificar as operações subsequentes.
Enviar os dados das partes do arquivo: Envie o arquivo em partes simultaneamente, cada uma com tamanho entre 100 KB e 5 GB. Há suporte para upload retomável.
Concluir o upload combinando as partes: Chame a operação CompleteMultipartUpload para combinar todas as partes, na ordem de seus números, em um objeto completo.
Implementar upload multipart
Devido a uma alteração de política para melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do OSS devem usar um nome de domínio personalizado (CNAME) para executar operações de API de dados em buckets do OSS localizados em regiões da China continental. Os endpoints públicos padrão estão restritos para essas operações. Consulte o anúncio oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via HTTPS, será necessário vincular um certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao OSS Console, pois o console impõe o uso de HTTPS.
Use ferramentas gráficas, ferramentas CLI ou SDKs para implementar o upload multipart.
O console do OSS não oferece suporte a upload multipart.
É possível enviar arquivos compactados criptografados, mas não é possível enviar diretórios.
Usar ferramentas para divisão automática de partes
Para tarefas de desenvolvimento, teste ou O&M, use ferramentas gráficas ou CLI que lidam com a divisão de partes automaticamente.
-
Ferramenta gráfica de gerenciamento: OSS Browser
O ossbrowser 2.0 ativa o upload multipart por padrão e fornece uma interface visual para monitorar o progresso do upload.
-
ossutil
O comando cp do ossutil 2.0 ativa automaticamente o upload multipart para arquivos maiores que 100 MiB. Para controlar manualmente o processo, use os comandos initiate-multipart-upload, upload-part e complete-multipart-upload em conjunto.
ossutil cp example.zip oss://example-bucket
Controle programático com SDKs
Os SDKs encapsulam o upload multipart com tamanhos de parte personalizados, concorrência e tratamento de erros. As seções a seguir mostram exemplos para SDKs comuns. Para outras linguagens, consulte a Referência do SDK.
Antes de executar o código, instale o SDK e configure as credenciais de acesso como variáveis de ambiente. Se você usar um usuário RAM ou uma função RAM, conceda as permissões necessárias. Para mais informações, consulte Permissões de API .
Java SDK V2
import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;
import com.aliyun.sdk.service.oss2.io.BoundedInputStream;
import com.aliyun.sdk.service.oss2.models.*;
import com.aliyun.sdk.service.oss2.transport.BinaryData;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
/**
* Sample OSS multipart upload.
* Implements multipart upload for large files.
*/
public class MultipartUpload {
public static void main(String[] args) {
// Obtain access credentials from environment variables.
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// Set the OSS region and endpoint.
String region = "cn-hangzhou";
String endpoint = "oss-cn-hangzhou.aliyuncs.com";
// Configure bucket and file information.
String bucket = "example-bucket";
String key = "dest.jpg";
String filePath = "dest.jpg";
// Create a credential provider.
CredentialsProvider provider = new StaticCredentialsProvider(accessKeyId, accessKeySecret);
// Initialize the OSS client.
OSSClient client = OSSClient.newBuilder()
.credentialsProvider(provider)
.region(region)
.endpoint(endpoint)
.build();
try {
// Step 1: Initialize the multipart upload.
InitiateMultipartUploadResult initiateResult = client.initiateMultipartUpload(
InitiateMultipartUploadRequest.newBuilder()
.bucket(bucket)
.key(key)
.build());
String uploadId = initiateResult.initiateMultipartUpload().uploadId();
System.out.printf("Initiated multipart upload successfully. Status code: %d, Request ID: %s, Upload ID: %s\n",
initiateResult.statusCode(), initiateResult.requestId(), uploadId);
// Step 2: Upload parts.
File file = new File(filePath);
long fileSize = file.length();
long partSize = 100 * 1024; // 100 KB per part.
int partNumber = 1;
List<Part> uploadParts = new ArrayList<>();
for (long start = 0; start < fileSize; start += partSize) {
long curPartSize = Math.min(partSize, fileSize - start);
// Read a file part and upload it.
try (InputStream is = new FileInputStream(file)) {
is.skip(start);
BoundedInputStream boundedInputStream = new BoundedInputStream(is, curPartSize);
// Upload the part.
UploadPartResult partResult = client.uploadPart(UploadPartRequest.newBuilder()
.bucket(bucket)
.key(key)
.uploadId(uploadId)
.partNumber((long) partNumber)
.body(BinaryData.fromStream(boundedInputStream))
.build());
System.out.printf("Status code: %d, Request ID: %s, Part number: %d, ETag: %s\n",
partResult.statusCode(), partResult.requestId(), partNumber, partResult.eTag());
uploadParts.add(Part.newBuilder()
.partNumber((long) partNumber)
.eTag(partResult.eTag())
.build());
}
partNumber++;
}
// Step 3: Complete the multipart upload.
uploadParts.sort((p1, p2) -> p1.partNumber().compareTo(p2.partNumber()));
CompleteMultipartUpload completeMultipartUpload = CompleteMultipartUpload.newBuilder()
.parts(uploadParts)
.build();
CompleteMultipartUploadResult completeResult = client.completeMultipartUpload(
CompleteMultipartUploadRequest.newBuilder()
.bucket(bucket)
.key(key)
.uploadId(uploadId)
.completeMultipartUpload(completeMultipartUpload)
.build());
System.out.printf("Completed multipart upload. Status code: %d, Request ID: %s, Bucket: %s, Key: %s, Location: %s, ETag: %s\n",
completeResult.statusCode(), completeResult.requestId(),
completeResult.completeMultipartUpload().bucket(),
completeResult.completeMultipartUpload().key(),
completeResult.completeMultipartUpload().location(),
completeResult.completeMultipartUpload().eTag());
} catch (Exception e) {
System.out.printf("Error:\n%s", e);
e.printStackTrace();
} finally {
// Close the client.
try {
client.close();
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
Java SDK V1
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
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;
/**
* Sample OSS multipart upload (V1 SDK).
* Implements multipart upload for large files.
*/
public class MultipartUpload {
public static void main(String[] args) {
// Obtain access credentials from environment variables.
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// Set the OSS region and endpoint.
String region = "cn-hangzhou";
String endpoint = "oss-cn-hangzhou.aliyuncs.com";
// Configure bucket and file information.
String bucketName = "example-bucket";
String objectName = "dest.jpg";
String filePath = "dest.jpg";
// Create a credential provider.
DefaultCredentialProvider provider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);
// Configure client parameters.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
// Initialize the OSS client.
OSS ossClient = OSSClientBuilder.create()
.credentialsProvider(provider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.endpoint(endpoint)
.build();
try {
// Step 1: Initialize the multipart upload.
InitiateMultipartUploadRequest initiateRequest = new InitiateMultipartUploadRequest(bucketName, objectName);
InitiateMultipartUploadResult initiateResult = ossClient.initiateMultipartUpload(initiateRequest);
String uploadId = initiateResult.getUploadId();
System.out.printf("Initiated multipart upload successfully. Upload ID: %s\n", uploadId);
// Step 2: Upload parts.
File file = new File(filePath);
long fileLength = file.length();
long partSize = 100 * 1024L; // 100 KB per part.
// Calculate the number of parts.
int partCount = (int) (fileLength / partSize);
if (fileLength % partSize != 0) {
partCount++;
}
// Save the ETags of uploaded parts.
List<PartETag> partETags = new ArrayList<>();
// Traverse and upload parts.
for (int i = 0; i < partCount; i++) {
long startPos = i * partSize;
long curPartSize = (i + 1 == partCount) ? (fileLength - startPos) : partSize;
// Create an upload part request.
UploadPartRequest uploadPartRequest = new UploadPartRequest();
uploadPartRequest.setBucketName(bucketName);
uploadPartRequest.setKey(objectName);
uploadPartRequest.setUploadId(uploadId);
uploadPartRequest.setPartNumber(i + 1);
uploadPartRequest.setPartSize(curPartSize);
// Read a file part and upload it.
try (InputStream instream = new FileInputStream(file)) {
instream.skip(startPos);
uploadPartRequest.setInputStream(instream);
UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
partETags.add(uploadPartResult.getPartETag());
System.out.printf("Uploaded part %d/%d successfully. ETag: %s\n",
i + 1, partCount, uploadPartResult.getPartETag().getETag());
}
}
// Step 3: Complete the multipart upload.
CompleteMultipartUploadRequest completeRequest = new CompleteMultipartUploadRequest(
bucketName, objectName, uploadId, partETags);
CompleteMultipartUploadResult completeResult = ossClient.completeMultipartUpload(completeRequest);
System.out.printf("Completed multipart upload. ETag: %s\n", completeResult.getETag());
} catch (Exception e) {
System.out.printf("Error: %s\n", e.getMessage());
e.printStackTrace();
} finally {
// Close the client.
ossClient.shutdown();
}
}
}
Python SDK V2
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Sample multipart upload using OSS Python SDK V2.
# Implements multipart upload for large files.
import alibabacloud_oss_v2 as oss
import os
def main():
# Obtain access credentials from environment variables.
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
# Load the default configurations of the SDK.
config = oss.config.load_default()
config.credentials_provider = credentials_provider
# Set the OSS region and endpoint.
config.region = "cn-hangzhou"
config.endpoint = "oss-cn-hangzhou.aliyuncs.com"
# Initialize the OSS client.
client = oss.Client(config)
# Configure bucket and file information.
bucket = "example-bucket"
key = "dest.jpg"
file_path = "dest.jpg"
try:
# Step 1: Initialize the multipart upload.
initiate_result = client.initiate_multipart_upload(
oss.InitiateMultipartUploadRequest(
bucket=bucket,
key=key
))
upload_id = initiate_result.upload_id
print(f"Initiated multipart upload successfully. Status code: {initiate_result.status_code}, "
f"Request ID: {initiate_result.request_id}, Upload ID: {upload_id}")
# Step 2: Upload parts.
file_size = os.path.getsize(file_path)
part_size = 100 * 1024 # 100 KB per part.
part_number = 1
upload_parts = []
offset = 0
with open(file_path, 'rb') as f:
while offset < file_size:
# Calculate the size of the current part.
current_part_size = min(part_size, file_size - offset)
# Read the part data.
f.seek(offset)
part_data = f.read(current_part_size)
# Upload the part.
part_result = client.upload_part(
oss.UploadPartRequest(
bucket=bucket,
key=key,
upload_id=upload_id,
part_number=part_number,
body=part_data
))
print(f"Status code: {part_result.status_code}, Request ID: {part_result.request_id}, "
f"Part number: {part_number}, ETag: {part_result.etag}")
# Record the information of the uploaded part.
upload_parts.append(oss.UploadPart(
part_number=part_number,
etag=part_result.etag
))
offset += current_part_size
part_number += 1
# Step 3: Complete the multipart upload.
upload_parts.sort(key=lambda p: p.part_number)
complete_result = client.complete_multipart_upload(
oss.CompleteMultipartUploadRequest(
bucket=bucket,
key=key,
upload_id=upload_id,
complete_multipart_upload=oss.CompleteMultipartUpload(
parts=upload_parts
)
))
print(f"Completed multipart upload. Status code: {complete_result.status_code}, "
f"Request ID: {complete_result.request_id}, "
f"Bucket: {complete_result.bucket}, "
f"Key: {complete_result.key}, "
f"Location: {complete_result.location}, "
f"ETag: {complete_result.etag}")
except Exception as e:
print(f"Error: {e}")
raise
if __name__ == "__main__":
main()
Python SDK V1
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Sample multipart upload using OSS Python SDK V1.
# Implements multipart upload for large files.
import os
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2 import SizedFileAdapter
from oss2.models import PartInfo
def main():
# Obtain access credentials from environment variables.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Set the OSS region and endpoint.
region = "cn-hangzhou"
endpoint = "oss-cn-hangzhou.aliyuncs.com"
# Configure bucket and file information.
bucket_name = "example-bucket"
key = "dest.jpg"
file_path = "dest.jpg"
# Initialize the OSS bucket.
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
try:
# Step 1: Initialize the multipart upload.
upload_id = bucket.init_multipart_upload(key).upload_id
print(f"Initiated multipart upload successfully. Upload ID: {upload_id}")
# Step 2: Upload parts.
file_size = os.path.getsize(file_path)
part_size = 100 * 1024 # 100 KB per part.
part_number = 1
parts = []
offset = 0
with open(file_path, 'rb') as fileobj:
while offset < file_size:
# Calculate the size of the current part.
current_part_size = min(part_size, file_size - offset)
# Upload the part.
result = bucket.upload_part(
key,
upload_id,
part_number,
SizedFileAdapter(fileobj, current_part_size)
)
print(f"Part number: {part_number}, ETag: {result.etag}")
# Record the information of the uploaded part.
parts.append(PartInfo(part_number, result.etag))
offset += current_part_size
part_number += 1
# Step 3: Complete the multipart upload.
result = bucket.complete_multipart_upload(key, upload_id, parts)
print(f"Completed multipart upload. ETag: {result.etag}")
except Exception as e:
print(f"Error: {e}")
raise
if __name__ == "__main__":
main()
Go SDK V2
package main
// Sample multipart upload using OSS Go SDK V2.
// Implements multipart upload for large files.
import (
"context"
"fmt"
"io"
"os"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
func main() {
// Obtain access credentials from environment variables.
// Configure the OSS client, set the credential provider and endpoint.
config := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion("cn-hangzhou").
WithEndpoint("oss-cn-hangzhou.aliyuncs.com")
// Initialize the OSS client.
client := oss.NewClient(config)
// Configure bucket and file information.
bucket := "example-bucket"
key := "dest.jpg"
filePath := "dest.jpg"
// Step 1: Initialize the multipart upload.
initResult, err := client.InitiateMultipartUpload(context.TODO(), &oss.InitiateMultipartUploadRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
})
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
uploadId := *initResult.UploadId
fmt.Printf("Initiated multipart upload successfully. Upload ID: %s\n", uploadId)
// Step 2: Upload parts.
file, err := os.Open(filePath)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
defer file.Close()
fileInfo, err := file.Stat()
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fileSize := fileInfo.Size()
partSize := int64(100 * 1024) // 100 KB per part.
partNumber := int32(1)
var parts []oss.UploadPart
for offset := int64(0); offset < fileSize; offset += partSize {
// Calculate the size of the current part.
currentPartSize := partSize
if offset+partSize > fileSize {
currentPartSize = fileSize - offset
}
// Read the part data.
file.Seek(offset, 0)
partData := io.LimitReader(file, currentPartSize)
// Upload the part.
partResult, err := client.UploadPart(context.TODO(), &oss.UploadPartRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
UploadId: oss.Ptr(uploadId),
PartNumber: partNumber,
Body: partData,
})
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Part number: %d, ETag: %s\n", partNumber, *partResult.ETag)
// Record the information of the uploaded part.
parts = append(parts, oss.UploadPart{
PartNumber: partNumber,
ETag: partResult.ETag,
})
partNumber++
}
// Step 3: Complete the multipart upload.
completeResult, err := client.CompleteMultipartUpload(context.TODO(), &oss.CompleteMultipartUploadRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
UploadId: oss.Ptr(uploadId),
CompleteMultipartUpload: &oss.CompleteMultipartUpload{
Parts: parts,
},
})
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Completed multipart upload. Bucket: %s, Key: %s, Location: %s, ETag: %s\n",
*completeResult.Bucket, *completeResult.Key, *completeResult.Location, *completeResult.ETag)
}
Go SDK V1
package main
// Sample multipart upload using OSS Go SDK V1.
// Implements multipart upload for large files.
import (
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Obtain access credentials from environment variables.
provider, _ := oss.NewEnvironmentVariableCredentialsProvider()
// Create an OSS client instance.
client, _ := oss.New(
"oss-cn-hangzhou.aliyuncs.com",
"",
"",
oss.SetCredentialsProvider(&provider),
oss.AuthVersion(oss.AuthV4),
oss.Region("cn-hangzhou"),
)
// Obtain the bucket object.
bucket, _ := client.Bucket("example-bucket")
// Configure file information.
key := "dest.jpg"
filePath := "dest.jpg"
// Step 1: Initialize the multipart upload.
imur, err := bucket.InitiateMultipartUpload(key)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Initiated multipart upload successfully. Upload ID: %s\n", imur.UploadID)
// Step 2: Upload parts.
file, err := os.Open(filePath)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
defer file.Close()
fileInfo, err := file.Stat()
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fileSize := fileInfo.Size()
partSize := int64(100 * 1024) // 100 KB per part.
// Split the file into parts.
chunks, err := oss.SplitFileByPartSize(filePath, partSize)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
var parts []oss.UploadPart
for _, chunk := range chunks {
part, err := bucket.UploadPart(imur, file, chunk.Size, chunk.Number)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Part number: %d, ETag: %s\n", chunk.Number, part.ETag)
parts = append(parts, part)
}
// Step 3: Complete the multipart upload.
_, err = bucket.CompleteMultipartUpload(imur, parts)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Completed multipart upload. File size: %d bytes\n", fileSize)
}
Limpar partes incompletas
Devido a uma alteração de política para melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do OSS devem usar um nome de domínio personalizado (CNAME) para executar operações de API de dados em buckets do OSS localizados em regiões da China continental. Os endpoints públicos padrão estão restritos para essas operações. Consulte o anúncio oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via HTTPS, será necessário vincular um certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao OSS Console, pois o console impõe o uso de HTTPS.
Se um upload multipart for interrompido sem a chamada de AbortMultipartUpload, as partes enviadas permanecerão no bucket e continuarão a gerar taxas de armazenamento. Limpe essas partes para evitar custos desnecessários.
Usar o console
Acesse a lista de Buckets e clique em no bucket de destino.
Na lista Objects, clique em Parts para visualizar e excluir partes.
Usar regras de ciclo de vida
Regras de ciclo de vida limpam automaticamente partes expiradas, reduzindo a manutenção manual. Para mais informações, consulte Limpar partes expiradas usando regras de ciclo de vida.
Usar ferramentas
-
ossbrowser
Na página de lista de objetos do bucket, clique em Parts para visualizar e excluir partes.
-
ossutil
Use o comando abort-multipart-upload para cancelar um upload multipart e excluir os dados das partes:
ossutil api abort-multipart-upload --bucket example-bucket --key dest.jpg --upload-id D9F4****************************
Usar SDKs
Chame AbortMultipartUpload para cancelar um upload multipart e excluir os dados das partes. As seções a seguir mostram códigos de exemplo para SDKs comuns. Para outras linguagens, consulte a Referência do SDK.
Antes de executar o código, instale o SDK e configure as credenciais de acesso como variáveis de ambiente. Se você usar um usuário RAM ou uma função RAM, conceda as permissões necessárias. Para mais informações, consulte Permissões de API .
Java SDK V2
import com.aliyun.sdk.service.oss2.OSSClient;
import com.aliyun.sdk.service.oss2.credentials.CredentialsProvider;
import com.aliyun.sdk.service.oss2.credentials.StaticCredentialsProvider;
import com.aliyun.sdk.service.oss2.models.AbortMultipartUploadRequest;
import com.aliyun.sdk.service.oss2.models.AbortMultipartUploadResult;
/**
* Sample for canceling an OSS multipart upload.
* Shows how to cancel a multipart upload.
*/
public class AbortMultipartUpload {
public static void main(String[] args) {
// Obtain access credentials from environment variables.
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// Set the OSS region and endpoint.
String region = "cn-hangzhou";
String endpoint = "oss-cn-hangzhou.aliyuncs.com";
// Configure bucket and file information.
String bucket = "example-bucket";
String key = "dest.jpg";
String uploadId = "D9F4****************************";
// Create a credential provider.
CredentialsProvider provider = new StaticCredentialsProvider(accessKeyId, accessKeySecret);
// Initialize the OSS client.
OSSClient client = OSSClient.newBuilder()
.credentialsProvider(provider)
.region(region)
.endpoint(endpoint)
.build();
try {
// Cancel the multipart upload.
AbortMultipartUploadResult result = client.abortMultipartUpload(
AbortMultipartUploadRequest.newBuilder()
.bucket(bucket)
.key(key)
.uploadId(uploadId)
.build());
System.out.printf("Canceled multipart upload successfully. Status code: %d, Request ID: %s\n",
result.statusCode(), result.requestId());
} catch (Exception e) {
System.out.printf("Error: %s\n", e.getMessage());
e.printStackTrace();
} finally {
// Close the client.
try {
client.close();
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
Java SDK V1
import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;
/**
* Sample for canceling an OSS multipart upload (V1 SDK).
* Shows how to cancel a multipart upload.
*/
public class AbortMultipartUpload {
public static void main(String[] args) {
// Obtain access credentials from environment variables.
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// Set the OSS region and endpoint.
String region = "cn-hangzhou";
String endpoint = "oss-cn-hangzhou.aliyuncs.com";
// Configure bucket and file information.
String bucketName = "example-bucket";
String objectName = "dest.jpg";
String uploadId = "D9F4****************************";
// Create a credential provider.
DefaultCredentialProvider provider = new DefaultCredentialProvider(accessKeyId, accessKeySecret);
// Configure client parameters.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
// Initialize the OSS client.
OSS ossClient = OSSClientBuilder.create()
.credentialsProvider(provider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.endpoint(endpoint)
.build();
try {
// Cancel the multipart upload.
AbortMultipartUploadRequest abortMultipartUploadRequest =
new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
ossClient.abortMultipartUpload(abortMultipartUploadRequest);
System.out.printf("Canceled multipart upload successfully. Upload ID: %s\n", uploadId);
} catch (Exception e) {
System.out.printf("Error: %s\n", e.getMessage());
e.printStackTrace();
} finally {
// Close the client.
ossClient.shutdown();
}
}
}
Python SDK V2
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Sample for canceling a multipart upload using OSS Python SDK V2.
# Cancels a multipart upload and deletes the uploaded parts.
import alibabacloud_oss_v2 as oss
def main():
# Obtain access credentials from environment variables.
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
# Load the default configurations of the SDK.
config = oss.config.load_default()
config.credentials_provider = credentials_provider
# Set the OSS region and endpoint.
config.region = "cn-hangzhou"
config.endpoint = "oss-cn-hangzhou.aliyuncs.com"
# Initialize the OSS client.
client = oss.Client(config)
# Configure bucket and file information.
bucket = "example-bucket"
key = "dest.jpg"
upload_id = "D9F4****************************"
# Cancel the multipart upload.
result = client.abort_multipart_upload(
oss.AbortMultipartUploadRequest(
bucket=bucket,
key=key,
upload_id=upload_id
))
print(f"Canceled multipart upload successfully. Status code: {result.status_code}, Request ID: {result.request_id}")
if __name__ == "__main__":
main()
Python SDK V1
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Sample for canceling a multipart upload using OSS Python SDK V1.
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def main():
# Obtain access credentials from environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Set the OSS region and endpoint.
region = "cn-hangzhou"
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Configure bucket and file information.
bucket_name = "example-bucket"
key = "dest.jpg"
upload_id = "D9F4****************************"
# Initialize the OSS client.
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
# Cancel the multipart upload.
bucket.abort_multipart_upload(key, upload_id)
print(f"Canceled multipart upload successfully. Upload ID: {upload_id}")
if __name__ == "__main__":
main()
Go SDK V2
package main
// Sample for canceling a multipart upload using OSS Go SDK V2.
import (
"context"
"fmt"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
func main() {
// Obtain access credentials from environment variables.
// Configure the OSS client, set the credential provider and endpoint.
config := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
WithRegion("cn-hangzhou").
WithEndpoint("oss-cn-hangzhou.aliyuncs.com")
// Initialize the OSS client.
client := oss.NewClient(config)
// Configure bucket and file information.
bucket := "example-bucket"
key := "dest.jpg"
uploadId := "D9F4****************************"
// Cancel the multipart upload.
client.AbortMultipartUpload(context.TODO(), &oss.AbortMultipartUploadRequest{
Bucket: oss.Ptr(bucket),
Key: oss.Ptr(key),
UploadId: oss.Ptr(uploadId),
})
fmt.Printf("Canceled multipart upload successfully. Upload ID: %s\n", uploadId)
}
Go SDK V1
package main
// Sample for canceling a multipart upload using OSS Go SDK V1.
import (
"fmt"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Obtain access credentials from environment variables.
provider, _ := oss.NewEnvironmentVariableCredentialsProvider()
// Create an OSS client instance.
client, _ := oss.New(
"oss-cn-hangzhou.aliyuncs.com",
"",
"",
oss.SetCredentialsProvider(&provider),
oss.AuthVersion(oss.AuthV4),
oss.Region("cn-hangzhou"),
)
// Obtain the bucket object.
bucket, _ := client.Bucket("example-bucket")
// Configure file information.
key := "dest.jpg"
uploadId := "D9F4****************************"
// Create an InitiateMultipartUploadResult object.
imur := oss.InitiateMultipartUploadResult{
UploadID: uploadId,
Key: key,
}
// Cancel the multipart upload.
bucket.AbortMultipartUpload(imur)
fmt.Printf("Canceled multipart upload successfully. Upload ID: %s\n", uploadId)
}
Aplicar em produção
Melhores práticas
-
Otimização de desempenho: Melhorar velocidade e estabilidade do upload
Controle o número de partes simultâneas: Equilibre a concorrência com a largura de banda disponível e a carga do dispositivo. Conexões excessivas causam congestionamento; poucas conexões subutilizam a rede.
Evite prefixos sequenciais nos nomes: Não use prefixos sequenciais, como carimbos de data/hora, nos nomes dos objetos. Isso concentra solicitações em uma única partição e causa hotspots. Para mais informações, consulte Melhores práticas de desempenho do OSS.
-
Garantia de confiabilidade: Implementar uploads retomáveis
Uploads multipart não expiram e permitem pausa e retomada. Use o UploadId como identificador da tarefa. Se uma parte falhar, reenvie apenas essa parte em vez de todo o arquivo.
-
Otimização de custos: Ajustar a estratégia de upload para Deep Cold Archive
Para otimizar custos no Deep Cold Archive, envie arquivos como objetos Standard e use uma regra de ciclo de vida para fazer a transição deles. Isso evita taxas PUT por solicitação mais altas associadas a uploads diretos.
Prevenção de riscos
-
Segurança de dados: Evitar sobrescrita de arquivos
Defina
x-oss-forbid-overwritecomotrueno cabeçalho da solicitação para impedir sobrescritas de mesmo nome que podem causar perda de dados. Você também pode ativar o versionamento para reter versões históricas.
Limites
|
Limite |
Descrição |
|
Tamanho de um único arquivo |
Até 48,8 TB |
|
Número de partes |
1 a 10.000 |
|
Tamanho de uma única parte |
O tamanho mínimo é 100 KB e o máximo é 5 GB. O tamanho da última parte pode ser inferior a 100 KB. |
|
Número máximo de partes retornadas em uma única solicitação ListParts |
1.000 |
|
Número máximo de eventos de upload multipart retornados em uma única solicitação ListMultipartUploads |
1.000 |
Faturamento
A tabela a seguir lista os itens faturáveis para operações de upload multipart. Para mais informações sobre faturamento, consulte Taxas de solicitação e Taxas de armazenamento.
|
API |
Item faturável |
Descrição |
|
InitiateMultipartUpload |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
|
UploadPart |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
|
Taxas de armazenamento |
As taxas de armazenamento são cobradas com base na classe de armazenamento das partes (que é a mesma do objeto), no tamanho real e na duração do armazenamento. Não há unidade mínima de medição. O faturamento cessa após as partes serem excluídas ou combinadas em um objeto completo. |
|
|
UploadPartCopy |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
|
CompleteMultipartUpload |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
|
Taxas de armazenamento |
As taxas de armazenamento são cobradas com base na classe de armazenamento, no tamanho e na duração do objeto. |
|
|
AbortMultipartUpload |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. Importante
|
|
ListMultipartUploads |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
|
ListParts |
Solicitações PUT |
As taxas são calculadas com base no número de solicitações bem-sucedidas. |
Ao usar UploadPartCopy para copiar dados de um objeto existente e enviar uma parte, se a classe de armazenamento do objeto de origem for Infrequent Access (IA), Archive ou Cold Archive, serão incorridas taxas de recuperação de dados (se o objeto de origem usar a classe de armazenamento Archive e o acesso em tempo real a objetos Archive estiver ativado, serão incorridas taxas de acesso em tempo real para objetos Archive). Além disso, classes de armazenamento como IA, Archive e Cold Archive possuem requisitos de duração mínima de armazenamento e tamanho mínimo faturável, o que pode gerar as taxas mínimas de armazenamento correspondentes.
Permissões de API
Uma conta Alibaba Cloud possui permissões totais de API por padrão. Usuários RAM e funções RAM exigem permissões explícitas para cada operação de API. Para mais informações, consulte Políticas RAM e Exemplos comuns de políticas RAM.
|
API |
Ação |
Descrição |
|
InitiateMultipartUpload |
|
Inicializa um upload multipart. |
|
|
Esta permissão é necessária se você especificar tags de objeto usando x-oss-tagging ao inicializar um upload multipart. |
|
|
|
Estas permissões são necessárias se os metadados do objeto contiverem X-Oss-Server-Side-Encryption: KMS ao enviar um objeto. |
|
|
|
||
|
UploadPart |
|
Envia uma parte. |
|
UploadPartCopy |
|
A permissão para ler o objeto de origem é necessária ao enviar uma parte copiando dados de um objeto existente. |
|
|
A permissão para gravar no objeto de destino é necessária ao enviar uma parte copiando dados de um objeto existente. |
|
|
|
A permissão para ler a versão especificada do objeto de origem é necessária se você definir a versão do objeto usando versionId ao enviar uma parte copiando dados de um objeto existente. |
|
|
CompleteMultipartUpload |
|
Combina partes em um objeto. |
|
|
Esta permissão é necessária se você especificar tags de objeto usando x-oss-tagging ao combinar partes em um objeto. |
|
|
AbortMultipartUpload |
|
Cancela um evento de upload multipart e exclui os dados das partes correspondentes. |
|
ListMultipartUploads |
|
Lista todos os eventos de upload multipart em andamento. Trata-se de eventos iniciados, mas ainda não concluídos ou abortados. |
|
ListParts |
|
Lista todas as partes enviadas com sucesso que pertencem a um UploadId especificado. |