From cca301d15cac5cf6854a22d8ff8ab873db761be0 Mon Sep 17 00:00:00 2001 From: 824750130 Date: Fri, 7 Aug 2020 09:34:43 +0800 Subject: [PATCH] Improve document. --- README-CN.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+) diff --git a/README-CN.md b/README-CN.md index 13bda0f..2ae4b7a 100644 --- a/README-CN.md +++ b/README-CN.md @@ -161,6 +161,69 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` +### 使用默认凭证提供链 + +```python +from alibabacloud_credentials.client import Client as CredClient +from alibabacloud_ocr20191230.client import Client as OcrClient +from alibabacloud_ocr20191230.models import GetAsyncJobResultRequest +from alibabacloud_tea_rpc.models import Config +from alibabacloud_tea_util.models import RuntimeOptions + +cred = CredClient() +config = Config(credential=cred) + +client = OcrClient(config) + +request = GetAsyncJobResultRequest( + job_id='' +) + +runtime_options = RuntimeOptions() +response = client.get_async_job_result(request, runtime_options) +``` + +默认凭证提供程序链查找可用的凭证，寻找顺序如下： + +1.环境凭证 + +在环境变量里寻找环境凭证，如果定义了 `ALIBABA_CLOUD_ACCESS_KEY_ID` 和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET` 环境变量且不为空，程序将使用它们创建默认凭证。 + +2.配置文件 + +如果用户主目录存在默认文件 `~/.alibabacloud/credentials （Windows 为 C:\Users\USER_NAME\.alibabacloud\credentials）`，程序会自动创建指定类型和名称的凭证。默认文件可以不存在，但解析错误会抛出异常。配置名小写。不同的项目、工具之间可以共用这个配置文件，因为不在项目之内，也不会被意外提交到版本控制。 +可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。不配置则使用默认配置 `default`，也可以设置环境变量 `ALIBABA_CLOUD_PROFILE` 使用配置。 + +```ini +[default] # 默认配置 +enable = true # 启用，没有该选项默认不启用 +type = access_key # 认证方式为 access_key +access_key_id = foo # Key +access_key_secret = bar # Secret + +[client1] # 命名为 `client1` 的配置 +type = ecs_ram_role # 认证方式为 ecs_ram_role +role_name = EcsRamRoleTest # Role Name + +[client2] # 命名为 `client2` 的配置 +enable = false # 不启用 +type = ram_role_arn # 认证方式为 ram_role_arn +region_id = cn-test # 获取session用的region +policy = test # 选填 指定权限 +access_key_id = foo +access_key_secret = bar +role_arn = role_arn +role_session_name = session_name # 选填 + +[client3] # 命名为 `client3` 的配置 +type = rsa_key_pair # 认证方式为 rsa_key_pair +public_key_id = publicKeyId # Public Key ID +private_key_file = /your/pk.pem # Private Key 文件 +``` + +3.实例 RAM 角色 + +如果定义了环境变量 `ALIBABA_CLOUD_ECS_METADATA` 且不为空，程序会将该环境变量的值作为角色名称，请求 获取临时安全凭证。 ## 问题 diff --git a/README.md b/README.md index 9f00534..7c13f13 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,68 @@ security_token = cred.get_security_token() cred_type = cred.get_type() ``` +### Use the default credential provider chain + +```python +from alibabacloud_credentials.client import Client as CredClient +from alibabacloud_ocr20191230.client import Client as OcrClient +from alibabacloud_ocr20191230.models import GetAsyncJobResultRequest +from alibabacloud_tea_rpc.models import Config +from alibabacloud_tea_util.models import RuntimeOptions + +cred = CredClient() +config = Config(credential=cred) + +client = OcrClient(config) + +request = GetAsyncJobResultRequest( + job_id='' +) + +runtime_options = RuntimeOptions() +response = client.get_async_job_result(request, runtime_options) +``` + +The default credential provider chain looks for available credentials, with following order: + +1.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. + +2.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. + +```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 + +[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 +role_session_name = session_name # optional + +[client3] # configuration that is named as `client3` +type = rsa_key_pair # Certification type: rsa_key_pair +public_key_id = publicKeyId # Public Key ID +private_key_file = /your/pk.pem # Private Key file +``` + +3.Instance RAM Role + +If the environment variable `ALIBABA_CLOUD_ECS_METADATA` is defined and not empty, the program will take the value of the environment variable as the role name and request to get the temporary Security credentials. ## Issues