平安云|Ping An Cloud- Building Your Smart Future

USE_Instructions

All API interfaces provided by Ping An Cloud support HTTP or HTTPS request, allowing both GET and POST request methods, but some interfaces do not permit GET request.   API URL request needs to use AccessKey to sign and encode a URL.   1. Request Structure Ping An Cloud supports URL-based HTTP/HTTPS GET request, and request parameters should be included in a URL. Take “ListRegions” for an example:  <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td style="vertical-align:top"> <a href="https://api.yun.pingan.com/api/v1?Action=ListRegions">https://api.yun.pingan.com/api/v1?Action=ListRegions</a> &Id= Region-QTLzvswQFr &<Common Request Parameter> </td> </tr> </tbody> </table> <ul> <li>https: refers to the request communication protocol.</li> <li>api.yun.pingan.com: refers to the end point of an interface.</li> <li>/api/v1: refers to that the version of API service is v1.</li> <li>Action=ListRegions: refers to the specific API to be called.</li> <li>Id=Region-QTLzvswQFr: refers to the business request parameter of the ListRegions;</li> <li><Common Request Parameter>: refers to the common parameter agreed by Ping An Cloud, having nothing to do with actual business.</li> </ul> （1）Communication Protocol HTTP or HTTPS protocol is allowed to request communication. To be more safer, HTTPS protocol is recommended for sending request. When sensitive data such as user passwords and SSH key pairs are involved, for example, in case of specifying password parameters in Login, HTTPS protocol is recommended. （2）Access Gateway When your visit needs to access the API services of Ping An Cloud in mainland China, please use: <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td style="vertical-align:top"> Address (Deployment Location) </td> <td style="vertical-align:top">  Access Address </td> </tr> <tr> <td style="vertical-align:top"> Ping An Cloud (Public Cloud) </td> <td style="vertical-align:top"> https://api.yun.pingan.com </td> </tr> <tr> <td style="vertical-align:top"> Ping An Cloud (Government Cloud) </td> <td style="vertical-align:top"> https://api.city.pingan.com </td> </tr> </tbody> </table> （3）Request Parameters Ping An Cloud offers commands and RESTful APIs, with the former linked to IaaS products and some PaaS products, and the latter linked to SaaS products and some PaaS products. 1）Commands API Commands API Specifies target action with action parameters, e.g. Action=RunInstance. Other parameters of the interface and common request parameters are also needed to be specified, for example: https://api.yun.pingan.com/api/v1?Action=RunInstance&<Common Request Parameter>  2）RESTful API In terms of RESTful API, each URL represents a resource, and therefore there’s no verbs but only nouns, for example: GET https://api.yun.pingan.com/rest/v1/payment/{tenantId}/balance to check the balance in a tenant’s account. The specific action types of resources are represented by HTTP verbs, and the four commonly used HTTP verbs are: <ul> <li>GET（SELECT）： select one or more resources from a server.</li> <li>POST（CREATE）：create a new resource on a server.</li> <li>PUT（UPDATE）：update resources on a server (clients provide all updated resources).</li> <li>DELETE（DELETE）： delete resources on a server.</li> </ul> （4）Character Encoding Ping An Cloud APIs use UTF-8 character encoding to agree to requests and return the results.   2. Common Parameters （1）Common Request Parameters <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td> Parameter Name </td> <td> Parameter Type </td> <td> Required? (True/False) </td> <td> Parameter Description </td> <td> Remarks </td> </tr> <tr> <td> accessKeyId </td> <td> String </td> <td> true </td> <td> Access Key Id </td> <td>   </td> </tr> <tr> <td> signatureMethod </td> <td> String </td> <td> true </td> <td> Signature Method </td> <td> HMAC-SHA1 </td> </tr> <tr> <td> signatureNonce </td> <td> String </td> <td> true </td> <td> Random Number </td> <td>   </td> </tr> <tr> <td> signatureVersion </td> <td> String </td> <td> true </td> <td> SignatureVersion </td> <td> 1.0 </td> </tr> <tr> <td> timestamp </td> <td> String </td> <td> true </td> <td> TimeStamp </td> <td>   </td> </tr> <tr> <td> version </td> <td> String </td> <td> true </td> <td> API Version </td> <td> 2017-01-01 </td> </tr> <tr> <td> signature </td> <td> String </td> <td> true </td> <td> Request Signature </td> <td>   </td> </tr> </tbody> </table> （2） Common Response Parameters <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td> Parameter Name </td> <td> Parameter Type </td> <td> Parameter Description </td> <td> Remarks </td> </tr> <tr> <td> requestId </td> <td> String </td> <td> Request ID </td> <td> Trace ID, new ID will be generated by every request </td> </tr> <tr> <td> code </td> <td> String </td> <td> Request Status </td> <td> HTTP Status </td> </tr> <tr> <td> message </td> <td> String </td> <td> Request Result International Description </td> <td> Messages after internationalization </td> </tr> <tr> <td> resultCode </td> <td> String </td> <td> Request Result Code </td> <td> A00000~Z99999 </td> </tr> </tbody> </table>   3. Signature Mechanism （1）Introduction of Signature Mechanism Accessing the background interface with the AccessKey mainly determines by means of signature verification. whether the url requested by the user is tampered in the transmission process. If the signature verification is passed, such request is deemed as not being tampered, and the background will forward the request to a specific service. If the signature verification fails, it is considered that the current request is insecure for some reasons. For example, If the url requested by the user has been tampered, or the user request expires, the background will refuse to provide the service. After the Master Account is registered or Sub-Account is created in the portal, a pair of AccessKeys will be generated for each user. The AccessKey consists of the AccessKeyId and AccessKeySecret. With the AccessKeyId, the detailed information of its unique corresponding user can be found in the background; AccessKeySecret serves as the secret key to sign the request. AccessKeySecret needs to be kept secret in a strict manner by the user, so as to being protected against theft by another user who impersonates the user for a signature. Currently, method of signature authentication are used to access the background interface. The requested url parameter consists of the following parts: <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> Parameter name </td> <td style="vertical-align:top"> Whether the parameter participates in the signature computation </td> </tr> <tr> <td style="vertical-align:top"> accessKeyId </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> signature </td> <td style="vertical-align:top"> No </td> </tr> <tr> <td style="vertical-align:top"> signatureMethod </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> signatureNonce </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> signatureVersion </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> timestamp </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> version </td> <td style="vertical-align:top"> Yes </td> </tr> <tr> <td style="vertical-align:top"> Specific service interface parameters </td> <td style="vertical-align:top"> Yes </td> </tr> </tbody> </table> （2）Signature Generation Process This section takes the ListZones interface as an example to illustrate the signature generation process. To call this interface, the expected incoming business parameters are as the following: action=ListZones and regionId=Region-southChina. As been mentioned before in "Common Request Parameters", other required parameters may include: accessKeyId=xKJSFaxRfWT_7H0vSzkXLj5gzuS5HDzOkepNGbHWPtDj3mqlg_9nXf4XR23zSm1J_VPlTcXCFMx3JV0UTUDBeA， signatureMethod=HMAC-SHA1， signatureNonce=3378010751426913252， signatureVersion=1.0， timestamp= 1534159280463， version=2017-01-01 The parameters above are the request parameters participating in the signature computation. 1）First, these parameters need to be sorted alphabetically according to their names. The obtained request parameters are as the following: 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）Then, the HmacSHA1 algorithm is used to perform the signature computation for the request parameters. Signature computation requires the AccessKeySecret. The AccessKeySecret of the user is stored on the client. Therefore, users may set this parameter by themselves. The AccessKeySecret and other required parameters during the signature process may be used to compute the value of the final signature. Generally, we use methods such as SDK to integrate or provide some convenient methods for generating signatures or the request URLs on the client. 3）The client uses the signature and other request parameters to generate a request URL and sends the request to the server.   4. Access Verification When the request is sent to the backend service, the backend will use different logics for authentication according to the requested gateway and the URL. If a signature is used to access the backend service, the backend will use the logic for a signature check. The backend will obtain all the request parameters when receiving the request. The following is just an example. The request parameters obtained by the backend may be unordered: 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） First, the backend fetches all request parameters and request parameter values except the signature, then sorts the fetched request parameters alphabetically according to the parameter name. （2） The backend finds the AccessKeySecret in the database according to the AccessKeyId and then uses the AccessKeySecret to perform the signature computation for the sorted request parameters. （3） After obtaining the signature computation results, the backend compares the obtained results with the requested incoming signature results. If the two results are consistent, the request is deemed to be valid and the backend will forward the request to the specific service. If the two results are inconsistent, the backend will refuse to provide any services. During the signature check, the following items are checked separately in turn (see the following table). In the case of a failure to pass any of the following check items, the request will not be executed. The request is deemed to be valid only when it passes all check items. <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> Check Item </td> <td style="vertical-align:top"> Interpretation </td> </tr> <tr> <td style="vertical-align:top"> Resubmission </td> <td style="vertical-align:top"> A method for requesting the AccessKey. It can be used once for each signature. A new signature is generated for each request. Therefore, when a signature has been used once, the backend will be informed of a resubmission if the request with the same signature is sent within 15 minutes. </td> </tr> <tr> <td style="vertical-align:top"> API version error </td> <td style="vertical-align:top"> Currently, the API version shall be 2017-01-01 fixedly. </td> </tr> <tr> <td style="vertical-align:top"> Signature version error </td> <td style="vertical-align:top"> Currently, the signature version shall be 1.0 fixedly. </td> </tr> <tr> <td style="vertical-align:top"> Signature timeliness </td> <td style="vertical-align:top"> The request must be completed within 15 minutes after the signature is generated. A generated signature will expire after 15 minutes. </td> </tr> <tr> <td style="vertical-align:top"> Signature consistency </td> <td style="vertical-align:top"> The requested incoming signature must be consistent with the signature computed by the backend service. If the two signatures are inconsistent, the request is deemed to be insecure. </td> </tr> </tbody> </table>   5.  Returned Results The results returned by the API interface of the Ping An Cloud are mainly in JSON format. For more details, please see "Common Parameters." For the sake of an easy-to-view content and the beauty, operations such as the line feed and indent are conducted for the examples returned from API documents. Line feed and indent are not conducted for results returned actually.

Did the above content solve your problem? Yes No