Object Storage Service：Java禁止覆蓋同名檔案

注意事項

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

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

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

簡單上傳

以下代碼用於簡單上傳時禁止覆蓋同名檔案：

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.*;
import java.io.ByteArrayInputStream;

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的完整路徑。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/object";
        String content = "Hello OSS!";
        // 填寫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 {
            // 建立PutObjectRequest對象。
            PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));

            // 指定上傳檔案操作時是否覆蓋同名Object。
            // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setHeader("x-oss-forbid-overwrite", "true");
            putObjectRequest.setMetadata(metadata);

            // 上傳檔案。
            ossClient.putObject(putObjectRequest);
        } 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();
            }
        }
    }
}

拷貝檔案

• 通過CopyObjectRequest拷貝

  以下代碼用於通過CopyObjectRequest拷貝小檔案時禁止覆蓋同名檔案：

  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名稱。
          String sourceBucketName = "srcexamplebucket";
          // 填寫源Object的完整路徑，完整路徑中不能包含Bucket名稱。
          String sourceObjectName = "srcexampleobject.txt";
          // 填寫與源Bucket處於同一地區的目標Bucket名稱。
          String destinationBucketName = "desexamplebucket";
          // 填寫目標Object的完整路徑。Object完整路徑中不能包含Bucket名稱。
          String destinationObjectName = "desexampleobject.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 {
              // 建立CopyObjectRequest對象。
              CopyObjectRequest copyObjectRequest = new CopyObjectRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
  
              // 設定新的檔案中繼資料。
              ObjectMetadata metadata = new ObjectMetadata();
              metadata.setContentType("text/html");
              // 指定拷貝檔案操作時是否覆蓋同名Object。
              // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object
              // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
              // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
              metadata.setHeader("x-oss-forbid-overwrite", "true");
              copyObjectRequest.setNewObjectMetadata(metadata);
  
              // 拷貝檔案。
              CopyObjectResult result = ossClient.copyObject(copyObjectRequest);
              System.out.println("ETag: " + result.getETag() + " LastModified: " + result.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();
              }
          }
      }
  }

