本文由簡體中文內容自動轉碼而成。阿里雲不保證此自動轉碼的準確性、完整性及時效性。本文内容請以簡體中文版本為準。
首頁Object Storage Service開發參考SDK参考Java對象/檔案上傳檔案分區上傳
搜尋幫助內容

Java分區上傳

更新時間：2025-02-25 19:04
產品
社區

OSS提供的分區上傳（Multipart Upload）功能，將要上傳的較大檔案（Object）分成多個分區（Part）來分別上傳，上傳完成後再調用CompleteMultipartUpload介面將這些Part組合成一個Object來達到斷點續傳的效果。

注意事項

  • 本文以華東1（杭州）外網Endpoint為例。如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。

  • 本文以從環境變數讀取存取憑證為例。如何配置訪問憑證，請參見Java配置訪問憑證。

  • 本文以OSS網域名稱建立OSSClient為例。如果您希望通過自訂網域名、STS等方式建立OSSClient，請參見常見情境配置樣本。

  • 要完成分區上傳的完整流程，包括InitiateMultipartUpload、UploadPart、CompleteMultipartUpload，您必須有oss:PutObject許可權。具體操作，請參見為RAM使用者授權自訂的權限原則。

分區上傳流程

分區上傳（Multipart Upload）分為以下三個步驟：

  1. 初始化一個分區上傳事件。

    調用ossClient.initiateMultipartUpload方法返回OSS建立的全域唯一的uploadId。

  2. 上傳分區。

    調用ossClient.uploadPart方法上傳分區資料。

    說明

    • 對於同一個uploadId，分區號（PartNumber）標識了該分區在整個檔案內的相對位置。如果使用同一個分區號上傳了新的資料，則OSS上該分區已有的資料將會被覆蓋。

    • OSS將收到的分區資料的MD5值放在ETag頭內返回給使用者。

    • OSS計算上傳資料的MD5值，並與SDK計算的MD5值比較，如果不一致則返回InvalidDigest錯誤碼。

  3. 完成分區上傳。

    所有分區上傳完成後，調用ossClient.completeMultipartUpload方法將所有分區合并成完整的檔案。

範例程式碼

以下通過一個完整的樣本對分區上傳的流程進行逐步解析：

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 {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/exampleobject.txt";
        // 待上傳本地檔案路徑。
        String filePath = "D:\\localpath\\examplefile.txt";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // 建立InitiateMultipartUploadRequest對象。
            InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);

            // 建立ObjectMetadata並設定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());

            // 將metadata綁定到上傳請求中。
            request.setObjectMetadata(metadata);

            // 初始化分區。
            InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
            // 返回uploadId。
            String uploadId = upresult.getUploadId();

            // partETags是PartETag的集合。PartETag由分區的ETag和分區號組成。
            List<PartETag> partETags = new ArrayList<PartETag>();
            // 每個分區的大小，用於計算檔案有多少個分區。單位為位元組。
            // 分區最小值為100 KB，最大值為5 GB。最後一個分區的大小允許小於100 KB。
            // 設定分區大小為 1 MB。
            final long partSize = 1 * 1024 * 1024L;   

            // 根據上傳的資料大小計算分區數。以本地檔案為例，說明如何通過File.length()擷取上傳資料的大小。
            final File sampleFile = new File(filePath);
            long fileLength = sampleFile.length();
            int partCount = (int) (fileLength / partSize);
            if (fileLength % partSize != 0) {
                partCount++;
            }
            // 遍曆分區上傳。
            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);
                // 設定上傳的分區流。
                // 以本地檔案為例說明如何建立FileInputStream，並通過InputStream.skip()方法跳過指定資料。
                InputStream instream = new FileInputStream(sampleFile);
                instream.skip(startPos);
                uploadPartRequest.setInputStream(instream);
                // 設定分區大小。
                uploadPartRequest.setPartSize(curPartSize);
                // 設定分區號。每一個上傳的分區都有一個分區號，取值範圍是1~10000，如果超出此範圍，OSS將返回InvalidArgument錯誤碼。
                uploadPartRequest.setPartNumber(i + 1);
                // 每個分區不需要按順序上傳，甚至可以在不同用戶端上傳，OSS會按照分區號排序組成完整的檔案。
                UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
                // 每次上傳分區之後，OSS的返回結果包含PartETag。PartETag將被儲存在partETags中。
                partETags.add(uploadPartResult.getPartETag());

                // 關閉流
                instream.close();
            }

            // 建立CompleteMultipartUploadRequest對象。
            // 在執行完成分區上傳操作時，需要提供所有有效partETags。OSS收到提交的partETags後，會逐一驗證每個分區的有效性。當所有的資料分區驗證通過後，OSS將把這些分區組合成一個完整的檔案。
            CompleteMultipartUploadRequest completeMultipartUploadRequest =
                    new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);

            // 完成分區上傳。
            CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
            System.out.println("上傳成功，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();
            }
        }
    }
}

