初始化 - 对象存储 OSS

新建OSSClient

新建OSSClient时，需要指定Endpoint。有关Endpoint的更多信息，请参见访问域名和数据中心和自定义访问域名。

• 使用OSS域名新建OSSClient

  以下代码用于使用OSS域名新建OSSClient：

  // Endpoint以杭州为例，其它Region请按实际情况填写。
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
  
  // 关闭OSSClient。
  ossClient.shutdown();                    

  您的工程中可以有一个或多个OSSClient。OSSClient可以并发使用。

• 使用自定义域名新建OSSClient

  以下代码用于使用自定义域名新建OSSClient：

  String endpoint = "<yourEndpoint>";
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // 创建ClientConfiguration实例，您可以按照实际情况修改默认参数。
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  // 设置是否支持CNAME。CNAME用于将自定义域名绑定到目标Bucket。
  conf.setSupportCname(true);
  
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
  
  // 关闭OSSClient。
  ossClient.shutdown();                    

  说明 使用自定义域名时无法使用ossClient.listBuckets方法。
• 专有云或专有域环境新建OSSClient

  以下代码用于使用专有云或专有域环境新建OSSClient：

  // Endpoint以杭州为例，其它Region请按实际情况填写。
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // 创建ClientConfiguration实例，按照您的需要修改默认参数。
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  // 关闭CNAME选项。
  conf.setSupportCname(false);
  
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
  
  // 关闭OSSClient。
  ossClient.shutdown();                    

• 使用IP新建OSSClient

  以下代码用于使用IP新建OSSClient：

  // 某些特殊情况（比如专有域）下，您需要将IP地址作为Endpoint，请按照实际IP地址填写。
  String endpoint = "https://10.10.10.10";
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  
  // 创建ClientConfiguration。
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  // 开启二级域名访问OSS，默认不开启。OSS Java SDK 2.1.2及之前的版本需要设置此值，OSS Java SDK 2.1.2及之后以后的版本会自动检测到IP地址，不需要再设置此值。
  conf.setSLDEnabled(true);
  
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);
  
  // 关闭OSSClient。
  ossClient.shutdown();                    

• 使用STS新建OSSClient

  以下代码用于使用STS新建OSSClient：

  // Endpoint以杭州为例，其它Region请按实际情况填写。
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  String securityToken = "<yourSecurityToken>";
  
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);
  
  // 关闭OSSClient。
  ossClient.shutdown();                    

  更多信息，请参见授权访问。

• 使用STSAssumeRole新建OSSClient

  以下代码用于使用STSAssumeRole新建OSSClient：

  // 授权STSAssumeRole访问的Region。以杭州为例，其它Region请按实际情况填写。
  String region = "cn-hangzhou";
  // 填写RAM用户的访问密钥（AccessKeyId和AccessKeySecret）。
  String accessKeyId = "<yourAccessKeyId>";
  String accessKeySecret = "<yourAccessKeySecret>";
  // 角色的ARN，即需要扮演的角色ID。
  String roleArn = "<yourRoleArn>";   
  // 创建STSAssumeRoleSessionCredentialsProvider实例。
  STSAssumeRoleSessionCredentialsProvider provider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider(
  region, accessKeyId, accessKeySecret, roleArn);
  
  // 通过STSAssumeRole访问OSS的Endpoint。以杭州为例，其它endpoint请按实际情况填写。
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";  
  // 创建ClientConfiguration实例。
  ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
  
   
  // 创建OSSClient实例。
  OSS ossClient = new OSSClientBuilder().build(endpoint, provider, conf);
  
  // 关闭OSSClient。
  ossClient.shutdown();

  更多信息，请参见STS临时授权访问OSS。

• 使用EcsRamRole新建OSSClient

  在云服务器ECS上，您可以通过实例RAM角色的方式访问OSS。实例RAM角色允许您将一个角色关联到云服务器实例，在实例内部基于临时凭证STS访问OSS。临时凭证由系统自动生成和更新，应用程序可以使用指定的实例元数据URL获取临时凭证，无需特别管理。

  以下代码用于使用EcsRamRole新建OSSClient：

  // 通过ECS RAM角色访问OSS。
  // 以杭州为例，其它endpoint请按实际情况填写。
  String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";     
  
  // 通过ECS RAM角色获取访问凭证，例如以角色名（ecs-ram-role）访问为例。
  InstanceProfileCredentialsProvider provider = CredentialsProviderFactory.newInstanceProfileCredentialsProvider("ecs-ram-role");
  
  // 创建OSSClient实例。
   OSS ossClient = new OSSClientBuilder().build(endpoint, provider, new ClientBuilderConfiguration());
  
  // 关闭OSSClient。
  ossClient.shutdown(); 

配置OSSClient

ClientConfiguration是OSSClient的配置类，您可通过此类来配置代理、连接超时、最大连接数等参数。可设置的参数如下：

以下代码用于使用ClientConfiguration设置OSSClient参数：

// Endpoint以杭州为例，其它Region请按实际情况填写。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
String accessKeyId = "<yourAccessKeyId>";
String accessKeySecret = "<yourAccessKeySecret>";

// 创建ClientConfiguration。ClientConfiguration是OSSClient的配置类，可配置代理、连接超时、最大连接数等参数。
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();

// 设置OSSClient允许打开的最大HTTP连接数，默认为1024个。
conf.setMaxConnections(200);
// 设置Socket层传输数据的超时时间，默认为50000毫秒。
conf.setSocketTimeout(10000);
// 设置建立连接的超时时间，默认为50000毫秒。
conf.setConnectionTimeout(10000);
// 设置从连接池中获取连接的超时时间（单位：毫秒），默认不超时。
conf.setConnectionRequestTimeout(1000);
// 设置连接空闲超时时间。超时则关闭连接，默认为60000毫秒。
conf.setIdleConnectionTime(10000);
// 设置失败请求重试次数，默认为3次。
conf.setMaxErrorRetry(5);
// 设置是否支持将自定义域名作为Endpoint，默认支持。
conf.setSupportCname(true);
// 设置是否开启二级域名的访问方式，默认不开启。
conf.setSLDEnabled(true);
// 设置连接OSS所使用的协议（HTTP或HTTPS），默认为HTTP。
conf.setProtocol(Protocol.HTTP);
// 设置用户代理，指HTTP的User-Agent头，默认为aliyun-sdk-java。
conf.setUserAgent("aliyun-sdk-java");
// 设置代理服务器端口。
conf.setProxyHost("<yourProxyHost>");
// 设置代理服务器验证的用户名。
conf.setProxyUsername("<yourProxyUserName>");
// 设置代理服务器验证的密码。
conf.setProxyPassword("<yourProxyPassword>");
// 设置是否开启HTTP重定向，默认开启。
conf.setRedirectEnable(true);
// 设置是否开启SSL证书校验，默认开启。
conf.setVerifySSLEnable(true);

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, conf);

// 关闭OSSClient。
ossClient.shutdown();
            

更多信息，请参见阿里云OSS Java SDK超时时间设置。