• 拷貝大檔案

  以下代碼用於拷貝大檔案（分區拷貝）時禁止覆蓋同名檔案：

  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.*;
  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名稱。
          String sourceBucketName = "srcexamplebucket";
          // 填寫源Object的完整路徑，完整路徑中不能包含Bucket名稱。
          String sourceObjectName = "srcexampleobject.txt";
          // 填寫與源Bucket處於同一地區的目標Bucket名稱。
          String destinationBucketName = "desexamplebucket";
          // 填寫目標Object的完整路徑。Object完整路徑中不能包含Bucket名稱。
          String destinationObjectName = "desexampleobject.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 {
              ObjectMetadata objectMetadata = ossClient.getObjectMetadata(sourceBucketName, sourceObjectName);
              // 擷取被拷貝檔案的大小。
              long contentLength = objectMetadata.getContentLength();
  
              // 設定分區大小為10MB。
              long partSize = 1024 * 1024 * 10;
  
              // 計算分區總數。
              int partCount = (int) (contentLength / partSize);
              if (contentLength % partSize != 0) {
                  partCount++;
              }
              System.out.println("total part count:" + partCount);
  
              // 初始化拷貝任務。可以通過InitiateMultipartUploadRequest指定目標檔案中繼資料。
              InitiateMultipartUploadRequest initiateMultipartUploadRequest = new InitiateMultipartUploadRequest(destinationBucketName, destinationObjectName);
              // 指定拷貝檔案操作時是否覆蓋同名Object。
              // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object。
              // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
              // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
              ObjectMetadata metadata = new ObjectMetadata();
              metadata.setHeader("x-oss-forbid-overwrite", "true");
              initiateMultipartUploadRequest.setObjectMetadata(metadata);
  
              InitiateMultipartUploadResult initiateMultipartUploadResult = ossClient.initiateMultipartUpload(initiateMultipartUploadRequest);
              String uploadId = initiateMultipartUploadResult.getUploadId();
  
              // 分區拷貝。
              List<PartETag> partETags = new ArrayList<PartETag>();
              for (int i = 0; i < partCount; i++) {
                  // 計算每個分區的大小。
                  long skipBytes = partSize * i;
                  long size = partSize < contentLength - skipBytes ? partSize : contentLength - skipBytes;
  
                  // 建立UploadPartCopyRequest。可以通過UploadPartCopyRequest指定限定條件。
                  UploadPartCopyRequest uploadPartCopyRequest =
                          new UploadPartCopyRequest(sourceBucketName, sourceObjectName, destinationBucketName, destinationObjectName);
                  uploadPartCopyRequest.setUploadId(uploadId);
                  uploadPartCopyRequest.setPartSize(size);
                  uploadPartCopyRequest.setBeginIndex(skipBytes);
                  uploadPartCopyRequest.setPartNumber(i + 1);
                  UploadPartCopyResult uploadPartCopyResult = ossClient.uploadPartCopy(uploadPartCopyRequest);
  
                  // 將返回的分區ETag儲存到partETags中。
                  partETags.add(uploadPartCopyResult.getPartETag());
              }
  
              // 完成分區拷貝任務。
              CompleteMultipartUploadRequest completeMultipartUploadRequest = new CompleteMultipartUploadRequest(
                      destinationBucketName, destinationObjectName, uploadId, partETags);
  
              // 指定拷貝檔案操作時是否覆蓋同名Object。
              // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object
              // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
              // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
              completeMultipartUploadRequest.addHeader("x-oss-forbid-overwrite", "true");
  
              ossClient.completeMultipartUpload(completeMultipartUploadRequest);
          } 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.*;
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的完整路徑。Object完整路徑中不能包含Bucket名稱。
        String objectName = "exampledir/object";
        // 填寫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);

            // 指定分區上傳操作時是否覆蓋同名Object。
            // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
            ObjectMetadata metadata = new ObjectMetadata();
            metadata.setHeader("x-oss-forbid-overwrite", "true");
            request.setObjectMetadata(metadata);

            // 初始化分區。
            InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
            // 返回uploadId，它是分區上傳事件的唯一標識，您可以根據這個ID來發起相關的操作，如取消分區上傳、查詢分區上傳等。
            String uploadId = upresult.getUploadId();

            // partETags是PartETag的集合。PartETag由分區的ETag和分區號組成。
            List<PartETag> partETags =  new ArrayList<PartETag>();
            // 計算檔案有多少個分區。
            final long partSize = 1 * 1024 * 1024L;   // 1MB
            final File sampleFile = new File("<localFile>");
            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;
                InputStream instream = new FileInputStream(sampleFile);
                // 跳過已經上傳的分區。
                instream.skip(startPos);
                UploadPartRequest uploadPartRequest = new UploadPartRequest();
                uploadPartRequest.setBucketName(bucketName);
                uploadPartRequest.setKey(objectName);
                uploadPartRequest.setUploadId(uploadId);
                uploadPartRequest.setInputStream(instream);
                // 設定分區大小。除了最後一個分區沒有大小限制，其他的分區最小為100KB。
                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());
            }


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

            // 指定分區上傳操作時是否覆蓋同名Object。
            // 不指定x-oss-forbid-overwrite時，預設覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為false時，表示允許覆蓋同名Object。
            // 指定x-oss-forbid-overwrite為true時，表示禁止覆蓋同名Object，如果同名Object已存在，程式將報錯。
            completeMultipartUploadRequest.addHeader("x-oss-forbid-overwrite", "true");

            // 完成上傳。
            CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
        } 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介面說明，請參見PutObject。

• 關於拷貝檔案的API介面說明，請參見CopyObject。

• 關於分區上傳的API介面說明，請參見InitiateMultipartUpload以及CompleteMultipartUpload。