From df45c766ebdd9b315a86db2a9db5e764bcc76df0 Mon Sep 17 00:00:00 2001 From: wb-hx510875 Date: Thu, 17 Dec 2020 17:28:10 +0800 Subject: [PATCH] chore: add docs --- README-CN.md | 22 +++++++++++++ README.md | 23 ++++++++++++++ docs/0-Examples-CN.md | 66 ++++++++++++++++++++++++++++++++++++++ docs/0-Examples-EN.md | 68 ++++++++++++++++++++++++++++++++++++++++ docs/1-Client-CN.md | 73 +++++++++++++++++++++++++++++++++++++++++++ docs/1-Client-EN.md | 72 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 324 insertions(+) create mode 100644 README-CN.md create mode 100644 README.md create mode 100644 docs/0-Examples-CN.md create mode 100644 docs/0-Examples-EN.md create mode 100644 docs/1-Client-CN.md create mode 100644 docs/1-Client-EN.md diff --git a/README-CN.md b/README-CN.md new file mode 100644 index 00000000000..814adde1f42 --- /dev/null +++ b/README-CN.md @@ -0,0 +1,22 @@ +[English](README.md) | 简体中文 +![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# Alibaba Cloud SDK + +## 使用说明 + +- [Usage for PHP](./docs/php/0-Examples-CN.md) + +## 问题 + +[Opening an Issue](https://github.com/aliyun/alibabacloud-php-sdk/issues/new)，不符合指南的问题可能会立即关闭。 + +## 相关 + +- [Latest Release](https://github.com/aliyun/alibabacloud-php-sdk) + +## 许可证 + +[Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0) + +版权所有 1999-present, 阿里巴巴集团. diff --git a/README.md b/README.md new file mode 100644 index 00000000000..03f32f2e69c --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +English | [简体中文](README-CN.md) + +![](https://aliyunsdk-pages.alicdn.com/icons/AlibabaCloud.svg) + +# Alibaba Cloud SDK + +## Usage + +- [Usage for PHP](./docs/php/0-Examples-EN.md) + +## Issues + +[Opening an Issue](https://github.com/aliyun/alibabacloud-php-sdk/issues/new), Issues not conforming to the guidelines may be closed immediately. + +## References + +- [Latest Release](https://github.com/aliyun/alibabacloud-php-sdk) + +## License + +[Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0) + +Copyright 1999-present, Alibaba Cloud All rights reserved. diff --git a/docs/0-Examples-CN.md b/docs/0-Examples-CN.md new file mode 100644 index 00000000000..e7ff9b3e666 --- /dev/null +++ b/docs/0-Examples-CN.md @@ -0,0 +1,66 @@ +[← 首页](../../README.md) | 快速使用[(English)](0-Examples-EN.md) + +*** + +## 要求 + +- 要使用 Alibaba Cloud SDK for PHP，您需要一个云账号以及一对 `Access Key ID` 和 `Access Key Secret`。 请在阿里云控制台中的[AccessKey管理页面](https://usercenter.console.aliyun.com/#/manage/ak)上创建和查看您的Access Key，或者联系您的系统管理员。 +- 要使用 Alibaba Cloud SDK for PHP 访问某个产品的API，您需要事先在[阿里云控制台](https://home.console.aliyun.com/)中开通这个产品。 +- Alibaba Cloud SDK for PHP 需要 PHP >= 5.6 以上的版本。 + +## 通过 Composer 来管理项目依赖(推荐) + +```bash +# require alibabacloud/imagesearch-20200212 for example +composer require alibabacloud/imagesearch-20200212 +``` + +# 快速使用 + +以下这个代码示例向您展示了调用 Alibaba Cloud SDK for PHP 的3个主要步骤： + +1. 创建`Config`实例并初始化。 + +2. 创建`Client`实例并初始化。 + +3. 创建`RuntimeOptions`实例并设置运行参数。 + +4. 创建 API 请求并设置参数。 + +5. 发起请求并处理应答或异常。 + +```php +namespace demo; + +require __DIR__ . '/vendor/autoload.php'; + +use AlibabaCloud\SDK\ImageSearch\V20200212\ImageSearch; +use AlibabaCloud\Tea\Rpc\Rpc\Config; +use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions; + +$config = new Config(); +$config->accessKeyId = ""; +$config->accessKeySecret = ""; +$config->regionId = "cn-shanghai"; +$config->endpoint = "imagesearch.cn-shanghai.aliyuncs.com"; +$client = new ImageSearch($config); +$request = new ImageSearch\SearchImageByNameRequest(); +$request->picName = 'test'; + +$runtime = new RuntimeOptions(); +$runtime->maxIdleConns = 3; +$runtime->connectTimeout = 10000; +$runtime->readTimeout = 10000; +try { + $response = $client->searchImageByName($request, $runtime); + var_dump($response->toMap()); +} catch (TeaUnableRetryError $e) { + var_dump($e->getMessage()); + var_dump($e->getErrorInfo()); + var_dump($e->getLastException()); + var_dump($e->getLastRequest()); +} +``` + +*** +[← 首页](../../README.md) | 快速使用[(English)](0-Examples-EN.md) diff --git a/docs/0-Examples-EN.md b/docs/0-Examples-EN.md new file mode 100644 index 00000000000..bced277b35f --- /dev/null +++ b/docs/0-Examples-EN.md @@ -0,0 +1,68 @@ +[← Home](../../README.md) | Examples[(中文)](0-Examples-CN.md) + +*** + +## Requirements + +- To use Alibaba Cloud SDK for PHP, you must have an Alibaba Cloud account as well as an `AccessKey ID` and an `AccessKey Secret`. Create and view your AccessKey on the [RAM console](https://ram.console.aliyun.com "RAM console") or contact your system administrator. +- To use the Alibaba Cloud SDK for PHP to access the APIs of a product, you must first activate the product on the [Alibaba Cloud console](https://home.console.aliyun.com) if required. +- The Alibaba Cloud PHP SDK requires PHP 5.6 or later. + +## Installation + +If you use `Composer` to manage PHP libraries + +```bash +# require alibabacloud/imagesearch-20200212 for example +composer require alibabacloud/imagesearch-20200212 +``` + +## Quick Examples + +The following code example shows the three main steps to use Alibaba Cloud SDK for PHP : + +1. Create and initialize a `Config` instance. + +2. Create and initialize a `Client` instance. + +3. Create and set up parameters `RuntimeOptions` instance. + +4. Create an API request and set parameters. + +5. Initiate the request and handle the response or exceptions. + +```php +namespace demo; + +require __DIR__ . '/vendor/autoload.php'; + +use AlibabaCloud\SDK\ImageSearch\V20200212\ImageSearch; +use AlibabaCloud\Tea\Rpc\Rpc\Config; +use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions; + +$config = new Config(); +$config->accessKeyId = ""; +$config->accessKeySecret = ""; +$config->regionId = "cn-shanghai"; +$config->endpoint = "imagesearch.cn-shanghai.aliyuncs.com"; +$client = new ImageSearch($config); +$request = new ImageSearch\SearchImageByNameRequest(); +$request->picName = 'test'; + +$runtime = new RuntimeOptions(); +$runtime->maxIdleConns = 3; +$runtime->connectTimeout = 10000; +$runtime->readTimeout = 10000; +try { + $response = $client->searchImageByName($request, $runtime); + var_dump($response->toMap()); +} catch (TeaUnableRetryError $e) { + var_dump($e->getMessage()); + var_dump($e->getErrorInfo()); + var_dump($e->getLastException()); + var_dump($e->getLastRequest()); +} +``` + +*** +[← Home](../../README.md) | Examples[(中文)](0-Examples-CN.md) diff --git a/docs/1-Client-CN.md b/docs/1-Client-CN.md new file mode 100644 index 00000000000..cef42add940 --- /dev/null +++ b/docs/1-Client-CN.md @@ -0,0 +1,73 @@ +[← Examples](0-Examples-CN.md) | 客户端与凭证[(English)](1-Client-EN.md) | [首页 →](../../README-CN.md) +*** + +### 使用 AccessKey 调用 + +```java + +use AlibabaCloud\Tea\Rpc\Rpc\Config; + +$config = new Config(); +$config->accessKeyId = ""; +$config->accessKeySecret = ""; +$client = new ImageSearch($config); + +``` + +### 使用默认凭证提供链 + +默认凭证提供程序链查找可用的凭证，寻找顺序如下： + +1. 环境凭证 + +在环境变量里寻找环境凭证，如果定义了 `ALIBABA_CLOUD_ACCESS_KEY_ID` 和 `ALIBABA_CLOUD_ACCESS_KEY_SECRET` 环境变量且不为空，程序将使用它们创建默认凭证。 + +2. 配置文件 + +如果用户主目录存在默认文件 `~/.alibabacloud/credentials` （Windows 为 `C:\Users\USER_NAME\.alibabacloud\credentials`），程序会自动创建指定类型和名称的客户端。默认文件可以不存在，但解析错误会抛出异常。 客户端名称不分大小写，若客户端同名，后者会覆盖前者。也可以手动加载指定文件： `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` 不同的项目、工具之间可以共用这个配置文件，因为超出项目之外，也不会被意外提交到版本控制。Windows 上可以使用环境变量引用到主目录 %UserProfile%。类 Unix 的系统可以使用环境变量 $HOME 或 ~ (tilde)。 可以通过定义 `ALIBABA_CLOUD_CREDENTIALS_FILE` 环境变量修改默认文件的路径。 + +```ini +[default] # 默认客户端 +enable = true # 启用，没有该选项默认启用 +type = access_key # 认证方式为 access_key +access_key_id = foo # Key +access_key_secret = bar # Secret +region_id = cn-hangzhou # 非必填，区域 +debug = true # 非必填，Debug模式会在CLI下输出详细信息 +timeout = 0.2 # 非必填，超时时间，>1为单位为秒, <1自动乘1000转为毫秒 +connect_Timeout = 0.03 # 非必填，连接超时时间，同超时时间 +cert_file = /path/server.pem # 非必填，证书文件 +cert_password = password # 非必填，证书密码，没有密码可不填 +proxy = tcp://localhost:8125 # 非必填，总代理 +proxy_http = tcp://localhost:8125 # 非必填，HTTP代理 +proxy_https = tcp://localhost:9124 # 非必填，HTTPS代理 +proxy_no = .mit.edu,foo.com # 非必填，代理忽略的域名 + +[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 +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` 且不为空，程序会将该环境变量的值作为角色名称，请求 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` 获取临时安全凭证，再创建一个默认客户端。 + +*** +[← Examples](0-Examples-CN.md) | 客户端与凭证[(English)](1-Client-EN.md) | [首页 →](../../README-CN.md) diff --git a/docs/1-Client-EN.md b/docs/1-Client-EN.md new file mode 100644 index 00000000000..826ecc8fab9 --- /dev/null +++ b/docs/1-Client-EN.md @@ -0,0 +1,72 @@ +[← Examples](0-Examples-EN.md) | Client & Credentials[(中文)](1-Client-CN.md) | [Home →](../../README.md) +*** + +### Using AccessKey call + +```java + +use AlibabaCloud\Tea\Rpc\Rpc\Config; + +$config = new Config(); +$config->accessKeyId = ""; +$config->accessKeySecret = ""; +$client = new ImageSearch($config); + +``` + +### Use the default credential provider chain + +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 will automatically create clients with the specified type and name. The default file may not exist, but a parse error throws an exception. The client name is case-insensitive, and if the clients have the same name, the latter will override the former. The specified files can also be loaded indefinitely: `AlibabaCloud::load('/data/credentials', 'vfs://AlibabaCloud/credentials', ...);` This configuration file can be shared between different projects and between different tools. Because it is outside the project and will not be accidentally committed to the version control. Environment variables can be used on Windows to refer to the home directory %UserProfile%. Unix-like systems can use the environment variable $HOME or ~ (tilde). The path to the default file can be modified by defining the `ALIBABA_CLOUD_CREDENTIALS_FILE` environment variable. + +```ini +[default] # Default client +enable = true # Enable，Enabled by default if this option not present +type = access_key # Certification type: access_key +access_key_id = foo # Key +access_key_secret = bar # Secret +region_id = cn-hangzhou # Optional，Region +debug = true # Optional，Debug mode will output the details under CLI +timeout = 0.2 # Optional，Time-out period. if >1, unit is seconds; if<1, unit will be converted to milliseconds by multiplying 1000 automatically +connect_Timeout = 0.03 # Optional，Connection timeout, same as timeout +cert_file = /path/server.pem # Optional，Certification file +cert_password = password # Optional，Certification password, can be empty if no password +proxy = tcp://localhost:8125 # Optional，General proxy +proxy_http = tcp://localhost:8125 # Optional，HTTP proxy +proxy_https = tcp://localhost:9124 # Optional，HTTPS proxy +proxy_no = .mit.edu,foo.com # Optional，Ignored Domain Name by proxy + +[client1] # Client that is named as `client1` +type = ecs_ram_role # Certification type: ecs_ram_role +role_name = EcsRamRoleTest # Role Name +#..................................# As above, other configurations ignored. + +[client2] # Client that is named as `client2` +enable = false # Disable +type = ram_role_arn # Certification type: ram_role_arn +access_key_id = foo +access_key_secret = bar +role_arn = role_arn +role_session_name = session_name +#..................................# As above, other configurations ignored. + +[client3] # Client 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 +#..................................# As above, other configurations ignored. +``` + +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 `http://100.100.100.200/latest/meta-data/ram/security-credentials/` to get the temporary Security credentials, then create a default client. + +*** +[← Examples](0-Examples-EN.md) | Client & Credentials[(中文)](1-Client-CN.md) | [Home →](../../README.md)