Create a request

Step 1: Build a canonicalized query string

1. Collect all request parameters — common parameters and operation-specific parameters — but exclude the Signature parameter.

2. Sort the parameters alphabetically by name.

3. Percent-encode each parameter name and value using UTF-8 per RFC 3986: For Java, use java.net.URLEncoder then apply the following corrections:

   • Do not encode: A–Z, a–z, 0–9, -, _, ., ~

   • Encode all other characters as %XY, where XY is the uppercase hexadecimal ASCII code. For example, " becomes %22.

   • Encode spaces as %20, not +.

   private static final String ENCODING = "UTF-8";
   private static String percentEncode(String value) throws UnsupportedEncodingException {
     return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
   }

4. Join each encoded name-value pair with =, then join all pairs with &, in the same alphabetical order.

The result is the canonicalized query string.

Step 2: Build the string to sign

Construct StringToSign using the following formula:

StringToSign =
  HTTPMethod + "&" +
  percentEncode("/") + "&" +
  percentEncode(CanonicalizedQueryString)

• HTTPMethod: The HTTP method in uppercase, for example GET.

• percentEncode("/"): The percent-encoded forward slash, which is %2F.

• percentEncode(CanonicalizedQueryString): The percent-encoded canonicalized query string from step 1.

Step 3: Calculate the signature

Signature = Base64( HMAC-SHA1( AccessKeySecret + "&", UTF-8-Encoding-Of(StringToSign) ) )

Append & to your AccessKeySecret before using it as the HMAC key. This is required by RFC 2104.

In Java:

final String ALGORITHM = "HmacSHA1";
final String ENCODING = "UTF-8";
String key = accessKeySecret + "&";
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
String signature = new String(Base64.encodeBase64(signData));

Step 4: Add the signature to the request

Percent-encode the calculated signature per RFC 3986, then append it as the Signature parameter to the canonicalized query string from step 1.

Example 1: Manual parameter concatenation

Step 1 — Canonicalized query string:

AccessKeyId=testid&Action=DescribeKeywordLib&Format=XML&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&Timestamp=2016-02-23T12:46:24Z&Version=2014-05-26&ServiceModule=open_api

Step 2 — String to sign:

GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeKeywordLib%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf%26SignatureVersion%3D1.0%26Timestamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26%26ServiceModule%3Dopen_api

Step 3 — Calculated signature (key is testsecret&):

OLeaidS1JvxuMvnyHOwuJ+uX5qY=

Step 4 — Final signed URL (RFC 3986-encoded signature: OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D):

http://green.cn-shanghai.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeKeywordLib&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%253A46%253A24Z&ServiceModule=open_api

Send this URL with a browser, curl, or wget to call DescribeKeywordLib and list your custom keyword libraries.

Example 2: Java implementation

This example stores request parameters in a Map<String, String> and builds the signed URL programmatically.

// Step 1: Define encoding helpers

private static final String ENCODING = "UTF-8";
private static String percentEncode(String value) throws UnsupportedEncodingException {
  return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
}

// Timestamp must be in ISO 8601 format, UTC
private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";
private static String formatIso8601Date(Date date) {
  SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT);
  df.setTimeZone(new SimpleTimeZone(0, "GMT"));
  return df.format(date);
}

// Step 2: Build the request parameters

final String HTTP_METHOD = "GET";
Map<String, String> parameters = new HashMap<>();
parameters.put("Action", "DescribeKeywordLib");
parameters.put("Version", "2017-08-23");
parameters.put("AccessKeyId", "testid");
parameters.put("Timestamp", formatIso8601Date(new Date()));
parameters.put("SignatureMethod", "HMAC-SHA1");
parameters.put("SignatureVersion", "1.0");
parameters.put("SignatureNonce", UUID.randomUUID().toString());
parameters.put("Format", "XML");
parameters.put("ServiceModule", "open_api");

// Sort parameters alphabetically
String[] sortedKeys = parameters.keySet().toArray(new String[]{});
Arrays.sort(sortedKeys);

// Build the canonicalized query string
final String SEPARATOR = "&";
StringBuilder canonicalizedQueryString = new StringBuilder();
for (String key : sortedKeys) {
  canonicalizedQueryString.append("&")
    .append(percentEncode(key)).append("=")
    .append(percentEncode(parameters.get(key)));
}

// Build StringToSign
StringBuilder stringToSign = new StringBuilder();
stringToSign.append(HTTP_METHOD).append(SEPARATOR);
stringToSign.append(percentEncode("/")).append(SEPARATOR);
stringToSign.append(percentEncode(canonicalizedQueryString.toString().substring(1)));

// Step 3: Calculate the signature
// Key = AccessKeySecret + "&"

final String ALGORITHM = "HmacSHA1";
String signingKey = "testsecret&";
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(signingKey.getBytes(ENCODING), ALGORITHM));
byte[] signData = mac.doFinal(stringToSign.toString().getBytes(ENCODING));
String signature = new String(Base64.encodeBase64(signData));

After appending the RFC 3986-encoded signature as the Signature parameter, the final URL matches the one in example 1. Send the request using a browser, curl, or wget.