Todos os produtos
Search
Central de documentação

Object Storage Service:Upload multipart

Última atualização: Jul 08, 2026

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:

  1. 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.

  2. 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.

  3. 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.

image

Implementar upload multipart

Importante

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.

Nota
  • 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

Importante

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

  1. Acesse a lista de Buckets e clique em no bucket de destino.

  2. 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-overwrite como true no 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
  • Nas regiões da China continental, as taxas de solicitação PUT para exclusão de partes Infrequent Access, Archive e Cold Archive usando regras de ciclo de vida são maiores do que as taxas para exclusão de partes Standard. Nenhuma taxa de solicitação PUT é cobrada para exclusão de partes Deep Cold Archive usando regras de ciclo de vida.

  • Na região de Hong Kong (China) e em regiões fora da China, nenhuma taxa de solicitação PUT é cobrada para exclusão de partes de qualquer classe de armazenamento usando regras de ciclo de vida.

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.

Nota

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

oss:PutObject

Inicializa um upload multipart.

oss:PutObjectTagging

Esta permissão é necessária se você especificar tags de objeto usando x-oss-tagging ao inicializar um upload multipart.

kms:GenerateDataKey

Estas permissões são necessárias se os metadados do objeto contiverem X-Oss-Server-Side-Encryption: KMS ao enviar um objeto.

kms:Decrypt

UploadPart

oss:PutObject

Envia uma parte.

UploadPartCopy

oss:GetObject

A permissão para ler o objeto de origem é necessária ao enviar uma parte copiando dados de um objeto existente.

oss:PutObject

A permissão para gravar no objeto de destino é necessária ao enviar uma parte copiando dados de um objeto existente.

oss:GetObjectVersion

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

oss:PutObject

Combina partes em um objeto.

oss:PutObjectTagging

Esta permissão é necessária se você especificar tags de objeto usando x-oss-tagging ao combinar partes em um objeto.

AbortMultipartUpload

oss:AbortMultipartUpload

Cancela um evento de upload multipart e exclui os dados das partes correspondentes.

ListMultipartUploads

oss:ListMultipartUploads

Lista todos os eventos de upload multipart em andamento. Trata-se de eventos iniciados, mas ainda não concluídos ou abortados.

ListParts

oss:ListParts

Lista todas as partes enviadas com sucesso que pertencem a um UploadId especificado.