平安云 - 云以致用智造未来

使用说明

平安云提供的所有API接口支持HTTP或者HTTPS请求，允许GET和POST两种请求方法，部分接口不允许GET请求。 API URL请求需要使用AccessKey进行签名及URL编码。   1. 请求结构 平安云支持基于URL发起的HTTP/HTTPS GET请求，请求参数需要包含在URL中，以下为“ListRegions”（查询地域列表接口）为例： <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> https://api.yun.pingan.com/api/v1?Action=ListRegions &Id= Region-QTLzvswQFr &<公共请求参数> </td> </tr> </tbody> </table> <ul> <li>https: 指定了请求通信协议。</li> <li>api.yun.pingan.com: 接口的接入网关（Endpoint）。</li> <li>/api/v1: 代表API服务的版本为v1。</li> <li>Action=ListRegions: 指定了要调用的具体API。</li> <li>Id=Region-QTLzvswQFr: 是ListRegions接口的业务请求参数。</li> <li><公共请求参数>：是平安云约定的公共参数，与实际业务无关。</li> </ul> （1）通信协议 支持HTTP或HTTPS协议请求通信。为了获得更高的安全性，推荐您使用HTTPS协议发送请求。 涉及敏感数据时，如用户密码和SSH密钥对，推荐使用HTTPS协议。例如，在Login中指定Password参数时。 （2）接入网关 当前访问需要接入平安云中国大陆的API服务时，请使用： <table border="1" cellpadding="0" cellspacing="0" style="width:319px"> <tbody> <tr> <td style="vertical-align:top; width:130px"> 地址（部署位置） </td> <td style="vertical-align:top; width:183px"> 接入地址 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 平安云（公有云） </td> <td style="vertical-align:top; width:183px"> https://api.yun.pingan.com </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 平安云（政务云） </td> <td style="vertical-align:top; width:183px"> https://api.city.pingan.com </td> </tr> </tbody> </table> （3）请求参数 平安云提供命令模式和RESTful两种模式的API接口，其中命令模式的API接口主要是IaaS类产品和部分PaaS类产品，而RESTful接口主要是SaaS类产品和部分PaaS类产品。 1）命令模式 通过Action参数指定目标操作，例如Action=RunInstance。还需要指定接口的其他参数以及公共请求参数，例如： https://api.yun.pingan.com/api/v1?Action=RunInstance&<公共请求参数> 2）RESTful模式 在RESTful风格的API接口中，每个URL代表一种资源（resource），所以url中不能有动词，只能有名词，例如： GET  https://api.yun.pingan.com/rest/v1/payment/{tenantId}/balance 查询租户余额。 对于资源的具体操作类型，由HTTP动词表示，常用的HTTP动词有下面四个： <ul> <li>GET（SELECT）：从服务器取出资源（一项或多项）。</li> <li>POST（CREATE）：在服务器新建一个资源。</li> <li>PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。</li> <li>DELETE（DELETE）：从服务器删除资源。</li> </ul> （4）字符编码 平安云API约定请求及返回结果都使用UTF-8字符集编码。   2. 公共参数 （1）公共请求参数 <table border="1" cellpadding="0" cellspacing="0" style="width:606px"> <tbody> <tr> <td style="width:126px"> 参数名称 </td> <td style="width:101px"> 参数类型 </td> <td style="width:79px"> 是否必须 </td> <td style="width:132px"> 参数描述 </td> <td style="width:156px"> 格式/备注 </td> </tr> <tr> <td style="width:126px"> accessKeyId </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> Access Key Id </td> <td style="width:156px">   </td> </tr> <tr> <td style="width:126px"> signatureMethod </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> 签名方法 </td> <td style="width:156px"> HMAC-SHA1 </td> </tr> <tr> <td style="width:126px"> signatureNonce </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> 请求随机数 </td> <td style="width:156px">   </td> </tr> <tr> <td style="width:126px"> signatureVersion </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> 签名版本 </td> <td style="width:156px"> 1.0 </td> </tr> <tr> <td style="width:126px"> timestamp </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> 请求时间戳 </td> <td style="width:156px">   </td> </tr> <tr> <td style="width:126px"> version </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> Api版本 </td> <td style="width:156px"> 2017-01-01 </td> </tr> <tr> <td style="width:126px"> signature </td> <td style="width:101px"> String </td> <td style="width:79px"> true </td> <td style="width:132px"> 请求签名 </td> <td style="width:156px">   </td> </tr> </tbody> </table> （2）公共返回参数 <table border="1" cellpadding="0" cellspacing="0" style="width:607px"> <tbody> <tr> <td style="width:124px"> 参数名称 </td> <td style="width:99px"> 参数类型 </td> <td style="width:139px"> 参数描述 </td> <td style="width:235px"> 格式/备注 </td> </tr> <tr> <td style="width:124px"> requestId </td> <td style="width:99px"> String </td> <td style="width:139px"> 请求Id </td> <td style="width:235px"> Trace ID, 每一次请求会产生新的ID </td> </tr> <tr> <td style="width:124px"> code </td> <td style="width:99px"> String </td> <td style="width:139px"> 请求结果状态 </td> <td style="width:235px"> HTTP状态 </td> </tr> <tr> <td style="width:124px"> message </td> <td style="width:99px"> String </td> <td style="width:139px"> 请求结果国际化描述 </td> <td style="width:235px"> 国际化之后的消息 </td> </tr> <tr> <td style="width:124px"> resultCode </td> <td style="width:99px"> String </td> <td style="width:139px"> 请求结果状态码 </td> <td style="width:235px"> A00000~Z99999 </td> </tr> </tbody> </table>   3. 签名机制 （1）签名机制简介 通过AccessKey的方式访问后台接口，主要是通过签名校验的方式，鉴定用户请求的url是否在传输过程中被篡改过，若签名校验通过，则认为请求没有被篡改过，后台会将请求转发到具体的服务。若签名校验失败，则被认为由于一些原因，导致当前请求是不安全的，例如用户请求的url被篡改过，用户请求过期等，后台将拒绝提供服务。在云门户注册主用户或创建子用户后，可以为每个用户生成一对AccessKey，AccessKey由AccessKeyId与AccessKeySecret组成。通过AccessKeyId，可以在后台查出唯一对应的用户的详细信息；AccessKeySecret则作为秘钥，用于对请求进行签名。AccessKeySecret需要用户严格保密，来防止被盗用后用于冒充用户进行签名。 目前，使用签名校验的方式访问后台接口，请求的url参数由以下几个部分组成： <table border="1" cellpadding="0" cellspacing="0" style="width:273px"> <tbody> <tr> <td style="vertical-align:top"> 参数名称 </td> <td style="vertical-align:top; width:159px"> 参数是否参与计算签名 </td> </tr> <tr> <td style="vertical-align:top"> accessKeyId </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> signature </td> <td style="vertical-align:top; width:159px"> 否 </td> </tr> <tr> <td style="vertical-align:top"> signatureMethod </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> signatureNonce </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> signatureVersion </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> timestamp </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> version </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> <tr> <td style="vertical-align:top"> 具体业务接口参数 </td> <td style="vertical-align:top; width:159px"> 是 </td> </tr> </tbody> </table> （2）签名生成过程 以查询地域ListZones接口为例，调用该接口，需要传入的业务参数为action=ListZones，regionId=Region-southChina。 必传的其他参数如公共请求参数部分所述，包括： accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA， signatureMethod=HMAC-SHA1， signatureNonce=3378010751426913252， signatureVersion=1.0， timestamp= 1534159280463， version=2017-01-01 以上参数是需要参与计算签名的请求参数。 1）首先要对这些参数，根据参数名称按照字母序进行排序，得到的请求参数为：accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA&action=ListZones&regionId=Region-southChina&signatureMethod=HMAC-SHA1&signatureNonce=3378010751426913252&signatureVersion=1.0&timestamp=1534159280463&version=2017-01-01。 2）然后对请求参数，利用HmacSHA1算法进行签名计算，计算签名需要使用AccessKeySecret，用户的AccessKeySecret是存储在客户端的，因此用户可以自行设置，利用AccessKeySecret和其他签名过程中必须的参数，可以计算得到最终的签名signature的值。通常，我们会通过SDK等方式，在用户端集成或提供生成签名或生成请求url的便捷方法。 3）客户端利用签名和其他请求参数，生成请求url，开始请求服务端。   4. 访问验证 请求进入后端服务时，后台会根据请求的url，进入不同的认证逻辑。使用签名的方式访问后端服务，后端将会进入到校验签名的逻辑。 后端接到请求时，会获取到所有的请求参数，以下仅为示例，后端获取的请求参数可能是无序的： accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA action=ListZones regionId=Region-southChina signatureMethod=HMAC-SHA1 signatureNonce=3378010751426913252 signatureVersion=1.0 timestamp=1534159280463 version=2017-01-01&signature （1）首先后端会取出所有请求参数和请求参数值，但会将signature参数排除，然后对排除signanture参数的其他参数，按照参数名称，以字母序进行排序。 （2）后端会根据AccessKeyId，在数据库中查找到AccessKeySecret，然后利用AccessKeySecret，对已经进行过排序的请求参数，进行签名的计算 （3）后端得到签名计算结果后，与请求传入的签名结果进行比较，若签名结果一致，则认为请求合法，将请求转发到具体服务，否则拒绝服务。 签名校验过程中，将依次对下面几个条件进行单独校验（见下表），任何一个环节校验失败，请求都将不会被执行，只有所有校验项都校验通过后，本次请求才被认为是一次合法请求。 <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top; width:130px"> 校验项 </td> <td style="vertical-align:top; width:770px"> 解释 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 重复提交 </td> <td style="vertical-align:top; width:770px"> AccessKey的请求方式，每个签名只能使用一次，每次请求都会生成新的签名，因此当一个签名已经被使用过一次时，15分钟内相同签名的请求会被提示重复提交 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> API版本错误 </td> <td style="vertical-align:top; width:770px"> 目前固定取值2017-01-01 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 签名版本错误 </td> <td style="vertical-align:top; width:770px"> 目前固定取值1.0 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 签名时效性 </td> <td style="vertical-align:top; width:770px"> 生成的签名必须在15分钟内完成请求，15分钟后签名会失效 </td> </tr> <tr> <td style="vertical-align:top; width:130px"> 签名一致性 </td> <td style="vertical-align:top; width:770px"> 请求中传入的签名和后端服务计算出来的签名必须一致，否则认为请求是不安全的 </td> </tr> </tbody> </table>   5. 返回结果 平安云API接口返回结果主要是JSON 格式。更多详情，请参阅公共参数。为了便于查看和美观，API 文档返回示例均有换行和缩进等处理，实际返回结果无换行和缩进处理。

以上内容是否解决了您的问题？是否