注意事項(xiàng)

• 本文以華東1（杭州）外網(wǎng)Endpoint為例。如果您希望通過與OSS同地域的其他阿里云產(chǎn)品訪問OSS，請(qǐng)使用內(nèi)網(wǎng)Endpoint。關(guān)于OSS支持的Region與Endpoint的對(duì)應(yīng)關(guān)系，請(qǐng)參見OSS訪問域名、數(shù)據(jù)中心、開放端口。

• 本文以從環(huán)境變量讀取訪問憑證為例。如何配置訪問憑證，請(qǐng)參見Java配置訪問憑證。

• 本文以OSS域名新建OSSClient為例。如果您希望通過自定義域名、STS等方式新建OSSClient，請(qǐng)參見新建OSSClient。

MD5校驗(yàn)

如果上傳文件時(shí)設(shè)置了Content-MD5，OSS會(huì)根據(jù)接收的內(nèi)容計(jì)算MD5。OSS計(jì)算的MD5值和上傳提供的MD5值不一致時(shí)，則返回InvalidDigest異常，從而保證數(shù)據(jù)的完整性。返回InvalidDigest異常后，您需要重新上傳文件。

分片上傳也支持MD5校驗(yàn)。在分片上傳MultipartUpload請(qǐng)求中，meta是對(duì)于文件的設(shè)置，其中分片上傳實(shí)現(xiàn)MD5的校驗(yàn)是在每個(gè)分片中實(shí)現(xiàn)的。主要是調(diào)用UploadPartRequest中的setMd5Digest，用以設(shè)置客戶端計(jì)算該分片的本地MD5。

• 上傳文件時(shí)進(jìn)行MD5校驗(yàn)：

  import com.aliyun.oss.*;
  import com.aliyun.oss.common.auth.*;
  import com.aliyun.oss.common.utils.BinaryUtil;
  import com.aliyun.oss.model.ObjectMetadata;
  import java.io.ByteArrayInputStream;
  
  public class Demo {
      public static void main(String[] args) throws Throwable {
          // Endpoint以華東1（杭州）為例，其它Region請(qǐng)按實(shí)際情況填寫。
          String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
          // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量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";
  
          // 創(chuàng)建OSSClient實(shí)例。
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
  
          try {
              // 上傳字符串。
              String content = "Hello OSS";
  
              ObjectMetadata meta = new ObjectMetadata();
              // 設(shè)置MD5校驗(yàn)。
              String md5 = BinaryUtil.toBase64String(BinaryUtil.calculateMd5(content.getBytes()));
              meta.setContentMD5(md5);
  
              ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()), meta);
  
          } 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();
              }
          }
      }
  }            

