Drive and Photo Service:Calling PDS API By Using An AccessKey Pair

1. Sample request for calling an API operation by using an AccessKey pair

You can call all the API operations within the following endpoints by sending requests that are signed by using AccessKey pairs.

Sample request:

POST /v2/drive/list

Host: ${domainID}.api.aliyunpds.com
Authorization: acs ${ACCESS_KEY_ID}:${SIGNATURE}
Content-Type: application/json; charset=UTF-8

{
  "owner": "xxxx"
}

2. Sign a request by using an AccessKey pair

You can add the Authorization header to an HTTP request to include a signature in the request. This signature indicates that the request is authorized.

2.1 Signature calculation method

In the following example, the resource-oriented architecture (ROA) request style of Alibaba Cloud SDK is used. Make sure that Alibaba Cloud SDK is accessible.

Authorization = "acs " + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha1(AccessKeySecret,
            VERB + "\n"
            + Accept + "\n"
            + Content-MD5 + "\n"
            + Content-Type + "\n"
            + Date + "\n"
            + CanonicalizedHeaders
            + CanonicalizedResource))

• AccessKeySecret: the AccessKey secret that is used to sign the request.

• VERB: the method of the HTTP request. Set the value to POST.

• \n: the line feed.

• Accept: optional. If you specify this header, set the value to application/json.

• Content-MD5: the MD5 hash of the request content. You need to specify this header only if the request body is not empty. Calculate the MD5 hash of the request content that excludes headers to obtain a 128-bit number. Encode this number in Base64 to obtain the value of this header. This header can be used to check whether the received request content is the same as the request content that is sent. Example: eB5eJF1ptWaXm4bijSPyxw==. For more information, see Content-MD5 in Request for Comments (RFC) 2616.

• Content-Type: optional. This header specifies the type of the request content. Example: application/octet-stream.

• Date: required. This header specifies the time when the request was sent, in Greenwich Mean Time (GMT). Example: Sun, 22 Nov 2015 08:16:38 GMT.

• CanonicalizedHeaders: the HTTP headers that are prefixed with x-acs-. The headers are arranged in alphabetical order.

• CanonicalizedResource: the PDS resources you want to access. The Date header and the CanonicalizedResource string are required. If the difference between the time specified by the Date header in the request and the time on the PDS server when the request is received is greater than 15 minutes, PDS rejects the request and returns the HTTP status code 403.

2.2 How to create a CanonicalizedHeaders string

A CanonicalizedHeaders string consists of all HTTP headers that are prefixed with x-acs-. To create a CanonicalizedResource string, perform the following steps:

1. Convert the names of all HTTP headers that are prefixed with x-acs- to lowercase letters. For example, convert X-ACS-Meta-Name: TaoBao into x-acs-meta-name: TaoBao.

2. If the request is sent by using an AccessKey pair provided by Security Token Service (STS), add the security-token value to the CanonicalizedHeaders string in the format of x-acs-security-token:security-token.

3. Sort all the HTTP headers obtained in the previous step in alphabetical order.

4. Delete all spaces on each side of the delimiter between each header and value. For example, convert x-acs-meta-name: TaoBao into x-acs-meta-name:TaoBao.

5. Separate every two pairs of headers and their values with the delimiter \n to obtain the CanonicalizedHeaders string.

2.3 How to create a CanonicalizedResource string

A CanonicalizedResource string specifies the PDS resource that you want to access. To create a CanonicalizedResource string, perform the following steps:

1. Set the CanonicalizedResource string to an empty string "".

2. Add the PDS resource that you want to access to the empty string. Example: /v2/domain/list.

2.4 Signature calculation rules

• The string-to-sign must be encoded in UTF-8. Use the UTF-8-encoded string-to-sign and an AccessKeySecret to calculate the signature.

• Use the HMAC-SHA1 method defined in RFC 2104 to calculate the signature. In this method, the AccessKeySecret is used as the key.

• The Accept, Content-Type, and Content-MD5 headers are optional in a request. If these headers are empty in a request, replace them with line feeds (\n) when you calculate a signature for the request.

• Among all non-standard HTTP headers, only the headers that are prefixed with x-acs- need to be added to the string-to-sign. Other non-standard HTTP headers are ignored.

• Headers prefixed with x-acs- in the string-to-sign must comply with the following conventions:

• The header names are in lowercase.

• The headers are sorted in alphabetical order.

• No space exists before or after the colon (:) that separates each header name and value.

• Each header is followed by a line feed (\n). If the request does not contain headers that are prefixed with x-acs-, specify the CanonicalizedHeaders string as an empty string without a tailing \n delimiter.

2.5 Troubleshooting

• If you specify the Accept header, verify that the value is application/json. Otherwise, the error 400 Bad Request is returned. The error code is InvalidHeader.

• Verify that the body length does not exceed 4 MB. If the body length exceeds 4 MB, the error 400 Bad Request is returned. The error code is InvaliField.

• If the format of the Authorization header is invalid, the error 400 Bad Request is returned. The error code is InvaliField.

• If the AccessKey ID starts with STS, verify that the x-acs-security-token header is set. Otherwise, the error 403 Forbidden is returned. The error code is InvalidHeader.

• If the AccessKey ID does not exist or is in the Disabled state, the error 403 Forbidden is returned. The error code is InvalidParameter.

• If the AccessKey ID is in the Enabled state, but PDS detects that the signature for the request is invalid, the error 403 Forbidden is returned. The error code is SignatureDoesNotMatch. The string-to-sign that is used to verify the signature is also returned in the response. You can check whether the signature string is correct based on the response.

3. Permission control

PDS API server uses Alibaba Cloud Resource Access Management (RAM) to verify permissions. You can configure permission policies for the AccessKey pair of the RAM user that you use in the RAM console.

The following table describes the action and resource that are verified for each API operation.