OSSClient是OSS的Java客户端,用于管理存储空间和文件等OSS资源。使用Java SDK发起OSS请求,您需要初始化一个OSSClient实例,并根据需要修改ClientConfiguration的默认配置项。

新建OSSClient

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

  • 使用OSS域名新建OSSClient

    以下代码用于使用OSS域名新建OSSClient。一个工程中可以有一个或多个OSSClient,OSSClient支持并发使用。

    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    String endpoint = "yourEndpoint";
    // 阿里云账号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。

    // yourEndpoint填写自定义域名。
    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。

    // yourEndpoint填写Bucket所在地域对应的Endpoint。
    String endpoint = "yourEndpoint";
    // 阿里云账号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。

    说明 关于搭建STS服务的具体操作,请参见开发指南中的使用STS临时访问凭证访问OSS。您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。临时访问凭证包括临时访问密钥(AccessKeyId和AccessKeySecret)和安全令牌(SecurityToken)。临时访问凭证有效时间单位为秒,最小值为900,最大值以当前角色设定的最大会话时间为准。更多信息,请参见设置角色最大会话时间
    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    String endpoint = "yourEndpoint";
    // 从STS服务获取的临时访问密钥(AccessKey ID和AccessKey Secret)。
    String accessKeyId = "yourAccessKeyId";
    String accessKeySecret = "yourAccessKeySecret";
    // 从STS服务获取的安全令牌(SecurityToken)。
    String securityToken = "yourSecurityToken";
    
    // 创建OSSClient实例。
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);
    
    // 关闭OSSClient。
    ossClient.shutdown();                    

    更多信息,请参见授权访问

  • 使用STSAssumeRole新建OSSClient

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

    // 授权STSAssumeRole访问的Region。以华东1(杭州)为例,其它Region请根据实际情况填写。
    String region = "cn-hangzhou";
    // 填写RAM用户的访问密钥(AccessKeyId和AccessKeySecret)。
    String accessKeyId = "yourAccessKeyId";
    String accessKeySecret = "yourAccessKeySecret";
    // 填写角色的ARN信息,即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。
    // $accountID为阿里云账号ID。您可以通过登录阿里云控制台,将鼠标悬停在右上角头像的位置,直接查看和复制账号ID,或者单击基本资料查看账号ID。
    // $roleName为RAM角色名称。您可以通过登录RAM控制台,单击左侧导航栏的RAM角色管理,在RAM角色名称列表下进行查看。
    String roleArn = "acs:ram::17464958********:role/ossststest";   
    // 创建STSAssumeRoleSessionCredentialsProvider实例。
    STSAssumeRoleSessionCredentialsProvider provider = CredentialsProviderFactory.newSTSAssumeRoleSessionCredentialsProvider(
    region, accessKeyId, accessKeySecret, roleArn);
    // yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    String endpoint = "yourEndpoint";
    // 创建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