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

Use guide

Prerequisites <ul> <li>To use the Ping An Cloud OpenAPI service, you must have a Ping An Cloud account and an access key.</li> <li>Create and manage your access key in the Ping An Cloud console, or contact your account administrator to obtain the access key.</li> <li>Before using an API for a product, make sure you have opened this product.</li> </ul> Access Address You can obtain the Ping An Cloud OpenAPI service at https://api.yun.pingan.com. Currently, the Ping An Cloud OpenAPI supports the following access styles: <ul> <li>Action style—Each request parameter contains multiple key-value pairs. Specify the name of an operation in the Action key-value pair, and service parameters in other key-value pairs. The Action APIs support GET and POST requests. The routing entrance of Action APIs is /api/v1 (https://api.yun.pingan.com/api/v1).</li> <li>Restful style—Support the path parameter, the URL parameter, and the Body parameter. You can use the following HTTP methods to request resources: GET (for obtaining), POST (for adding or modifying), PUT (for updating), and DELETE (for deleting). The routing entrance is /rest/v1 (https://api.yun.pingan.com/rest/v1).</li> </ul> Required Structure Ping An Cloud supports URL-based HTTP/HTTPS GET or POST requests. The request parameters must be included in the URL. For example, for the GetUser API that obtains the current user information, its original URL request is as follows: https://api.yun.pingan.com/api/v1?Action=GetUser&<public request parameters> <ul> <li>HTTPS—Communication protocol of the request.</li> <li>api.yun.pingan.com—Access address of the service.</li> <li>/Api/v1—API type.</li> <li>Action=GetUser—API to be called.</li> <li><public request parameters>—Public parameters. For more information, see Public Request Parameters of the Ping An Cloud OpenAPI Service.</li> </ul> Character Encoding Both the requests and responses use UTF-8 encoding. Identity Authentication The Ping An Cloud OpenAPI service uses access key-based identity authentication. Functioning as a password that is used for a console login, an access key is used to call APIs. Consisting of an access key ID and a secret access key, each access key is globally unique. The access key ID uniquely identifies a user. The client uses the secret access key to sign the request, and the server uses the secrete access key to verify the client's signature to determine whether the request is valid. The secret access key is user-sensitive information. You must keep it strictly confidential. Once stolen, it might be maliciously used to perform illegal operations on your resources in Ping An Cloud. Signature Mechanism The Ping An Cloud OpenAPI service verifies the signature of a request to ensure that the request has not been altered in transit. The server accepts and executes only the requests that pass verification, and denies the requests that fail verification. The recommended signature algorithm is HMAC-SHA256. The client signs its requests by using the unique secret access key that is known only by the client and Ping An Cloud. By comparing the client-side and server-side signatures that are generated based on the same request data and the same key, the OpenAPI service determines whether the request is valid and unaltered. Signature Process The client signs a request and then sends the request and its signature to the server. After receiving the request, the server signs the request data and compares its locally generated signature with the signature that it received from the client. To enable both the client and the server to generate the same signature, make sure the two parties use the same request data and the signature process. The signature process can be effected by the validity, timeliness, anti-replay attack, algorithm version, and API version. When you access the Ping An Cloud API service, the following public request parameters are required: Public Request Parameters of the Ping An Cloud OpenAPI Service <table border="1" cellpadding="0" cellspacing="0" style="width:820px"> <tbody> <tr> <td style="width:149px"> Name </td> <td style="width:108px"> Type </td> <td style="width:198px"> Description </td> <td style="width:355px"> Remarks </td> </tr> <tr> <td style="width:149px"> AccessKeyId </td> <td style="width:108px"> String </td> <td style="width:198px"> Access key ID that uniquely identifies a user. </td> <td style="width:355px"> The access key ID is included in the access key. </td> </tr> <tr> <td style="width:149px"> SignatureMethod </td> <td style="width:108px"> String </td> <td style="width:198px"> Signature algorithm. </td> <td style="width:355px"> The recommended signature algorithm is HMAC-SHA256, which is also the fixed value. </td> </tr> <tr> <td style="width:149px"> SignatureNonce </td> <td style="width:108px"> String </td> <td style="width:198px"> Random number of a request. </td> <td style="width:355px"> Each request must be followed by a complex random number to identify the request and prevent the request replay. </td> </tr> <tr> <td style="width:149px"> SignatureVersion </td> <td style="width:108px"> String </td> <td style="width:198px"> Signature version. </td> <td style="width:355px"> The currently supported version is 1.0, which is also the fixed value. </td> </tr> <tr> <td style="width:149px"> Timestamp </td> <td style="width:108px"> String </td> <td style="width:198px"> Signature timestamp. </td> <td style="width:355px"> Timestamp when the request is signed. The timestamp string is required for generating the signature. </td> </tr> <tr> <td style="width:149px"> Version </td> <td style="width:108px"> String </td> <td style="width:198px"> API version. </td> <td style="width:355px"> The currently supported API version is 2017-01-01, which is also the fixed value. </td> </tr> <tr> <td style="width:149px"> Signature </td> <td style="width:108px"> String </td> <td style="width:198px"> Signature of the request content. </td> <td style="width:355px"> The signature of the request content is calculated based on the special parameters above and service parameters. </td> </tr> </tbody> </table> Request Parameter Encoding The client encodes the request parameter names and the parameter values in an HTTP/HTTPS request URL in compliance with RFC 3986 as follows: •    The following characters are not encoded: a to z, A to Z, 0 to 9, hyphens (-), underscores (_), dots (.), and tildes (~). •    Other characters are extended in the format of %XY, where XY is the hexadecimal strings converted from ASCII codes of the characters. •    A single space is encoded as %20 instead of a plus sign (+). If Java codes are used for signature generation, characters can be encoded by using the java.net.URLEncoder class in the Java standard library or the java.net.URLEncoder implemented in Java components. In either case, special processing is required for the encoding result. For example, the plus sign (+), asterisk (*), and %7E must be replaced with % 20, %2A, and tilde (~), respectively. Data Signature Process <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td style="vertical-align:top; width:154px"> Step </td> <td style="vertical-align:top; width:633px"> Action </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Configure parameters </td> <td style="vertical-align:top; width:633px"> <ul> <li>Set all values of public and service parameters.</li> <li>Service parameter: Action=GetUser.</li> <li>Public parameters: AccessKeyld=XXXXXXXX, version=2017-01-01, signatureVersion=1.0, signatureMethod=HMAC-SHA256, Timestamp=1579516096440, signatureNonce=14489499455.</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Encode key-value pairs </td> <td style="vertical-align:top; width:633px"> <ul> <li>Encode all the key-value pairs in the format of application/x-www-form-urlencoded. For example, if a value before encoding is a space, the encoded value is a plus sign (+).</li> <li>Replace some special characters in the encoding result. The plus sign (+) is replaced with %20, asterisk (*) with %2A, and %7E with tilde (~).</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Convert cases </td> <td style="vertical-align:top; width:633px"> <ul> <li>Convert all the key-value pairs to lowercase letters: action=getuser, accesskeyid=xxxxxxxx, version=2017-01-01, signatureversion=1.0, signaturemethod=hmac-sha256, timestamp=1579516096440, signaturenonce=14489499455.</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Sort key-value pairs </td> <td style="vertical-align:top; width:633px"> <ul> <li>Sort all the key-value pairs in alphabetical order: accesskeyid=xxxxxxxx, action=getuser, signaturemethod=hmac-sha256, signaturenonce=14489499455, signatureversion=0.1, timestamp=1579516096440, version=2017-01-01.</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Concatenate key-value pairs </td> <td style="vertical-align:top; width:633px"> <ul> <li>Concatenate all the key-value pairs with at signs (&) to form the new data to be signed: accesskeyid=xxxxxxxx&action=getuser&signaturemethod=hmac-sha256&signaturenonce=14489499455&signatureversion=0.1&timestamp=1579516096440&version=2017-01-01.</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Sign data </td> <td style="vertical-align:top; width:633px"> <ul> <li>Use the secret access key and the HMAC-SHA256 algorithm to sign the concatenated data. The generated signature is yyyyyyyy. If the signature contains a plus sign (+), replace the plus sign with %2B. For example, replace yyyy+yyyy with yyyy%2Byyyyy.</li> </ul> </td> </tr> <tr> <td style="vertical-align:top; width:154px"> Send request </td> <td style="vertical-align:top; width:633px"> <ul> <li>Send a request of the original data (the unencoded and unconverted parameters) with the signature appended to the request URL. No special requirement for parameter orders when sending a request.</li> </ul> </td> </tr> </tbody> </table>   Request and Response Request Methods GET, POST Public Request Parameters <table border="1" cellpadding="0" cellspacing="0" style="width:794px"> <tbody> <tr> <td style="width:221px"> Parameter Name </td> <td style="width:567px"> Description </td> </tr> <tr> <td style="width:221px"> Public request parameters </td> <td style="width:567px"> For more information, see Public Request Parameters of the Ping An Cloud OpenAPI Service. </td> </tr> <tr> <td style="width:221px"> Service parameters </td> <td style="width:567px"> For more information, see the product-specific API document. </td> </tr> </tbody> </table> Public Response Parameters <table border="1" cellpadding="0" cellspacing="0"> <tbody> <tr> <td> Name </td> <td style="width:114px"> Type </td> <td style="width:171px"> Description </td> <td style="width:383px"> Remarks </td> </tr> <tr> <td> RequestId </td> <td style="width:114px"> String </td> <td style="width:171px"> Request ID. </td> <td style="width:383px"> A unique request ID is generated for each request. </td> </tr> <tr> <td> Code </td> <td style="width:114px"> String </td> <td style="width:171px"> Request result status. </td> <td style="width:383px"> English code of the request result. </td> </tr> <tr> <td> Message </td> <td style="width:114px"> String </td> <td style="width:171px"> International description of the request result. </td> <td style="width:383px"> You can set Accept-Language in the request header. The currently supported settings are zh-CN (default) and en-US. </td> </tr> <tr> <td> ResultCode </td> <td style="width:114px"> String </td> <td style="width:171px"> Request result code. </td> <td style="width:383px"> The code range is A00000 to Z99999. </td> </tr> <tr> <td> Service response parameters. </td> <td colspan="3"> For more information, see the product-specific API document. </td> </tr> </tbody> </table>

Did the above content solve your problem? Yes No