常見使用情境

初始化分區時設定中繼資料

在初始化分區時設定中繼資料的範例程式碼片段如下。

// 建立InitiateMultipartUploadRequest對象。
InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);

ObjectMetadata metadata = new ObjectMetadata();
metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
// 指定該Object的網頁緩衝行為。
metadata.setCacheControl("no-cache");
// 指定該Object被下載時的名稱。
metadata.setContentDisposition("attachment;filename=oss_MultipartUpload.txt");
// 指定該Object的內容編碼格式。
metadata.setContentEncoding(OSSConstants.DEFAULT_CHARSET_NAME);
// 指定初始化分區上傳時是否覆蓋同名Object。此處設定為true，表示禁止覆蓋同名Object。
metadata.setHeader("x-oss-forbid-overwrite", "true");
// 指定上傳該Object的每個part時使用的伺服器端加密方式。
metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION, ObjectMetadata.KMS_SERVER_SIDE_ENCRYPTION);
// 指定Object的密碼編譯演算法。如果未指定此選項，表明Object使用AES256密碼編譯演算法。
metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_DATA_ENCRYPTION, ObjectMetadata.KMS_SERVER_SIDE_ENCRYPTION);
// 指定KMS託管的使用者主要金鑰。
metadata.setHeader(OSSHeaders.OSS_SERVER_SIDE_ENCRYPTION_KEY_ID, "9468da86-3509-4f8d-a61e-6eab1eac****");
// 指定Object的儲存類型。
metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard);
// 指定Object的對象標籤，可同時設定多個標籤。
metadata.setHeader(OSSHeaders.OSS_TAGGING, "a:1");
request.setObjectMetadata(metadata);

// 根據檔案自動化佈建ContentType。如果不設定，ContentType預設值為application/oct-srream。
if (metadata.getContentType() == null) {
    metadata.setContentType(Mimetypes.getInstance().getMimetype(new File(filePath), objectName));
}

// 將metadata綁定到上傳請求中。
request.setObjectMetadata(metadata);
// 初始化分區。
InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);

在完成分區上傳時設定檔案存取權限

在完成分區上傳的同時設定檔案存取權限的範例程式碼如下。

completeMultipartUploadRequest.setObjectACL(CannedAccessControlList.Private);

在完成分區上傳時自動處理分區的ETags

在完成分區上傳時自動處理分區的ETags的範例程式碼如下。

// 指定是否列舉當前UploadId已上傳的所有Part。僅在Java SDK為3.14.0及以上版本時，支援通過服務端List分區資料來合并完整檔案時，將CompleteMultipartUploadRequest中的partETags設定為null。
Map<String, String> headers = new HashMap<String, String>();
// 如果指定了x-oss-complete-all:yes，則OSS會列舉當前UploadId已上傳的所有Part，然後按照PartNumber的序號排序並執行CompleteMultipartUpload操作。
// 如果指定了x-oss-complete-all:yes，則不允許繼續指定body，否則報錯。
headers.put("x-oss-complete-all","yes");
completeMultipartUploadRequest.setHeaders(headers);

取消分區上傳事件

如果您需要取消分區上傳事件的操作，您需要在調用InitiateMultipartUpload完成初始化分區之後擷取uploadId，然後使用擷取的uploadId調用abortMultipartUpload方法來取消分區上傳事件。當一個分區上傳事件被取消後，無法再使用該uploadId進行任何操作，已上傳的分區資料會被刪除。取消分區上傳事件的範例程式碼如下。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/exampleobject.txt";
        // 填寫uploadId，例如0004B999EF518A1FE585B0C9360D****。uploadId來源於調用InitiateMultipartUpload完成初始化分區之後的返回結果。
        String uploadId = "0004B999EF518A1FE585B0C9360D****";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 取消分區上傳。
            AbortMultipartUploadRequest abortMultipartUploadRequest =
                    new AbortMultipartUploadRequest(bucketName, objectName, uploadId);
            ossClient.abortMultipartUpload(abortMultipartUploadRequest);
        } 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 an 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();
            }
        }
    }
}

列舉已上傳的分區

