使用说明

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

电话咨询 - 7x24 小时

400-151-8800

邮件咨询

cloud@pingan.com

在线客服

7x24 小时,急速解答

工单支持

解决云产品相关技术问题