# 创建并配置客户端(Java SDK) #### 操作场景 本章节指导客户创建并配置客户端，该任务是使用SDK与OBS交互的必备前置任务。如果您已有客户端，请跳过该节，直接参考[Java SDK接口概览(Java SDK)](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0002.html)获取接口信息。 #### 前提条件 初始化客户端之前，您需要先完成以下几项准备工作： 1. [使用前须知(Java SDK)](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0101.html)：了解并选择合适的SDK版本。 2. [使用前准备(Java SDK)](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0102.html)：完成服务环境和开发环境准备。 3. [下载与安装SDK(Java SDK)](https://support.huaweicloud.com/sdk-java-devg-obs/obs_21_0001.html)：下载SDK并完成安装。 #### 注意事项 - 客户端在创建时必须同步完成客户端配置，配置机会仅有一次，创建完成后，不能对客户端进行二次配置。 - 在使用临时AK/SK时，AK/SK会有过期时间，可调用ObsClient.refresh("yourAccessKey", "yourSecretKey", "yourSecurityToken")刷新ObsClient的AK/SK，不必重新创建ObsClient。 - 建议整个代码工程全局使用一个ObsClient客户端，只在程序初始化时创建一次，因为创建多个ObsClient客户端在高并发场景下会影响性能。 - ObsClient是线程安全的，可在并发场景下使用。 - ObsClient在调用ObsClient.close方法关闭后不能再次使用，保证全局使用一个ObsClient客户端的情况下，不建议主动关闭ObsClient客户端。 #### 配置概览 图1创建并配置客户端概览 ![](https://support.huaweicloud.com/sdk-java-devg-obs/zh-cn_image_0000001809221937.png "点击放大") 如[图]所示，请根据需要选择客户端类、选择获取访问密钥的方法，以及进行其他配置： 表1创建并配置客户端概览 | **选择项** | **可选项** | **说明** | **示例代码** | |:---|:---|:---|:---| | 客户端类 | 不透传密钥的客户端类 | 如果您只想配置一次访问凭证，不想在每一次调用OBS接口时都为客户端设置一次访问密钥，请使用普通客户端类ObsClient创建客户端。 | [ObsClient示例代码] | | 客户端类 | 透传密钥的客户端类 | 如果您需要在每次调用接口时，都为客户端设置一次访问凭证，OBS Java SDK提供了直接在接口方法中透传AK和SK的OBS客户端类SecretFlexibleObsClient，SecretFlexibleObsClient继承自ObsClient。 | [SecretFlexibleObsClient示例代码] | | 访问凭证获取方式 | 从变量传入 | 创建OBS客户端实例，并将访问凭证使用变量传入的方式。 | - [访问凭证变量直接作为参数示例代码] - [BasicObsCredentialsProvider示例代码] | | 访问凭证获取方式 | 从环境变量获取 | 创建OBS客户端实例，并使用EnvironmentVariableObsCredentialsProvider从环境变量获取访问凭证。 | [EnvironmentVariableObsCredentialsProvider示例代码] | | 访问凭证获取方式 | ECS场景从云服务委托获取 | 创建OBS客户端实例，并使用EcsObsCredentialsProvider从ECS服务器自动获取临时访问密钥，并且访问凭证会定期自动刷新。 须知： 1. 使用EcsObsCredentialsProvider的前提，应用程序须运行在ECS服务器上，并且ECS绑定了IAM对ECS的云服务委托（该委托拥有OBS权限）。 2. 请确保服务端和应用程序部署所在环境的UTC时间一致，否则可能会导致临时访问密钥无法及时刷新。 3. 使用该方式创建客户端时，SDK会请求固定IP（169.254.169.254）的API获取临时AK/SK，具体请参见[在ECS上获取Security Key](https://support.huaweicloud.com/usermanual-ecs/ecs_03_0166.html#section7)。 | [EcsObsCredentialsProvider示例代码] | | 访问凭证获取方式 | 链式获取 | 以链式的方式从预定义方式列表中搜索访问密钥，以第一组成功获取到的访问密钥创建OBS客户端。 当前顺序是默认先从环境变量，再从ECS服务器委托中进行搜索，暂不支持自定义获取方式和顺序。 | [OBSCredentialsProviderChain示例代码] | | 其他配置 | 只配置终端节点（endpoint） | 除了访问凭证外，只配置终端节点（endpoint）参数。 | [除访问凭证外只配置endpoint示例代码] | | 其他配置 | 除了配置终端节点（endpoint）还有其他配置 | 除了配置终端节点（endpoint）还需要配置HTTP代理、Socket层传输数据超时时间等参数，您可通过ObsConfiguration配置类对ObsClient进行配置，支持的配置项参见[表2]。 | [ObsConfiguration示例代码] | #### 示例代码 - **使用不透传访问凭证的客户端类，直接配置访问凭证，除访问凭证外只配置终端节点（endpoint）的示例代码** - 永久访问密钥（AK/SK）创建OBS客户端的代码如下: ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // 创建ObsClient实例 ObsClient obsClient = new ObsClient(ak, sk, endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - 临时访问密钥（AK/SK/SecurityToken）创建OBS客户端的代码如下： ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); String securityToken = System.getenv("SECURITY_TOKEN"); // 创建ObsClient实例 ObsClient obsClient = new ObsClient(ak, sk, securityToken, endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - BasicObsCredentialsProvider示例代码 ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // 创建ObsClient实例 ObsClient obsClient = new ObsClient(new BasicObsCredentialsProvider(ak, sk), endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - **透传密钥客户端类（SecretFlexibleObsClient）示例代码** ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 创建ObsConfiguration配置类实例 ObsConfiguration config = new ObsConfiguration(); config.setEndPoint(endPoint); // 创建SecretFlexibleObsClient实例 SecretFlexibleObsClient obsClient = new SecretFlexibleObsClient(config); // 使用访问OBS // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak1 = System.getenv("ACCESS_KEY_ID"); String sk1 = System.getenv("SECRET_ACCESS_KEY_ID"); obsClient.listBuckets(ak1, sk1); String ak2 = System.getenv("ACCESS_KEY_ID"); String sk2 = System.getenv("SECRET_ACCESS_KEY_ID"); obsClient.listBuckets(ak2, sk2); // 关闭obsClient obsClient.close(); ``` - **从环境变量获取访问凭证（EnvironmentVariableObsCredentialsProvider）示例代码** 使用该方法需要在环境变量中定义OBS_ACCESS_KEY_ID和OBS_SECRET_ACCESS_KEY分别代表永久的AK和SK。 ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 创建ObsClient实例 ObsClient obsClient = new ObsClient(new EnvironmentVariableObsCredentialsProvider(), endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - **ECS场景从云服务委托获取访问凭证（EcsObsCredentialsProvider）示例代码** ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 创建ObsClient实例 ObsClient obsClient = new ObsClient(new EcsObsCredentialsProvider(), endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - **链式获取访问凭证（OBSCredentialsProviderChain）示例代码** ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 创建ObsClient实例 ObsClient obsClient = new ObsClient(new OBSCredentialsProviderChain(), endPoint); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` - **使用ObsConfiguration配置参数示例代码** - 配置KeyManagerFactory，配置后可以在本地保存证书，并校验服务端返回证书是否正确。 ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); String jksPassword = "you-jks-password"; String jksPath = "/path/to/your/keystore/file"; KeyStore ks = KeyStore.getInstance("JKS"); char[] passArray = jksPassword.toCharArray(); FileInputStream inputStream = new FileInputStream(jksPath); ks.load(inputStream, passArray); KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm()); kmf.init(ks, passArray); String trustJKSPassword = "you-trustJKS-password"; String trustJKSPath = "/path/to/your/trustKeyStore/file"; KeyStore trustKeyStore = KeyStore.getInstance("JKS"); char[] trustPassArray = trustJKSPassword.toCharArray(); FileInputStream trustInputStream = new FileInputStream(trustJKSPath); trustKeyStore.load(trustInputStream, trustPassArray); TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(trustKeyStore); ObsConfiguration config = new ObsConfiguration(); config.setEndPoint(endPoint); config.setKeyManagerFactory(kmf); config.setTrustManagerFactory(tmf); ObsClient obsClient = new ObsClient(ak, sk, config); ``` ![](https://support.huaweicloud.com/sdk-java-devg-obs/public_sys-resources/note_3.0-zh-cn.png) 本地证书保存格式应为 jks 格式，可以运行以下命令调用 Java 自带的 keytool 工具将 cer 证书转换为 jks 证书。 ``` keytool -import -file your-cer-file.cer -keystore your-keystore-file.jks ``` - 配置validateCertificate，配置后使用默认信任库校验服务端返回证书是否正确。 ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); ObsConfiguration config = new ObsConfiguration(); config.setEndPoint(endPoint); config.setValidateCertificate(true); ObsClient obsClient = new ObsClient(ak, sk,config); ``` - 配置 HTTP 代理，配置后SDK 将会通过的代理访问服务端。 ``` // Endpoint以北京四为例，其他地区请按实际情况填写。 String endPoint = "https://obs.cn-north-4.myhuaweicloud.com"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // Url不要携带协议头"http://"和"https://"。 String proxyUrl = "proxy.com"; int proxyPort = 8080; String proxyUser = "userName"; String proxyPassword = "password"; ObsConfiguration config = new ObsConfiguration(); config.setEndPoint(endPoint); config.setHttpProxy(proxyUrl, proxyPort, proxyUser, proxyPassword); ObsClient obsClient = new ObsClient(ak, sk,config); ``` #### 配置自定义域名访问obs 使用自定义的域名，必须在工信部完成备案，具体配置步骤请参考：[配置自定义域名](https://support.huaweicloud.com/bestpractice-obs/obs_05_0610.html)。 ``` // 在控制台绑定成功的自定义域名。 String endPoint = "http://your-domain"; // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量ACCESS_KEY_ID和SECRET_ACCESS_KEY_ID。 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html String ak = System.getenv("ACCESS_KEY_ID"); String sk = System.getenv("SECRET_ACCESS_KEY_ID"); // 创建ObsConfiguration配置类实例 ObsConfiguration config = new ObsConfiguration(); config.setEndPoint(endPoint); config.setCname(true); // 创建ObsClient实例 ObsClient obsClient = new ObsClient(ak, sk, config); // 使用Provider创建ObsClient实例 // ObsClient obsClient = new ObsClient(new EnvironmentVariableObsCredentialsProvider(), config); // ObsClient obsClient = new ObsClient(new EcsObsCredentialsProvider(), config); // 使用访问OBS // 关闭obsClient obsClient.close(); ``` #### ObsConfiguration类支持配置的参数列表 ![](https://support.huaweicloud.com/sdk-java-devg-obs/public_sys-resources/note_3.0-zh-cn.png) - 如需提高文件上传下载性能，在网络带宽满足的情况下，可对socketWriteBufferSize，socketReadBufferSize，readBufferSize，writeBufferSize四个参数进行调优。 - 如网络状况不佳，建议增大connectionTimeout和socketTimeout的值。 表2ObsConfiguration类支持配置的参数列表 | **参数** | **描述** | **方法** | **建议值** | |:---|:---|:---|:---| | connectionTimeout | **参数解释：** 建立HTTP/HTTPS连接的超时时间。 **默认取值：** 60000，单位：毫秒。 | ObsConfiguration.setConnectionTimeout | \[10000, 60000\] | | socketTimeout | **参数解释：** Socket层传输数据的超时时间（单位：毫秒）。 **默认取值：** 60000，单位：毫秒。 | ObsConfiguration.setSocketTimeout | \[10000, 60000\] | | idleConnectionTime | **参数解释：** 如果空闲时间超过此参数的设定值，则关闭连接。为了保证您的业务顺利运行，建议不超过**29000毫秒**。 **默认取值：** 28000，单位：毫秒。 | ObsConfiguration.setIdleConnectionTime | \[0, 29000\] | | maxIdleConnections | **参数解释：** 连接池中最大空闲连接数。 **默认取值：** 1000，单位：个。 | ObsConfiguration.setMaxIdleConnections | 根据实际情况设置 | | maxConnections | **参数解释：** 最大允许的HTTP并发请求数。 **默认取值：** 1000，单位：个。 | ObsConfiguration.setMaxConnections | 默认 | | maxErrorRetry | **参数解释：** 请求失败（请求异常、服务端报500或503错误等）后最大的重试次数。 **约束限制：** 该参数对于上传对象和下载对象接口时，当上传或下载已经进入数据流处理阶段后产生异常中断，此时将不会重试。 **默认取值：** 3，单位：次。 | ObsConfiguration.setMaxErrorRetry | \[0, 5\] | | endPoint | **参数解释：** 连接OBS的服务地址。可包含协议类型、域名、端口号。示例：https://your-endpoint:443。（出于安全性考虑，建议使用https协议） **约束限制：** 出于DNS解析性能和OBS服务可靠性的考虑，**不允许将endPoint设置为IP** ，必须使用域名访问OBS服务，同时endpoint设置为IP还会导致使用path请求方式访问OBS桶，此方式已经禁止使用。（[请在这个页面搜索并查看"禁止使用path请求方式访问OBS桶"相关说明](https://support.huaweicloud.com/usermanual-obs/obs_41_0060.html)）。 **默认取值：** 无 | ObsConfiguration.setEndPoint | 根据实际情况设置 | | httpProxy | **参数解释：** HTTP代理配置。 **默认取值：** 默认为空 | ObsConfiguration.setHttpProxy | 根据实际情况设置 | | validateCertificate | **参数解释：** 是否验证服务端证书。 **取值范围：** - true：验证服务端证书。 - false：不验证服务端证书。 **默认取值：** false | ObsConfiguration.setValidateCertificate | 根据实际情况设置 | | verifyResponseContentType | **参数解释：** 是否验证响应头信息的ContentType。 **取值范围：** - true：验证响应头信息的ContentType。 - false：不验证响应头信息的ContentType。 **默认取值：** true | ObsConfiguration.setVerifyResponseContentType | 默认 | | readBufferSize | **参数解释：** 从Socket流下载对象的缓存大小，-1表示不设置缓存。 **默认取值：** -1，单位：字节。 | ObsConfiguration.setReadBufferSize | 根据实际情况设置 | | writeBufferSize | **参数解释：** 上传对象到Socket流时的缓存大小，-1表示不设置缓存。 **默认取值：** -1，单位：字节。 | ObsConfiguration.setWriteBufferSize | 根据实际情况设置 | | socketWriteBufferSize | **参数解释：** Socket发送缓冲区大小，对应java.net.SocketOptions.SO_SNDBUF参数，-1表示不设置发送缓冲区大小。 **默认取值：** 默认为-1，单位：字节。 | ObsConfiguration.setSocketWriteBufferSize | 默认 | | socketReadBufferSize | **参数解释：** Socket接收缓冲区大小，对应java.net.SocketOptions.SO_RCVBUF参数，-1表示不设置接收缓冲区大小。 **默认取值：** 默认为-1，单位：字节。 | ObsConfiguration.setSocketReadBufferSize | 默认 | | keyManagerFactory | **参数解释：** 用于生成javax.net.ssl.KeyManager的工厂。 **默认取值：** 默认为空。 | ObsConfiguration.setKeyManagerFactory | 根据实际情况设置 | | trustManagerFactory | **参数解释：** 用于生成javax.net.ssl.TrustManager的工厂。 **默认取值：** 默认为空。 | ObsConfiguration.setTrustManagerFactory | 根据实际情况设置 | | isStrictHostnameVerification | **参数解释：** 是否严格验证服务端主机名。设置为true后，需要通过javax.net.ssl.HttpsURLConnection.setDefaultHostnameVerifier去设置一个实现javax.net.ssl.HostnameVerifier接口的对象，用于验证主机名 **取值范围：** - true：严格验证服务端主机名。 - false：不严格验证服务端主机名。 **默认取值：** false | ObsConfiguration.setIsStrictHostnameVerification | 根据实际情况设置 | | keepAlive | **参数解释：** 是否使用长连接访问OBS服务。 **取值范围：** - true：使用长连接访问OBS服务。 - false：不使用长连接访问OBS服务。 **默认取值：** true | ObsConfiguration.setKeepAlive | 根据实际情况设置 | | cname | **参数解释：** 是否通过自定义域名访问OBS服务。 说明： 为了保护您的业务不受华为云公共域名被相关机构接管的影响，建议优先选择自定义域名。 **取值范围：** - true：通过自定义域名访问OBS服务。 - false：不通过自定义域名访问OBS服务。 **默认取值：** false | ObsConfiguration.setCname | 根据实际情况设置 | | sslProvider | **参数解释：** SSLContext的Provider。 **默认取值：** 使用JDK提供的SSLContext。 | ObsConfiguration.setSslProvider | 根据实际情况设置 | | httpProtocolType | **参数解释：** 访问OBS服务端时使用的HTTP协议类型。 **默认取值：** HttpProtocolTypeEnum.HTTP1_1，即http1.1 说明： 如果设置的endPoint不带协议类型，则默认使用HTTPS协议。 | ObsConfiguration.setHttpProtocolType | 根据实际情况设置 | | httpDispatcher | **参数解释：** 自定义分发器。 **默认取值：** 无 | ObsConfiguration.setHttpDispatcher | 根据实际情况设置 | | secureRandom | **参数解释：** 配置随机数生成器，支持设置为自定义的随机数生成器。 **默认取值：** 默认为 new SecureRandom() 说明： - 在某些平台上new SecureRandom()可能会使用不安全实现。出于安全考虑，建议通过ObsConfiguration.setSecureRandom()设置一个种子是真随机数的SecureRandom。 - 当操作系统没有足够的熵来生成随机数时（比如系统刚启动时），那么生成真随机数的SecureRandom可能会阻塞，直到足够的熵可用为止。建议同时通过相关措施补充熵（例如linux下的haveged），改善熵源不足时生成真随机数阻塞的问题。 | ObsConfiguration.setSecureRandom | 根据实际情况设置 |