如果您需要列舉已上傳分區，您需要在調用InitiateMultipartUpload完成初始化分區之後，且在調用CompleteMultipartUpload完成分區上傳之前擷取uploadId，然後使用uploadId調用listParts方法列舉出指定uploadId下所有已經上傳成功的分區。

簡單列舉已上傳的分區

以下代碼用於簡單列舉已上傳的分區。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/exampleobject.txt";
        // 填寫uploadId，例如0004B999EF518A1FE585B0C9360D****。uploadId來源於調用InitiateMultipartUpload完成初始化分區之後，且在調用CompleteMultipartUpload完成分區上傳之前的返回結果。
        String uploadId = "0004B999EF518A1FE585B0C9360D****";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 列舉已上傳的分區。
            ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);
            // 設定uploadId。
            //listPartsRequest.setUploadId(uploadId);
            // 設定分頁時每一頁中分區數量為100個。預設列舉1000個分區。
            listPartsRequest.setMaxParts(100);
            // 指定List的起始位置。只有分區號大於此參數值的分區會被列舉。
            listPartsRequest.setPartNumberMarker(2);
            PartListing partListing = ossClient.listParts(listPartsRequest);

            for (PartSummary part : partListing.getParts()) {
                // 擷取分區號。
                System.out.println(part.getPartNumber());
                // 擷取分區資料大小。
                System.out.println(part.getSize());
                // 擷取分區的ETag。
                System.out.println(part.getETag());
                // 擷取分區的最後修改時間。
                System.out.println(part.getLastModified());
            }
        } 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 an 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();
            }
        }
    }
}

列舉所有已上傳的分區

預設情況下，listParts只能一次列舉1000個分區。當分區數量大於1000時，請使用以下代碼列舉所有已上傳的分區。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/exampleobject.txt";
        // 填寫uploadId，例如0004B999EF518A1FE585B0C9360D****。uploadId來源於調用InitiateMultipartUpload完成初始化分區之後，且在調用CompleteMultipartUpload完成分區上傳之前的返回結果。
        String uploadId = "0004B999EF518A1FE585B0C9360D****";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 列舉所有已上傳的分區。
            PartListing partListing;
            ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);

            do {
                partListing = ossClient.listParts(listPartsRequest);

                for (PartSummary part : partListing.getParts()) {
                    // 擷取分區號。
                    System.out.println(part.getPartNumber());
                    // 擷取分區資料大小。
                    System.out.println(part.getSize());
                    // 擷取分區的ETag。
                    System.out.println(part.getETag());
                    // 擷取分區的最後修改時間。
                    System.out.println(part.getLastModified());
                }
                // 指定List的起始位置，只有分區號大於此參數值的分區會被列出。
                listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
            } while (partListing.isTruncated());
        } 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 an 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();
            }
        }
    }
}

分頁列舉所有已上傳的分區

以下代碼用於指定每頁分區的數量、分頁列舉所有分區。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/exampleobject.txt";
        // 填寫uploadId，例如0004B999EF518A1FE585B0C9360D****。uploadId來源於調用InitiateMultipartUpload完成初始化分區之後，且在調用CompleteMultipartUpload完成分區上傳之前的返回結果。
        String uploadId = "0004B999EF518A1FE585B0C9360D****";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 分頁列舉已上傳的分區。
            PartListing partListing;
            ListPartsRequest listPartsRequest = new ListPartsRequest(bucketName, objectName, uploadId);
            // 設定分頁列舉時，每頁列舉100個分區。
            listPartsRequest.setMaxParts(100);

            do {
                partListing = ossClient.listParts(listPartsRequest);

                for (PartSummary part : partListing.getParts()) {
                    // 擷取分區號。
                    System.out.println(part.getPartNumber());
                    // 擷取分區資料大小。
                    System.out.println(part.getSize());
                    // 擷取分區的ETag。
                    System.out.println(part.getETag());
                    // 擷取分區的最後修改時間。
                    System.out.println(part.getLastModified());
                }

                listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());

            } while (partListing.isTruncated());
        } 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 an 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();
            }
        }
    }
}

列舉分區上傳事件

調用listMultipartUploads方法列舉出所有執行中的分區上傳事件，即已初始化但尚未完成或已取消的分區上傳事件。可設定的參數請參見下表。

參數

作用

設定方法

prefix

限定返回的檔案名稱必須以指定的prefix作為首碼。注意使用prefix查詢時，返回的檔案名稱中仍會包含prefix。

ListMultipartUploadsRequest.setPrefix(String prefix)

delimiter

用於對檔案名稱進行分組的一個字元。所有名稱包含指定的首碼且第一次出現delimiter字元之間的檔案作為一組元素。

