融合接口

功能说明

分片上传步骤较多，包括初始化、文件切片、各个分片上传、完成上传。为了简化分片上传，Java SDK 提供了分片上传的封装接口。您可以调用 TransferManager 接口，快速实现文件的分片上传与分片的管理。文件的上传时，TransferManager 会采用多线程的方式，同时进行多个文件的上传。

代码示例

• 使用 TransferManager 分片上传

public void upload() {
    try {
        String bucket = "<your-bucket-name>";
        String key = "<your-object-key>";
        String localPath = "<your-local-path>";
​
        // TransferManager 只需要初始化一次，可以用于多个上传任务
        TransferManager transMgr = TransferManagerBuilder.standard()
            .withS3Client(s3Client)
            // 设置最小分片大小，默认是5MB。
            .withMinimumUploadPartSize(10*1024*1024L)
            // 设置采用分片上传的阈值为100MB。只有当文件大于该值时，才会采用分片上传，否则采用普通上传。默认值是16MB。
            .withMultipartUploadThreshold(100*1024*1024L)
            .build();
​
        // TransferManager 采用异步方式进行处理，因此该调用会立即返回。
        PutObjectRequest request = new PutObjectRequest(bucket, key, new File(localPath));
        request.withCannedAcl(CannedAccessControlList.Private);     // 设置对象ACL，可以设置公共读CannedAccessControlList.PublicRead
        // request.setStorageClass(StorageClass.Standard);             // 设置对象的存储类别
        ObjectMetadata meta = new ObjectMetadata();
        meta.setContentType("application/octet-stream");            // 设置Content-Type，默认application/octet-stream
        request.setMetadata(meta);                                  // 还可以设置其他自定义元数据
​
        Upload upload = transMgr.upload(request);
        // 等待上传全部完成。
        UploadResult result = upload.waitForUploadResult();
        System.out.println("upload success, etag=" + result.getETag());
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
}

• 使用 TransferManager 分片复制

public void copy() {
    try {
        String destBucketName = "<your-bucket-name>";
        String destObjectKey = "<your-object-key>";
        String sourceBucketName = "<source-bucket-name>";
        String sourceObjectKey = "<source-object-key>";
​
        // TransferManager 只需要初始化一次，可以用于多个上传任务
        TransferManager transMgr = TransferManagerBuilder.standard()
            .withS3Client(s3Client)
            .withMinimumUploadPartSize(10*1024*1024L)
            .withMultipartUploadThreshold(100*1024*1024L)
            .build();
​
        // TransferManager 采用异步方式进行处理，因此该调用会立即返回。
        CopyObjectRequest request = new CopyObjectRequest(sourceBucketName, sourceObjectKey, destBucketName, destObjectKey);
        Copy copy = transMgr.copy(request);
        CopyResult result = copy.waitForCopyResult();
        System.out.println("copy success, etag=" + result.getETag());
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
}

• 取消分片上传

您可以使用 TransferManager.abortMultipartUploads 来取消分片上传。

public void abortMultipartUploads() {
    String bucket = "<your-bucket-name>";
    int sevenDays = 1000 * 60 * 60 * 24 * 7;
    Date oneWeekAgo = new Date(System.currentTimeMillis() - sevenDays);
    TransferManager transMgr = TransferManagerBuilder.standard()
        .withS3Client(s3Client)
        .build();
    //取消在一个星期前初始化并还未完成的分片上传
    transMgr.abortMultipartUploads(bucket, oneWeekAgo);
}

• 关于Content-Type的说明

Content-Type用于标识文件的资源类型，比如image/png， image/jpg 是图片类型，video/mpeg， video/mp4是视频类型，text/plain， text/html是文本类型， 浏览器针对不同的Content-Type会有不同的操作，比如图片类型可以预览，视频类型可以播放，文本类型可以直接打开。application/octet-stream类型会直接打开下载窗口。

在java sdk中，如果用户没有设置Content-Type，会根据PutObjectRequest中file参数的后缀扩展名自动生成Content-Type。

请求参数

注意：acl在PutObjectRequest中设置

初始化分片上传任务

功能说明

分片上传操作可以将超过5GB的大文件分割后上传，分片上传对象首先需要发起分片上传请求获取一个upload id。

代码示例

System.out.println("multiPartUpload");
String bucket = "<your-bucket-name>";
String key = "<your-object-key>";
InitiateMultipartUploadRequest initReq = new InitiateMultipartUploadRequest(bucket, key);
initReq.withCannedACL(CannedAccessControlList.PublicRead);
//  initReq.setStorageClass(StorageClass.Standard); // 设置对象的存储类型
InitiateMultipartUploadResult initRes = s3Client.initiateMultipartUpload(initReq);
System.out.println("multiPartUpload: init success, uploadId=" + initRes.getUploadId());

请求参数

InitiateMultipartUploadRequest 可设置的参数如下：

返回结果

InitiateMultipartUploadResult 返回的属性如下：

上传分片

功能说明

初始化分片上传任务后，指定分片上传任务的id可以上传分片数据，可以将大文件分割成分片后上传，除了最后一个分片，每个分片的数据大小为5MB~5GB，每个分片上传任务最多上传10000个分片。

代码示例

String bucket = "<your-bucket-name>";
String key = "<your-object-key>";
String uploadId = "<your-upload-id>";
​
InputStream stream1 = new ByteArrayInputStream(new byte[5*1024*1024]);
UploadPartRequest partReq1 = new UploadPartRequest();
partReq1.setBucketName(bucket);
partReq1.setKey(key);
partReq1.setUploadId(uploadId); // 在 initiateMultipartUpload 获取 
partReq1.setInputStream(stream1);
partReq1.setPartNumber(1); // 设置分片号代表这次复制是整个分片上传任务中的第几个分片，从1开始
partReq1.setObjectMetadata(new ObjectMetadata());
partReq1.setPartSize(stream1.available());
// rate 上传限速，单位KB
partReq1.putCustomRequestHeader("x-amz-limit", String.format("rate=%d", 10));
UploadPartResult partRes1 = s3Client.uploadPart(partReq1);
System.out.println("multiPartUpload: uploadPart success, etag=" + partRes1.getETag());
​
InputStream stream2 = new ByteArrayInputStream(new byte[1*1024*1024]);
UploadPartRequest partReq2 = new UploadPartRequest();
partReq2.setBucketName(bucket);
partReq2.setKey(key);
partReq2.setUploadId(uploadId);
partReq2.setInputStream(stream2);
partReq2.setPartNumber(2);
partReq2.setPartSize(stream2.available());
// rate 上传限速，单位KB
partReq2.putCustomRequestHeader("x-amz-limit", String.format("rate=%d", 10));
UploadPartResult partRes2 = s3Client.uploadPart(partReq2);
System.out.println("multiPartUpload: uploadPart success, etag=" + partRes2.getETag());

请求参数

UploadPartRequest 可设置的参数如下：

返回结果

UploadPartRequest 返回的属性如下：

合并分片

功能说明

合并指定分片上传任务id对应任务中已上传的对象分片，使之成为一个完整的文件。

代码示例

String bucket = "<your-bucket-name>";
String key = "<your-object-key>";
String uploadId = "<your-upload-id>";
PartETag tag1 = new PartETag(partReq1.getPartNumber(), partRes1.getETag()); //partNumber与eTag在上传分片时获取
PartETag tag2 = new PartETag(partReq2.getPartNumber(), partRes2.getETag());
List<PartETag> partETags = new ArrayList<>();
partETags.add(tag1);
partETags.add(tag2);
​
CompleteMultipartUploadRequest completeReq = new CompleteMultipartUploadRequest(bucket, key, uploadId, partETags);
CompleteMultipartUploadResult completeRes = s3Client.completeMultipartUpload(completeReq);
System.out.println("multiPartUpload: complete success, etag=" + completeRes.getETag());
System.out.println("bucket=" + completeRes.getBucketName());
System.out.println("key=" + completeRes.getKey());
System.out.println("location=" + completeRes.getLocation());
System.out.println("versionId=" + completeRes.getVersionId());

请求参数

CompleteMultipartUploadRequest 可设置的参数如下：

返回结果

CompleteMultipartUploadResult 返回的属性如下：

列举分片上传任务

功能说明

列举分片上传操作可以列出一个桶中正在进行的分片上传，这些分片上传的请求已经发起，但是还没完成或者被中止。listMultipartUploads 操作可以通过指定maxUploads参数来设置返回分片上传信息的数量，maxUploads参数的最大值和默认值均为1000。如果返回结果中的isTruncated字段为true，表示还有符合条件的分片上传信息没有列出，可以通过设置请求中的keyMarker和uploadIdMarker参数，来列出符合筛选条件的正在上传的分片信息。

代码示例

public void listMultipartUploads(){
    String bucket = "<your-bucket-name>";
    ListMultipartUploadsRequest listMultipartUploadsRequest = new ListMultipartUploadsRequest(bucket);
    MultipartUploadListing multipartUploadListing = s3Client.listMultipartUploads(listMultipartUploadsRequest);
    for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
        System.out.println("uploadId=" + multipartUpload.getUploadId());
        System.out.println("initiator=" + multipartUpload.getInitiator());
        System.out.println("initiated=" + multipartUpload.getInitiated());
        System.out.println("key=" + multipartUpload.getKey());
    }
}

如果list大于1000，则返回的结果中 isTruncated 为true，并返回 NextKeyMarker NextUploadIdMarker 作为下次读取的起点。如果没有一次性获取所有的分片上传事件，可以采用分页列举的方式。列举所有分片上传事件示例代码如下：

public void listMultipartUploads2(){
    String bucket = "<your-bucket-name>";
    MultipartUploadListing multipartUploadListing;
    ListMultipartUploadsRequest listMultipartUploadsRequest = new
        ListMultipartUploadsRequest(bucket);
    do {
        multipartUploadListing = s3Client.listMultipartUploads(listMultipartUploadsRequest);
        for (MultipartUpload multipartUpload : multipartUploadListing.getMultipartUploads()) {
            System.out.println("uploadId=" + multipartUpload.getUploadId());
            System.out.println("initiator=" + multipartUpload.getInitiator());
            System.out.println("initiated=" + multipartUpload.getInitiated());
            System.out.println("key=" + multipartUpload.getKey());
        }
        listMultipartUploadsRequest.setKeyMarker(multipartUploadListing.getNextKeyMarker());
        listMultipartUploadsRequest.setUploadIdMarker(multipartUploadListing.getNextUploadIdMarker());
    } while (multipartUploadListing.isTruncated());
}

请求参数

ListMultipartUploadsRequest 可设置的参数如下：

返回结果

MultipartUploadListing 返回的属性如下：

列举已上传的分片

功能说明

列举已上传分片操作可以列出一个分片上传操作中已经上传完毕但是还未合并的分片信息。请求中需要提供object key和 upload id，返回的结果最多包含1000个已上传的分片信息，默认返回1000个，可以通过设置maxParts参数的值指定返回结果中分片信息的数量。如果已上传的分片信息的数量多于1000个，则返回结果中的isTruncated字段为true，可用通过设置partNumberMarker参数获取partNumber大于该参数的分片信息。

代码示例

public void listParts() {
    System.out.println("ListParts");
    String bucket = "<your-bucket-name>";
    String key = "<your-object-key>";
    String uploadId = "<your-upload-id>";
    ListPartsRequest listParts = new ListPartsRequest(bucket, key, uploadId);
    PartListing partListing = this.s3Client.listParts(listParts);
    System.out.println("bukcet=" + partListing.getBucketName() + ", key=" + partListing.getKey() + ", uploadId="+partListing.getUploadId());
    for (PartSummary part : partListing.getParts()) {
        System.out.println("part number="+part.getPartNumber()+", size="+part.getSize());
    }
}

如果分片数大于1000，返回的 PartListing 中 isTruncated 为 true ，并可以根据 NextPartNumberMarker 为下一次请求的 list 的起始位置。

public void listParts2() {
    System.out.println("ListParts");
    String bucket = "<your-bucket-name>";
    String key = "<your-object-key>";
    String uploadId = "<your-upload-id>";
    ListPartsRequest listParts = new ListPartsRequest(bucket, key, uploadId);
    PartListing partListing;
    ListPartsRequest listPartsRequest = new ListPartsRequest(bucket, key, uploadId);
    do {
            partListing = s3Client.listParts(listPartsRequest);
            System.out.println("bukcet=" + partListing.getBucketName() + ", key=" + partListing.getKey() + ", uploadId="+partListing.getUploadId());
            for (PartSummary part : partListing.getParts()) {
                System.out.println("part number="+part.getPartNumber()+", size="+part.getSize());
            }
            listPartsRequest.setPartNumberMarker(partListing.getNextPartNumberMarker());
        } while (partListing.isTruncated());
}

请求参数

ListPartsRequest 可设置的参数如下：

返回结果

PartListing 返回的属性如下：

复制分片

功能说明

复制分片操作可以从一个已存在的对象中复制指定分片的数据。您可以使用 copyPart 复制分片。在复制分片前，需要使用 initiateMultipartUpload 接口获取一个upload id，在完成复制和上传分片操作之后，需要使用 completeMultipartUpload 操作组装分片成为一个对象。当复制的对象大小超过5GB，必须使用复制分片操作完成对象的复制。除了最后一个分片外，每个复制分片的大小范围是[5MB，5GB]。

代码示例

String destBucketName = "<your-bucket-name>";
String destObjectKey = "<your-object-key>";
String sourceBucketName = "<source-bucket-name>";
String sourceObjectKey = "<source-object-key>";
​
List<PartEtag> partEtags = new ArrayList<PartEtag>();
// 创建分片复制请求
CopyPartRequest copyRequest = new CopyPartRequest()
    //设置源桶和对象，目标桶和对象
    .withSourceBucketName(sourceBucketName)
    .withSourceKey(sourceObjectKey)
    .withDestinationBucketName(destBucketName)
    .withDestinationKey(destObjectKey)
    //uploadId为initiateMultipartUpload中返回值
    .withUploadId(initResult.getUploadId())
    //设置分片复制范围
    .withFirstByte(firstByte)
    .withLastByte(lastByte)
    //设置分片号，代表这次复制是整个分片上传任务中的第几个分片
    .withPartNumber(partNum);
​
CopyPartResult copyPartResult = s3.copyPart(copyRequest);
partETags.add(copyPartResult.getPartETag()); //把 partETag 放入 PartEtag 列表中，合并分片是需要此参数
System.out.println("multiPartCopy: copyPart success, part " + partNum + ", etag=" + copyPartResult.getETag());
System.out.println("lastModifiedDate=" + copyPartResult.getLastModifiedDate());
System.out.println("partNumber=" + copyPartResult.getPartNumber());

请求参数

copyRequest 可设置的参数如下：

返回结果

CopyPartResult 返回的属性如下：

取消分片上传任务

功能说明

取消分片上传任务操作用于终止一个分片上传。当一个分片上传被中止后，不会再有数据通过与之相应的upload id上传，同时已经被上传的分片所占用的空间会被释放。执行取消分片上传任务操作后，正在上传的分片可能会上传成功也可能会被中止，所以必要的情况下需要执行多次取消分片上传任务操作去释放全部上传成功的分片所占用的空间。可以通过执行列举已上传分片操作来确认所有中止分片上传后所有已上传分片的空间是否被被释放。

代码示例

String bucket = "<your-bucket-name>";
String key = "<your-object-key>";
String uploadId = "<your-upload-id>";
System.out.println("multiPartUpload: error=" + e.getMessage());
AbortMultipartUploadRequest abortReq = new AbortMultipartUploadRequest(bucket, key, uploadId);
s3Client.abortMultipartUpload(abortReq);

请求参数

AbortMultipartUploadRequest 可设置的参数如下：