diff --git a/docs/0-Usage-CN.md b/docs/0-Usage-CN.md new file mode 100644 index 000000000..37f9b9801 --- /dev/null +++ b/docs/0-Usage-CN.md @@ -0,0 +1,125 @@ +[← 首页](../../README-CN.md) | 快速使用[(English)](0-Usage-EN.md) | [客户端与凭证 →](1-Client-CN.md) + +![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# Python SDK 使用说明 + +## 要求 + +- Python >= 3.6 + +## 安装 + +你可以使用 `pip` 来安装你的依赖。 + +```sh +$ pip install alibabacloud-imagesearch20200212 +``` + +## 快速使用 + +在您开始之前,您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。 +SDK 使用 [credentials](https://github.com/aliyun/credentials-python/blob/master/README-CN.md) 来管理凭证。 + +## 使用示例 + +```python +from alibabacloud_imagesearch20200212.client import Client +from alibabacloud_imagesearch20200212.models import SearchImageByPicAdvanceRequest +from alibabacloud_oss_util.models import RuntimeOptions +from alibabacloud_tea_rpc.models import Config + +'''图像搜索示例''' + + +with open('pic.jpg', 'rb') as f: + # 初始化Request + request = SearchImageByPicAdvanceRequest( + instance_name='name', + pic_content_object=f + ) + + # 初始化Config + config = Config( + access_key_id='', + access_key_secret='', + endpoint='', + region_id='cn-shanghai', + type='access_key' + ) + + # 初始化RuntimeObject + runtime_option = RuntimeOptions() + + # 初始化Client + client = Client(config) + + # 调用api + response = client.search_image_by_pic_advance(request, runtime_option) + +print(response) +print('request id:', response.request_id) +print('code:', response.code) +print('message:', response.msg) + +# head +print('docs return:', response.head.docs_return) +print('docs found:', response.head.docs_found) +print('search time:', response.head.search_time) + +# pic info +print('category id:', response.pic_info.category_id) +print('region:', response.pic_info.region) +print('all categories:', response.pic_info.all_categories) + +# Auctions +for aut in response.auctions: + print('category id:', aut.category_id) + print('product id:', aut.product_id) + +``` + +## 参数说明 + +```python +'''Config''' +class Config(TeaModel): + def __init__(self): + self.access_key_id = access_key_id # access key id + self.access_key_secret = access_key_secret # access key secret + self.security_token = security_token # Security Token + self.protocol = protocol # 请求协议 http|https + self.region_id = region_id # 区域id + self.read_timeout = read_timeout # 读超时 + self.connect_timeout = connect_timeout # 连接超时 + self.http_proxy = http_proxy # http代理 + self.https_proxy = https_proxy # https代理 + self.endpoint = endpoint # endpoint + self.no_proxy = no_proxy # 代理白名单 + self.max_idle_conns = max_idle_conns # 最大连接数 + self.user_agent = user_agent # User-Agent + self.socks_5proxy = socks_5proxy # socks5代理 + self.socks_5net_work = socks_5net_work # socks5代理协议 + self.endpoint_type = endpoint_type # 域名类型:internal,accelerate 或不填 + self.open_platform_endpoint = open_platform_endpoint # 文件上传时授权使用的域名(目前暂不需要填写) + self.type = type # 凭证类型,如有疑问请参考https://github.com/aliyun/credentials-python/blob/master/README-CN.md + + +'''RuntimeOptions''' +class RuntimeOptions(TeaModel): + def __init__(self): + self.autoretry = autoretry # 是否开启重试 + self.ignore_ssl = ignore_ssl # 是否忽略 SSL 校验 + self.max_attempts = max_attempts # 最大重试次数, 默认为 3 + self.backoff_policy = backoff_policy # 重试休眠策略,默认为 no + self.backoff_period = backoff_period # 重试休眠时间, 默认为 1 + self.read_timeout = read_timeout # 读超时 + self.connect_timeout = connect_timeout # 连接超时 + self.local_addr = local_addr # 本地网卡 ip + self.http_proxy = http_proxy # http 的代理 + self.https_proxy = https_proxy # https 的代理 + self.no_proxy = no_proxy # 代理白名单 + self.max_idle_conns = max_idle_conns # 最大连接数 + self.socks_5proxy = socks_5proxy # socks5 代理 + self.socks_5net_work = socks_5net_work # socks5 代理协议 +``` diff --git a/docs/0-Usage-EN.md b/docs/0-Usage-EN.md new file mode 100644 index 000000000..d42ed9f14 --- /dev/null +++ b/docs/0-Usage-EN.md @@ -0,0 +1,122 @@ +[← Home](../../README.md) | Usage[(中文)](0-Usage-CN.md) | [Client & Credentials →](1-Client-EN.md) + +![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# Python SDK instructions + +## Requirements + +- Python >= 3.6 + +## Installation + +If you use `pip` to install your dependence + +```sh +$ pip install alibabacloud-imagesearch20200212 +``` + +## 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). + +## Demo + +```python +from alibabacloud_imagesearch20200212.client import Client +from alibabacloud_imagesearch20200212.models import SearchImageByPicAdvanceRequest +from alibabacloud_oss_util.models import RuntimeOptions +from alibabacloud_tea_rpc.models import Config + +'''ImageSearch Example''' + +with open('pic.jpg', 'rb') as f: + # init Request + request = SearchImageByPicAdvanceRequest( + instance_name='name', + pic_content_object=f + ) + + # init Config + config = Config( + access_key_id='', + access_key_secret='', + endpoint='', + region_id='cn-shanghai', + type='access_key' + ) + + # init RuntimeObject + runtime_option = RuntimeOptions() + + # init Client + client = Client(config) + + # call api + response = client.search_image_by_pic_advance(request, runtime_option) + +print(response) +print('request id:', response.request_id) +print('code:', response.code) +print('message:', response.msg) + +# head +print('docs return:', response.head.docs_return) +print('docs found:', response.head.docs_found) +print('search time:', response.head.search_time) + +# pic info +print('category id:', response.pic_info.category_id) +print('region:', response.pic_info.region) +print('all categories:', response.pic_info.all_categories) + +# Auctions +for aut in response.auctions: + print('category id:', aut.category_id) + print('product id:', aut.product_id) +``` + +## Parameter Specification + +```python +'''Config''' +class Config(TeaModel): + def __init__(self): + self.access_key_id = access_key_id # access key id + self.access_key_secret = access_key_secret # access key secret + self.security_token = security_token # Security Token + self.protocol = protocol # http|https + self.region_id = region_id # region id + self.read_timeout = read_timeout # read timeout + self.connect_timeout = connect_timeout # connect timeout + self.http_proxy = http_proxy # http proxy + self.https_proxy = https_proxy # https proxy + self.endpoint = endpoint # endpoint + self.no_proxy = no_proxy # agent whitelist + self.max_idle_conns = max_idle_conns # maximum number of connections + self.user_agent = user_agent # User-Agent + self.socks_5proxy = socks_5proxy # socks5 proxy + self.socks_5net_work = socks_5net_work # ocks5 agency agreement + self.endpoint_type = endpoint_type # ednpoint type:internal,accelerate or null + self.open_platform_endpoint = open_platform_endpoint # endpoint used when the file is uploaded(Not at the moment) + self.type = type # credential type,If you have any questions, please refer to it https://github.com/aliyun/credentials-python/blob/master/README-CN.md + + +'''RuntimeOptions''' +class RuntimeOptions(TeaModel): + def __init__(self): + self.autoretry = autoretry # whether to enable retry + self.ignore_ssl = ignore_ssl # whether SSL validation is ignored + self.max_attempts = max_attempts # maximum number of retries + self.backoff_policy = backoff_policy # retry the sleep strategy + self.backoff_period = backoff_period # retry the sleep time + self.read_timeout = read_timeout # read timeout + self.connect_timeout = connect_timeout # connect timeout + self.local_addr = local_addr # the local network adapter ip + self.http_proxy = http_proxy # http proxy + self.https_proxy = https_proxy # httpsproxy + self.no_proxy = no_proxy # agent whitelist + self.max_idle_conns = max_idle_conns # maximum number of connections + self.socks_5proxy = socks_5proxy # socks5 proxy + self.socks_5net_work = socks_5net_work # socks5 proxy +``` \ No newline at end of file diff --git a/docs/1-Client-CN.md b/docs/1-Client-CN.md new file mode 100644 index 000000000..d852a028f --- /dev/null +++ b/docs/1-Client-CN.md @@ -0,0 +1,231 @@ +[← Usage](0-Usage-CN.md) | 客户端与凭证[(English)](1-Client-EN.md) | [首页 →](../../README-CN.md) + +![Alternate text](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# 客户端与凭证 + +## 使用说明 + +在您开始之前,您需要注册阿里云帐户并获取您的[凭证](https://usercenter.console.aliyun.com/#/manage/ak)。 + +### 使用 AccessKey 调用 + +```python +from alibabacloud_ocr20191230.client import Client +from alibabacloud_ocr20191230.models import GetAsyncJobResultRequest +from alibabacloud_tea_rpc.models import Config +from alibabacloud_tea_util.models import RuntimeOptions + +config = Config( + access_key_id='', + access_key_secret='' +) + +# 实例化Client +client = Client(config) + +request = GetAsyncJobResultRequest( + job_id='' +) + +runtime_options = RuntimeOptions() +response = client.get_async_job_result(request, runtime_options) + +print(response.to_map()) + +``` + +### 使用凭证 + +#### access_key + +通过[用户信息管理](https://usercenter.console.aliyun.com/#/manage/ak)设置 access_key,它们具有该账户完全的权限,请妥善保管。有时出于安全考虑,您不能把具有完全访问权限的主账户 AccessKey 交于一个项目的开发者使用,您可以[创建RAM子账户](https://ram.console.aliyun.com/users)并为子账户[授权](https://ram.console.aliyun.com/permissions),使用RAM子用户的 AccessKey 来进行API调用。 + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='access_key', # 凭证类型 + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +cred_type = cred.get_type() +``` + +#### sts + +通过安全令牌服务(Security Token Service,简称 STS),申请临时安全凭证(Temporary Security Credentials,简称 TSC),创建临时安全凭证。 + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='sts', # 凭证类型 + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret + security_token='securityToken' # STS Token +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### Ram_role_arn + +通过指定[RAM角色](https://ram.console.aliyun.com/#/role/list),让凭证自动申请维护 STS Token。你可以通过为 `Policy` 赋值来限制获取到的 STS Token 的权限。 + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='ram_role_arn', # 凭证类型 + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret + security_token='securityToken', # STS Token + role_arn='roleArn', # 格式: acs:ram::用户ID:role/角色名 + role_session_name='roleSessionName', # 角色会话名称 + policy='policy', # 可选, 限制 STS Token 的权限 + role_session_expiration=3600 # 可选, 限制 STS Token 的有效时间 +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### ecs_ram_role + +通过指定角色名称,让凭证自动申请维护 STS Token + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='ecs_ram_role', # 凭证类型 + role_name='roleName' # 账户RoleName,非必填,不填则自动获取,建议设置,可以减少请求 +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### Ras_key_pair + +通过指定公钥ID和私钥文件,让凭证自动申请维护 AccessKey。仅支持日本站。 + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='rsa_key_pair', # 凭证类型 + private_key_file='privateKeyFile', # PrivateKey文件路径 + public_key_id='publicKeyId' # 账户PublicKeyId +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### bearer + +如呼叫中心(CCC)需用此凭证,请自行申请维护 Bearer Token。 + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='bearer', # 凭证类型 + bearer_token='bearerToken', # BearerToken +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +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/docs/1-Client-EN.md b/docs/1-Client-EN.md new file mode 100644 index 000000000..8134092c4 --- /dev/null +++ b/docs/1-Client-EN.md @@ -0,0 +1,232 @@ +[← Usage](0-Usage-EN.md) | Client & Credentials[(中文)](1-Client-CN.md) | [Home →](../../README.md) + +![Alternate text](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# Client & Credentials + +## Usage + +Before you begin, you need to sign up for an Alibaba Cloud account and retrieve your [Credentials](https://usercenter.console.aliyun.com/#/manage/ak). + +### Using AccessKey call + +```python + +from alibabacloud_ocr20191230.client import Client +from alibabacloud_ocr20191230.models import GetAsyncJobResultRequest +from alibabacloud_tea_rpc.models import Config +from alibabacloud_tea_util.models import RuntimeOptions + +config = Config( + access_key_id='', + access_key_secret='' +) + +# create and initialize a Client instance +client = Client(config) + +request = GetAsyncJobResultRequest( + job_id='' +) + +runtime_options = RuntimeOptions() +response = client.get_async_job_result(request, runtime_options) + +print(response.to_map()) + + +``` + +### Credential Type + +#### access_key + +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. + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='access_key', # credential type + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +cred_type = cred.get_type() +``` + +#### sts + +Create a temporary security credential by applying Temporary Security Credentials (TSC) through the Security Token Service (STS). + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='sts', # credential type + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret + security_token='securityToken' # STS Token +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### ram_role_arn + +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`. + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='ram_role_arn', # credential type + access_key_id='accessKeyId', # AccessKeyId + access_key_secret='accessKeySecret', # AccessKeySecret + security_token='securityToken', # STS Token + role_arn='roleArn', # Format: acs:ram::USER_ID:role/ROLE_NAME + role_session_name='roleSessionName', # Role Session Name + policy='policy', # Not required, limit the permissions of STS Token + role_session_expiration=3600 # Not required, limit the Valid time of STS Token +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### ecs_ram_role + +By specifying the role name, the credential will be able to automatically request maintenance of STS Token. + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='ecs_ram_role', # credential type + role_name='roleName' # `roleName` is optional. It will be retrieved automatically if not set. It is highly recommended to set it up to reduce requests. +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### rsa_key_pair + +By specifying the public key ID and the private key file, the credential will be able to automatically request maintenance of the AccessKey before sending the request. Only Japan station is supported. + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='rsa_key_pair', # credential type + private_key_file='privateKeyFile', # The file path to store the PrivateKey + public_key_id='publicKeyId' # PublicKeyId of your account +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +security_token = cred.get_security_token() +cred_type = cred.get_type() +``` + +#### bearer + +If credential is required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself. + +```python +from alibabacloud_credentials.client import Client +from alibabacloud_credentials.models import Config + +config = Config( + type='bearer', # credential type + bearer_token='bearerToken', # BearerToken +) +cred = Client(config) + +access_key_id = cred.get_access_key_id() +access_key_secret = cred.get_access_key_secret() +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.