ListMultipartUploadsRequest.setDelimiter(String delimiter)

maxUploads

限定此次返回分區上傳事件的最大個數，預設值和最大值均為1000。

ListMultipartUploadsRequest.setMaxUploads(Integer maxUploads)

keyMarker

所有檔案名稱的字典序大於keyMarker參數值的分區上傳事件。與uploadIdMarker參數一同使用，用於指定返回結果的起始位置。

ListMultipartUploadsRequest.setKeyMarker(String keyMarker)

uploadIdMarker

與keyMarker參數一同使用，用於指定返回結果的起始位置。 如果未設定keyMarker參數，則此參數無效。如果設定了keyMarker參數，則查詢結果中包含：

  • 檔案名稱的字典序大於keyMarker參數值的所有檔案。

  • 檔案名稱等於keyMarker參數值且uploadId比uploadIdMarker參數值大的所有分區上傳事件。

ListMultipartUploadsRequest.setUploadIdMarker(String uploadIdMarker)

簡單列舉分區上傳事件

以下代碼用於列舉分區上傳事件。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 列舉分區上傳事件。預設列舉1000個分區。
            ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
            MultipartUploadListing multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);

            for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
                // 擷取uploadId。
                System.out.println(multipartUpload.getUploadId());
                // 擷取Key。
                System.out.println(multipartUpload.getKey());
                // 擷取分區上傳的初始化時間。
                System.out.println(multipartUpload.getInitiated());
            }
        } 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 an 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();
            }
        }
    }
}

返回結果中isTruncated為true，返回nextKeyMarker和nextUploadIdMarker作為下次讀取的起點。如果無法一次性擷取所有的上傳事件，可以採用分頁列舉的方式。

列舉全部分區上傳事件

預設情況下，listMultipartUploads只能一次列舉1000個分區。當分區數量大於1000時，請使用以下代碼列舉全部分區上傳事件。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 列舉分區上傳事件。
            MultipartUploadListing multipartUploadListing;
            ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);

            do {
                multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);

                for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
                    // 擷取uploadId。
                    System.out.println(multipartUpload.getUploadId());
                    // 擷取檔案名稱。
                    System.out.println(multipartUpload.getKey());
                    // 擷取分區上傳的初始化時間。
                    System.out.println(multipartUpload.getInitiated());
                }

                listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());

                listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
            } while (multipartUploadListing.isTruncated());
        } 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 an 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();
            }
        }
    }
}

分頁列舉全部上傳事件

以下代碼用於分頁列舉所有上傳事件。

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();
        
        try {
            // 列舉分區上傳事件。
            MultipartUploadListing multipartUploadListing;
            ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucketName);
            // 設定每頁列舉的分區上傳事件個數。
            listMultipartUploadsRequest.setMaxUploads(50);

            do {
                multipartUploadListing = ossClient.listMultipartUploads(listMultipartUploadsRequest);

                for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
                    // 擷取uploadId。
                    System.out.println(multipartUpload.getUploadId());
                    // 擷取Key。
                    System.out.println(multipartUpload.getKey());
                    // 擷取分區上傳的初始化時間。
                    System.out.println(multipartUpload.getInitiated());
                }

                listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
                listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());

            } while (multipartUploadListing.isTruncated());
        } 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 an 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();
            }
        }
    }
}

實現網路流或者資料流分區上傳

本文以本地檔案分區上傳為例進行介紹，如果您需要實現網路流或者資料流分區上傳，請參見資料流分區上傳。

相關文檔

  • 關於分區上傳的完整範例程式碼，請參見GitHub樣本。

  • 分區上傳的完整實現涉及三個API介面，詳情如下：

  • 關於取消分區上傳事件的API介面說明，請參見AbortMultipartUpload。

  • 關於列舉已上傳分區的API介面說明，請參見ListParts。

  • 關於列舉所有執行中的分區上傳事件的API介面說明，請參見ListMultipartUploads。

上一篇：斷點續傳上傳下一篇：進度條
  • 本頁導讀 （1, M）
  • 注意事項
  • 分區上傳流程
  • 範例程式碼
  • 常見使用情境
  • 初始化分區時設定中繼資料
  • 在完成分區上傳時設定檔案存取權限
  • 在完成分區上傳時自動處理分區的ETags
  • 取消分區上傳事件
  • 列舉已上傳的分區
  • 列舉分區上傳事件
  • 實現網路流或者資料流分區上傳
  • 相關文檔
文檔反饋
phone 聯絡我們