<p>This document describes basic way of accessing Ping An Cloud service by calling API interface. It mainly introduces public parameters, identity authentication process, and other basic concepts.</p>

Use Restrictions

<p>Some restrictions are required when managing user resources by API interfaces of Ping An Cloud. If there are conflicts among specific interface description, parameter optional value, resource specification and usage limits, prior to usage limits.</p>


<p>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.&nbsp;&nbsp;</p> <p>API URL request needs to use AccessKey to sign and encode a URL.</p> <p>&nbsp;</p> <p><strong>1.&nbsp;Request Structure</strong></p> <p>Ping An Cloud supports URL-based HTTP/HTTPS GET request, and request parameters should be included in a URL. Take &ldquo;ListRegions&rdquo; for an example:&nbsp;</p> <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td style="vertical-align:top"> <p><a href=""></a></p> <p>&amp;Id= Region-QTLzvswQFr</p> <p>&amp;&lt;Common Request Parameter&gt;</p> </td> </tr> </tbody> </table> <ul> <li>https: refers to the<span style="color:#0782c1"> </span>request communication protocol.</li> <li> 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>&lt;Common Request Parameter&gt;: refers to the common parameter agreed by Ping An Cloud, having nothing to do with actual business.</li> </ul> <p><strong>(1)Communication Protocol</strong></p> <p>HTTP or HTTPS protocol is allowed to request communication. To be more safer, HTTPS protocol is recommended for sending request.</p> <p>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.</p> <p><strong>(2)Access Gateway</strong></p> <p>When your visit needs to access the API services of Ping An Cloud in mainland China, please use:</p> <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td style="vertical-align:top"> <p>Address (Deployment Location)</p> </td> <td style="vertical-align:top"> <p>&nbsp;Access Address</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Ping An Cloud (Public Cloud)</p> </td> <td style="vertical-align:top"> <p></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Ping An Cloud (Government Cloud)</p> </td> <td style="vertical-align:top"> <p></p> </td> </tr> </tbody> </table> <p><strong>(3)Request Parameters</strong></p> <p>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.</p> <p><strong>1)Commands API</strong></p> <p>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:</p> <p>;&lt;Common Request Parameter&gt;</p> <p><strong>&nbsp;2)RESTful API</strong></p> <p>In terms of RESTful API, each URL represents a resource, and therefore there&rsquo;s no verbs but only nouns, for example:</p> <p>GET{tenantId}/balance to check the balance in a tenant&rsquo;s account.</p> <p>The specific action types of resources are represented by HTTP verbs, and the four commonly used HTTP verbs are:</p> <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> <p><strong>(4)Character Encoding</strong></p> <p>Ping An Cloud APIs use UTF-8 character encoding to agree to requests and return the results.</p> <p>&nbsp;</p> <p><strong>2. Common Parameters</strong></p> <p><strong>(1)Common Request Parameters</strong></p> <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td> <p><strong>Parameter Name</strong></p> </td> <td> <p><strong>Parameter Type</strong></p> </td> <td> <p><strong>Required?</strong></p> <p><strong>(True/False)</strong></p> </td> <td> <p><strong>Parameter Description</strong></p> </td> <td> <p><strong>Remarks</strong></p> </td> </tr> <tr> <td> <p>accessKeyId</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>Access Key Id</p> </td> <td> <p>&nbsp;</p> </td> </tr> <tr> <td> <p>signatureMethod</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>Signature Method</p> </td> <td> <p>HMAC-SHA1</p> </td> </tr> <tr> <td> <p>signatureNonce</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>Random Number</p> </td> <td> <p>&nbsp;</p> </td> </tr> <tr> <td> <p>signatureVersion</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>SignatureVersion</p> </td> <td> <p>1.0</p> </td> </tr> <tr> <td> <p>timestamp</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>TimeStamp</p> </td> <td> <p>&nbsp;</p> </td> </tr> <tr> <td> <p>version</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>API Version</p> </td> <td> <p>2017-01-01</p> </td> </tr> <tr> <td> <p>signature</p> </td> <td> <p>String</p> </td> <td> <p>true</p> </td> <td> <p>Request Signature</p> </td> <td> <p>&nbsp;</p> </td> </tr> </tbody> </table> <p><strong>(2) Common Response Parameters</strong></p> <table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td> <p><strong>Parameter Name</strong></p> </td> <td> <p><strong>Parameter Type</strong></p> </td> <td> <p><strong>Parameter Description</strong></p> </td> <td> <p><strong>Remarks</strong></p> </td> </tr> <tr> <td> <p>requestId</p> </td> <td> <p>String</p> </td> <td> <p>Request ID</p> </td> <td> <p>Trace ID, new ID will be generated by every request</p> </td> </tr> <tr> <td> <p>code</p> </td> <td> <p>String</p> </td> <td> <p>Request Status</p> </td> <td> <p>HTTP Status</p> </td> </tr> <tr> <td> <p>message</p> </td> <td> <p>String</p> </td> <td> <p>Request Result International Description</p> </td> <td> <p>Messages after internationalization</p> </td> </tr> <tr> <td> <p>resultCode</p> </td> <td> <p>String</p> </td> <td> <p>Request Result Code</p> </td> <td> <p>A00000~Z99999</p> </td> </tr> </tbody> </table> <p>&nbsp;</p> <p><strong>3.&nbsp;Signature Mechanism</strong></p> <p><strong>(1)Introduction of Signature Mechanism</strong></p> <p>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.</p> <p>Currently, method of signature authentication are used to access the background interface. The requested url parameter consists of the following parts:</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> <p><strong>Parameter name</strong></p> </td> <td style="vertical-align:top"> <p><strong>Whether the parameter participates in the signature computation</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>accessKeyId</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>signature</p> </td> <td style="vertical-align:top"> <p>No</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>signatureMethod</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>signatureNonce</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>signatureVersion</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>timestamp</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>version</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Specific service interface parameters</p> </td> <td style="vertical-align:top"> <p>Yes</p> </td> </tr> </tbody> </table> <p><strong>(2)Signature Generation Process</strong></p> <p>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.</p> <p>As been mentioned before in &quot;Common Request Parameters&quot;, other required parameters may include:</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>The parameters above are the request parameters participating in the signature computation.</p> <p>1)First, these parameters need to be sorted alphabetically according to their names. The obtained request parameters are as the following:</p> <p>accessKeyId=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)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. <strong>Generally, we use methods such as SDK to integrate or provide some convenient methods for generating signatures or the request URLs on the client.</strong></p> <p>3)The client uses the signature and other request parameters to generate a request URL and sends the request to the server.</p> <p>&nbsp;</p> <p><strong>4.&nbsp;Access Verification</strong></p> <p>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.</p> <p>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:</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) First, the backend fetches all request parameters and request parameter values except the<strong> signature</strong>, then sorts the fetched request parameters alphabetically according to the parameter name.</p> <p>(2) The backend finds <strong>the AccessKeySecret</strong> in the database according to the<strong> AccessKeyId</strong> and then uses the <strong>AccessKeySecret</strong> to perform the signature computation for the sorted request parameters.</p> <p>(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.</p> <p>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.</p> <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top"> <p><strong>Check Item</strong></p> </td> <td style="vertical-align:top"> <p><strong>Interpretation</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Resubmission</p> </td> <td style="vertical-align:top"> <p>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.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>API version error</p> </td> <td style="vertical-align:top"> <p>Currently, the API version shall be 2017-01-01 fixedly.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Signature version error</p> </td> <td style="vertical-align:top"> <p>Currently, the signature version shall be 1.0 fixedly.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Signature timeliness</p> </td> <td style="vertical-align:top"> <p>The request must be completed within 15 minutes after the signature is generated. A generated signature will expire after 15 minutes.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Signature consistency</p> </td> <td style="vertical-align:top"> <p>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.</p> </td> </tr> </tbody> </table> <p>&nbsp;</p> <p><strong>5.&nbsp; Returned Results</strong></p> <p>The results returned by the API interface of the Ping An Cloud are mainly in JSON format. For more details, please see &quot;Common Parameters.&quot; 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.</p>


<table border="1" cellpadding="0" cellspacing="0" style="width:0px"> <tbody> <tr> <td style="vertical-align:top"> <p><strong>Name</strong></p> </td> <td style="vertical-align:top"> <p><strong>Description</strong></p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Region</p> </td> <td style="vertical-align:top"> <p>Geographic region covered by IDC of Ping An Cloud. If a user purchases the data of the region, the user cannot change to another region.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Zone</p> </td> <td style="vertical-align:top"> <p>Physical data center with independent power and network within a region. One region may have multiple zones. Two zones within a region can interconnect with each other through intranet; faults may be isolated between two zones within a region; network delay is low.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Instance</p> </td> <td style="vertical-align:top"> <p>For resources purchased from Ping An Cloud such as ECS and OBS, instances are bound to the product specifications.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Resource Type</p> </td> <td style="vertical-align:top"> <p>Resource type: the service type is distinguished as different resource types based on the service concepts. For example, Instance involves resource types such as Instance, Ebs, Nic, Image and Snapshot. It corresponds to the Resource Option of a portal [Operation Audit].</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Product Series</p> </td> <td style="vertical-align:top"> <p><strong>Product series: </strong>service concept, product categories classified on the basis of some features. If resources differ greatly, they are generally split into different series according to service requirements of each product. For example, Instance is divided into series such as standard ECS and SSD ECS</p> <p><strong>Product: </strong>Correlate to [Basic Management] [Product Management]</p> <p><strong>Scope:</strong> SPECIAL or PUBLIC; specify whether the product series is a special category specific to a region or a tenant. Currently, the function is replaced by a menu management.</p> <p><strong>Attributes:</strong> Attributes customized for each product according to actual situations.</p> </td> </tr> <tr> <td style="vertical-align:top"> <p>Product Specification</p> </td> <td style="vertical-align:top"> <p>Product Specifications: Product type dimensions may be created for each product series. Generally, product specifications are subjective distinctions (such as different sizes and configurations) for the same type of resources. For example, the specifications for the standard cloud hosts include 1c2g and 2c4g.</p> </td> </tr> </tbody> </table>
Did the above content solve your problem? Yes No
Please complete information!

Call us


Email us

Online customer service

Instant reply

Technical Support

cloud products