• 分片上傳文件時(shí)進(jìn)行MD5校驗(yàn)：

  import java.io.File;
  import java.io.FileInputStream;
  import java.io.InputStream;
  import java.util.ArrayList;
  import java.util.List;
  import com.aliyun.oss.OSS;
  import com.aliyun.oss.OSSClientBuilder;
  import com.aliyun.oss.common.auth.CredentialsProviderFactory;
  import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
  import com.aliyun.oss.common.utils.BinaryUtil;
  import com.aliyun.oss.model.CompleteMultipartUploadRequest;
  import com.aliyun.oss.model.CompleteMultipartUploadResult;
  import com.aliyun.oss.model.InitiateMultipartUploadRequest;
  import com.aliyun.oss.model.InitiateMultipartUploadResult;
  import com.aliyun.oss.model.PartETag;
  import com.aliyun.oss.model.UploadPartRequest;
  import com.aliyun.oss.model.UploadPartResult;
  
  public class Demo {
      public static void main(String[] args) throws Exception {
          // Endpoint以華東1（杭州）為例，其它Region請(qǐng)按實(shí)際情況填寫。
          String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
          // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量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 localFile = "D:\\localpath\\examplefile.txt";
          // 填寫Bucket所在地域。以華東1（杭州）為例，Region填寫為cn-hangzhou。
          String region = "cn-hangzhou";
  
          // 創(chuàng)建OSSClient實(shí)例。
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
          // 創(chuàng)建InitiateMultipartUploadRequest對(duì)象。
          InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, objectName);
          // 如果需要在初始化分片時(shí)設(shè)置文件存儲(chǔ)類型，請(qǐng)參考以下示例代碼
          // ObjectMetadata metadata = new ObjectMetadata();
          // metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
          // request.setObjectMetadata(metadata);
          // 初始化分片。
          InitiateMultipartUploadResult upresult = ossClient.initiateMultipartUpload(request);
          // 返回uploadId，它是分片上傳事件的唯一標(biāo)識(shí)，您可以根據(jù)這個(gè)uploadId發(fā)起相關(guān)的操作，如取消分片上傳、查詢分片上傳等。
          String uploadId = upresult.getUploadId();
          // partETags是PartETag的集合。PartETag由分片的ETag和分片號(hào)組成。
          List<PartETag> partETags = new ArrayList<PartETag>();
          // 計(jì)算文件有多少個(gè)分片。
          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);
              InputStream instream1 = new FileInputStream(sampleFile);
           // 跳過已經(jīng)上傳的分片。
              instream.skip(startPos);
              instream1.skip(startPos);
              String md5;
              if(i==partCount-1){
           // 注意最后一個(gè)分片讀取的是到文件尾部的數(shù)據(jù)，非一個(gè)分片的大小
                  md5 = md5(instream1,fileLength - startPos);
              }else{
                  md5 = md5(instream1,partSize);
              }
            // instream1.skip(n)
              UploadPartRequest uploadPartRequest = new UploadPartRequest();
              uploadPartRequest.setBucketName(bucketName);
              uploadPartRequest.setKey(objectName);
              uploadPartRequest.setUploadId(uploadId);
              uploadPartRequest.setInputStream(instream);
              uploadPartRequest.setMd5Digest(md5);
           // 設(shè)置分片大小。除了最后一個(gè)分片沒有大小限制，其他的分片最小為100 KB。
              uploadPartRequest.setPartSize(curPartSize);
           // 設(shè)置分片號(hào)。每一個(gè)上傳的分片都有一個(gè)分片號(hào)，取值范圍是1~10000，如果超出這個(gè)范圍，OSS將返回InvalidArgument的錯(cuò)誤碼。
              uploadPartRequest.setPartNumber( i + 1);
           // 每個(gè)分片不需要按順序上傳，甚至可以在不同客戶端上傳，OSS會(huì)按照分片號(hào)排序組成完整的文件。
              UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
           // System.out.println("server md5" +uploadPartResult.getETag());
           // 每次上傳分片之后，OSS的返回結(jié)果包含PartETag。PartETag將被保存在partETags中。
              partETags.add(uploadPartResult.getPartETag());
          }
          // 創(chuàng)建CompleteMultipartUploadRequest對(duì)象。
          // 在執(zhí)行完成分片上傳操作時(shí)，需要提供所有有效的partETags。OSS收到提交的partETags后，會(huì)逐一驗(yàn)證每個(gè)分片的有效性。當(dāng)所有的數(shù)據(jù)分片驗(yàn)證通過后，OSS將把這些分片組合成一個(gè)完整的文件。
          CompleteMultipartUploadRequest completeMultipartUploadRequest =
                  new CompleteMultipartUploadRequest(bucketName, objectName, uploadId, partETags);
          // 如果需要在完成文件上傳的同時(shí)設(shè)置文件訪問權(quán)限，請(qǐng)參考以下示例代碼。
          // completeMultipartUploadRequest.setObjectACL(CannedAccessControlList.PublicRead);
          // 完成上傳。
          CompleteMultipartUploadResult completeMultipartUploadResult = ossClient.completeMultipartUpload(completeMultipartUploadRequest);
          // 關(guān)閉OSSClient。
          ossClient.shutdown();
      }
      public static String md5(InputStream in , long length1) throws Exception{
          byte[] bytes = new byte[(int) length1];
          long length_tmp = length1;
          int readSize = in.read(bytes, (int) 0, (int) length_tmp);
          return BinaryUtil.toBase64String(BinaryUtil.calculateMd5(bytes));
      }
  }

CRC64校驗(yàn)

上傳、下載和拷貝文件時(shí)默認(rèn)開啟CRC數(shù)據(jù)校驗(yàn)，以確保數(shù)據(jù)的完整性。

