improve readme

aliyun · Jul 9, 2024 · c17c44d · c17c44d
1 parent 72ea521
commit c17c44d
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 43 deletions.
diff --git a/README-CN.md b/README-CN.md
@@ -1,8 +1,9 @@
 [English](./README.md) | 简体中文
 
-![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg)
+![Alibaba Cloud Logo](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg)
 
 # Alibaba Cloud Credentials for Java
+
 [![Travis Build Status](https://travis-ci.org/aliyun/credentials-java.svg?branch=master)](https://travis-ci.org/aliyun/credentials-php)
 [![codecov](https://codecov.io/gh/aliyun/credentials-java/branch/master/graph/badge.svg)](https://codecov.io/gh/aliyun/credentials-java)
 [![Latest Stable Version](https://img.shields.io/maven-central/v/com.aliyun/credentials-java.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.aliyun%22%20AND%20a:%22credentials-java%22)
@@ -12,9 +13,11 @@ Alibaba Cloud Credentials for Java 是帮助 Java 开发者管理凭据的工具
 本文将介绍如何获取和使用 Credentials for Java。
 
 ## 环境要求
-1.  Alibaba Cloud Credentials for Java 需要1.8以上的JDK。
+
+1. Alibaba Cloud Credentials for Java 需要1.8以上的JDK。
 
 ## 安装
+
 ```xml
 <dependency>
     <groupId>com.aliyun</groupId>
@@ -23,12 +26,14 @@ Alibaba Cloud Credentials for Java 是帮助 Java 开发者管理凭据的工具
 </dependency>
 ```
 
-##快速使用
+## 快速使用
+
 在您开始之前，您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。
 
 ### 凭证类型
 
 #### AccessKey
+
 通过[用户信息管理][ak]设置 access_key，它们具有该账户完全的权限，请妥善保管。有时出于安全考虑，您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用，您可以[创建RAM子账户][ram]并为子账户[授权][permissions]，使用RAM子用户的 AccessKey 来进行API调用。
 
 ```java
@@ -50,6 +55,7 @@ public class DemoTest {
 ```
 
 #### STS
+
 通过安全令牌服务（Security Token Service，简称 STS），申请临时安全凭证（Temporary Security Credentials，简称 TSC），创建临时安全凭证。
 
 ```java
@@ -73,6 +79,7 @@ public class DemoTest {
 ```
 
 #### RamRoleArn
+
 通过指定[RAM角色][RAM Role]，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。
 
 ```java
@@ -103,6 +110,7 @@ public class DemoTest {
 ```
 
 #### OIDCRoleArn
+
 通过指定[OIDC 角色][OIDC Role]，让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。
 
 ```java
@@ -137,6 +145,7 @@ public class DemoTest {
 ```
 
 #### EcsRamRole
+
 通过指定角色名称，让凭证自动申请维护 STS Token
 
 ```java
@@ -158,6 +167,7 @@ public class DemoTest {
 ```
 
 #### URLCredential
+
 通过指定提供凭证的自定义网络服务地址，让凭证自动申请维护 STS Token
 
 ```java
@@ -177,6 +187,7 @@ public class DemoTest {
 ```
 
 #### Bearer Token
+
 如呼叫中心(CCC)需用此凭证，请自行申请维护 Bearer Token。
 
 ```java
@@ -196,6 +207,7 @@ public class DemoTest {
 ```
 
 ### 使用默认凭证提供链
+
 如果你调用 `Client client = new Client()` 时， 将通过凭证提供链来为你获取凭证。
 
 默认凭证提供程序链查找可用的凭证，寻找顺序如下：
@@ -211,7 +223,7 @@ public class DemoTest {
 3.配置文件
 
 如果用户主目录存在默认文件 `~/.alibabacloud/credentials （Windows 为 C:\Users\USER_NAME\.alibabacloud\credentials）`，程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。配置名小写。不同的项目、工具之间可以共用这个配置文件，因为不在项目之内，也不会被意外提交到版本控制。
-可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。不配置则使用默认配置 `default`，也可以设置环境变量 `ALIBABA_CLOUD_PROFILE` 使用配置。 
+可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。不配置则使用默认配置 `default`，也可以设置环境变量 `ALIBABA_CLOUD_PROFILE` 使用配置。
 
 ```ini
 [default]                          # 默认配置
@@ -246,20 +258,31 @@ role_session_name = session_name   # 选填
 ```
 
 ## 问题
+
 [提交 Issue](https://github.com/aliyun/credentials-java/issues/new)，不符合指南的问题可能会立即关闭。
 
 ## 发行说明
+
 每个版本的详细更改记录在[发行说明](./ChangeLog.txt)中。
 
 ## 贡献
+
 提交 Pull Request 之前请阅读[贡献指南](./.github/PULL_REQUEST_TEMPLATE.md)。
 
 ## 相关
+
 * [阿里云服务 Regions & Endpoints](https://developer.aliyun.com/endpoints)
 * [OpenAPI 开发者门户](https://next.api.aliyun.com/)
 * [最新源码](https://github.com/aliyun/aliyun-openapi-java-sdk)
 
 ## 许可证
+
 [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
 Copyright 2009-present Alibaba Cloud All rights reserved.
+
+[ak]: https://usercenter.console.aliyun.com/#/manage/ak
+[ram]: https://ram.console.aliyun.com/users
+[permissions]: https://ram.console.aliyun.com/permissions
+[RAM Role]: https://ram.console.aliyun.com/#/role/list
+[OIDC Role]: https://help.aliyun.com/zh/ram/user-guide/role-based-sso-by-using-oidc
diff --git a/README.md b/README.md
@@ -1,8 +1,9 @@
 English | [简体中文](./README-CN.md)
 
-![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg)
+![Alibaba Cloud Logo](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg)
 
 # Alibaba Cloud Credentials for Java
+
 [![Java CI](https://github.com/aliyun/credentials-java/actions/workflows/ci.yml/badge.svg)](https://github.com/aliyun/credentials-java/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/aliyun/credentials-java/branch/master/graph/badge.svg)](https://codecov.io/gh/aliyun/credentials-java)
 [![Latest Stable Version](https://img.shields.io/maven-central/v/com.aliyun/credentials-java.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.aliyun%22%20AND%20a:%22credentials-java%22)
@@ -25,14 +26,14 @@ This document introduces how to obtain and use Credentials for Java.
 </dependency>
 ```
 
-
 ## Quick Examples
 
 Before you begin, you need to sign up for an Alibaba Cloud account and retrieve your [Credentials](https://usercenter.console.aliyun.com/#/manage/ak).
 
 ### Credential Type
 
 #### AccessKey
+
 Setup access_key credential through [User Information Management][ak], it have full authority over the account, please keep it safe. Sometimes for security reasons, you cannot hand over a primary account AccessKey with full access to the developer of a project. You may create a sub-account [RAM Sub-account][ram] , grant its [authorization][permissions]，and use the AccessKey of RAM Sub-account.
 
 ```java
@@ -54,6 +55,7 @@ public class DemoTest {
 ```
 
 #### STS
+
 Create a temporary security credential by applying Temporary Security Credentials (TSC) through the Security Token Service (STS).
 
 ```java
@@ -77,6 +79,7 @@ public class DemoTest {
 ```
 
 #### RamRoleArn
+
 By specifying [RAM Role][RAM Role], the credential will be able to automatically request maintenance of STS Token. If you want to limit the permissions([How to make a policy][policy]) of STS Token, you can assign value for `Policy`.
 
 ```java
@@ -107,6 +110,7 @@ public class DemoTest {
 ```
 
 #### OIDCRoleArn
+
 By specifying [OIDC Role][OIDC Role], the credential will be able to automatically request maintenance of STS Token. If you want to limit the permissions([How to make a policy][policy]) of STS Token, you can assign value for `Policy`.
 
 ```java
@@ -142,6 +146,7 @@ public class DemoTest {
 ```
 
 #### EcsRamRole
+
 By specifying the role name, the credential will be able to automatically request maintenance of STS Token.
 
 ```java
@@ -163,6 +168,7 @@ public class DemoTest {
 ```
 
 #### URLCredential
+
 By specifying the url, the credential will be able to automatically request maintenance of STS Token.
 
 ```java
@@ -182,6 +188,7 @@ public class DemoTest {
 ```
 
 #### Bearer Token
+
 If credential is required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself.
 
 ```java
@@ -201,69 +208,81 @@ public class DemoTest {
 ```
 
 ### Use the default credential provider chain
+
 If you call `Client client = new Client()`, it will use provider chain to get credential for you.
 
 The default credential provider chain looks for available credentials, with following order:
 
-1.System Properties
+1. System Properties
 
-Look for environment credentials in system properties. If the `alibabacloud.accessKeyId` and `alibabacloud.accessKeyIdSecret` system properties are defined and not empty, the program will use them to create default credentials.
+    Look for environment credentials in system properties. If the `alibabacloud.accessKeyId` and `alibabacloud.accessKeyIdSecret` system properties are defined and not empty, the program will use them to create default credentials.
 
-2.Environment Credentials
+2. Environment Credentials
 
-Look for environment credentials in environment variable. If the `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are defined and are not empty, the program will use them to create default credentials. If the `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` and `ALIBABA_CLOUD_SECURITY_TOKEN` environment variables are defined and are not empty, the program will use them to create temporary security credentials(STS). Note: This token has an expiration time, it is recommended to use it in a temporary environment.
+    Look for environment credentials in environment variable. If the `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variables are defined and are not empty, the program will use them to create default credentials. If the `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` and `ALIBABA_CLOUD_SECURITY_TOKEN` environment variables are defined and are not empty, the program will use them to create temporary security credentials(STS). Note: This token has an expiration time, it is recommended to use it in a temporary environment.
 
-3.Credentials File
+3. Credentials File
 
-If there is `~/.alibabacloud/credentials default file (Windows shows C:\Users\USER_NAME\.alibabacloud\credentials)`, the program automatically creates credentials with the specified type and name. The default file is not necessarily exist, but a parse error will throw an exception. The name of configuration item is lowercase.This configuration file can be shared between different projects and between different tools. Because it is outside of the project and will not be accidentally committed to the version control. The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable. If not configured, use the default configuration `default`. You can also set the environment variables `ALIBABA_CLOUD_PROFILE` to use the configuration.
+    If there is `~/.alibabacloud/credentials default file (Windows shows C:\Users\USER_NAME\.alibabacloud\credentials)`, the program automatically creates credentials with the specified type and name. The default file is not necessarily exist, but a parse error will throw an exception. The name of configuration item is lowercase.This configuration file can be shared between different projects and between different tools. Because it is outside of the project and will not be accidentally committed to the version control. The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable. If not configured, use the default configuration `default`. You can also set the environment variables `ALIBABA_CLOUD_PROFILE` to use the configuration.
 
-```ini
-[default]                          # default setting
-enable = true                      # Enable，Enabled by default if this option is not present
-type = access_key                  # Certification type: access_key
-access_key_id = foo                # Key
-access_key_secret = bar            # Secret
+    ```ini
+    [default]                          # default setting
+    enable = true                      # Enable，Enabled by default if this option is not present
+    type = access_key                  # Certification type: access_key
+    access_key_id = foo                # Key
+    access_key_secret = bar            # Secret
 
-[client1]                          # configuration that is named as `client1`
-type = ecs_ram_role                # Certification type: ecs_ram_role
-role_name = EcsRamRoleTest         # Role Name
+    [client1]                          # configuration that is named as `client1`
+    type = ecs_ram_role                # Certification type: ecs_ram_role
+    role_name = EcsRamRoleTest         # Role Name
 
-[client2]                          # configuration that is named as `client2`
-enable = false                     # Disable
-type = ram_role_arn                # Certification type: ram_role_arn
-region_id = cn-test                 
-policy = test                      # optional Specify permissions
-access_key_id = foo                
-access_key_secret = bar            
-role_arn = role_arn                # can be replaced by setting environment variable: ALIBABA_CLOUD_ROLE_ARN
-role_session_name = session_name   # optional
+    [client2]                          # configuration that is named as `client2`
+    enable = false                     # Disable
+    type = ram_role_arn                # Certification type: ram_role_arn
+    region_id = cn-test                 
+    policy = test                      # optional Specify permissions
+    access_key_id = foo                
+    access_key_secret = bar            
+    role_arn = role_arn                # can be replaced by setting environment variable: ALIBABA_CLOUD_ROLE_ARN
+    role_session_name = session_name   # optional
 
-[client3]                          # configuration that is named as `client3`
-enable = false                     # Disable
-type = oidc_role_arn               # Certification type: oidc_role_arn
-region_id = cn-test                 
-policy = test                      # optional Specify permissions
-role_arn = role_arn                # can be replaced by setting environment variable: ALIBABA_CLOUD_ROLE_ARN
-oidc_provider_arn = oidc_provider_arn # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_PROVIDER_ARN
-oidc_token_file_path = /xxx/xxx    # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_TOKEN_FILE              
-role_session_name = session_name   # optional
-```
+    [client3]                          # configuration that is named as `client3`
+    enable = false                     # Disable
+    type = oidc_role_arn               # Certification type: oidc_role_arn
+    region_id = cn-test                 
+    policy = test                      # optional Specify permissions
+    role_arn = role_arn                # can be replaced by setting environment variable: ALIBABA_CLOUD_ROLE_ARN
+    oidc_provider_arn = oidc_provider_arn # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_PROVIDER_ARN
+    oidc_token_file_path = /xxx/xxx    # can be replaced by setting environment variable: ALIBABA_CLOUD_OIDC_TOKEN_FILE              
+    role_session_name = session_name   # optional
+    ```
 
 ## Issues
+
 [Opening an Issue](https://github.com/aliyun/credentials-java/issues/new), Issues not conforming to the guidelines may be closed immediately.
 
 ## Changelog
+
 Detailed changes for each release are documented in the [release notes](./ChangeLog.txt).
 
 ## Contribution
+
 Please make sure to read the [Contributing Guide](./.github/PULL_REQUEST_TEMPLATE.md) before making a pull request.
 
 ## References
-* [Alibaba Cloud Regions & Endpoints](https://developer.aliyun.com/endpoints)
-* [OpenAPI Developer Portal](https://next.api.aliyun.com/)
-* [Latest Release](https://github.com/aliyun/aliyun-openapi-java-sdk)
+
+- [OpenAPI Developer Portal](https://api.aliyun.com/)
+- [Troubleshoot](https://api.aliyun.com/troubleshoot)
 
 ## License
+
 [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
 Copyright 2009-present Alibaba Cloud All rights reserved.
+
+[ak]: https://usercenter.console.aliyun.com/#/manage/ak
+[ram]: https://ram.console.aliyun.com/users
+[permissions]: https://ram.console.aliyun.com/permissions
+[RAM Role]: https://ram.console.aliyun.com/#/role/list
+[OIDC Role]: https://help.aliyun.com/zh/ram/user-guide/role-based-sso-by-using-oidc
+[policy]: https://help.aliyun.com/zh/ram/user-guide/policy-management/