• 下載文件時(shí)CRC64校驗(yàn)

  以下代碼用于下載文件時(shí)進(jìn)行CRC64數(shù)據(jù)完整性校驗(yàn)：

  import com.aliyun.oss.*;
  import com.aliyun.oss.common.auth.*;
  import com.aliyun.oss.common.utils.IOUtils;
  import com.aliyun.oss.internal.OSSHeaders;
  import com.aliyun.oss.internal.OSSUtils;
  import com.aliyun.oss.model.GetObjectRequest;
  import com.aliyun.oss.model.OSSObject;
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  
  public class Demo {
      public static void main(String[] args) throws Throwable {
          // Endpoint以華東1（杭州）為例，其它Region請(qǐng)按實(shí)際情況填寫。
          String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
          // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量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";
  
          // 創(chuàng)建OSSClient實(shí)例。
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
  
          try {
              // 流式下載。
              GetObjectRequest getObjectRequest = new GetObjectRequest(bucketName, objectName);
              OSSObject ossObject = ossClient.getObject(bucketName, objectName);
  
              // 讀取文件內(nèi)容，只有讀取文件內(nèi)容之后才能獲取clientCrc。
              System.out.println("Object content:");
              BufferedReader reader = new BufferedReader(new InputStreamReader(ossObject.getObjectContent()));
              while (true) {
                  String line = reader.readLine();
                  if (line == null) break;
  
                  System.out.println("\n" + line);
              }
              // 數(shù)據(jù)讀取完成后，獲取的流必須關(guān)閉，否則會(huì)造成連接泄漏，導(dǎo)致請(qǐng)求無連接可用，程序無法正常工作。
              reader.close();
  
              // 查看客戶端是否開啟了CRC校驗(yàn)，默認(rèn)是開啟狀態(tài)。
              Boolean isCrcCheckEnabled = ((OSSClient)ossClient).getClientConfiguration().isCrcCheckEnabled();
              // 查看是否是范圍下載請(qǐng)求。范圍下載方式不支持CRC校驗(yàn)。
              Boolean isRangGetRequest = getObjectRequest.getHeaders().get(OSSHeaders.RANGE) != null;
  
              // 校驗(yàn)CRC，且只有讀取文件內(nèi)容之后才能獲取clientCRC。
              if (isCrcCheckEnabled && !isRangGetRequest) {
                  Long clientCRC = IOUtils.getCRCValue(ossObject.getObjectContent());
                  OSSUtils.checkChecksum(clientCRC, ossObject.getServerCRC(), ossObject.getRequestId());
              }
          } 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();
              }
          }
      }
  }

• 追加上傳時(shí)CRC64校驗(yàn)

  以下代碼用于追加上傳時(shí)進(jìn)行CRC64數(shù)據(jù)完整性校驗(yàn)：

  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請(qǐng)按實(shí)際情況填寫。
          String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
          // 從環(huán)境變量中獲取訪問憑證。運(yùn)行本代碼示例之前，請(qǐng)確保已設(shè)置環(huán)境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
          EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
          // 填寫Bucket名稱，例如examplebucket。
          String bucketName = "examplebucket";
          // 填寫Object完整路徑，例如exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
          String objectName = "exampleobject.txt";
          // 填寫第一次追加內(nèi)容，例如Hello。
          String firstAppendContent = "Hello";
          // 填寫第二次追加內(nèi)容，例如World。
          String secondAppendContent = "World";        
          // 填寫Bucket所在地域。以華東1（杭州）為例，Region填寫為cn-hangzhou。
          String region = "cn-hangzhou";
  
          // 創(chuàng)建OSSClient實(shí)例。
          ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
          clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
          OSS ossClient = OSSClientBuilder.create()
          .endpoint(endpoint)
          .credentialsProvider(credentialsProvider)
          .clientConfiguration(clientBuilderConfiguration)
          .region(region)               
          .build();
  
          try {
              // 第一次追加。
              AppendObjectRequest appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(firstAppendContent.getBytes()));
              appendObjectRequest.setPosition(0L);
              // 初始化CRC。初始化CRC之后，SDK內(nèi)部默認(rèn)會(huì)對(duì)上傳結(jié)果進(jìn)行CRC校驗(yàn)。
              appendObjectRequest.setInitCRC(0L);
              AppendObjectResult appendObjectResult = ossClient.appendObject(appendObjectRequest);
  
              // 第二次追加。
              appendObjectRequest = new AppendObjectRequest(bucketName, objectName, new ByteArrayInputStream(secondAppendContent.getBytes()));
              appendObjectRequest.setPosition(appendObjectResult.getNextPosition());
              // 初始化CRC設(shè)置為已上傳數(shù)據(jù)的CRC。初始化CRC之后，SDK內(nèi)部默認(rèn)會(huì)對(duì)上傳結(jié)果進(jìn)行CRC校驗(yàn)。
              appendObjectRequest.setInitCRC(appendObjectResult.getClientCRC());
              ossClient.appendObject(appendObjectRequest);
          } 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();
              }
          }
      }
  }

相關(guān)文檔

關(guān)于數(shù)據(jù)校驗(yàn)的完整示例代碼，請(qǐng)參見GitHub示例。