Content Moderation:Construct a request

Communication protocols

You can send requests over HTTP or HTTPS.

Request methods

All operations support the POST and GET methods.

Encoding

The request parameters and responses of all operations are encoded in UTF-8.

API request structure

API endpoint

http(s)://green.cn-shanghai.aliyuncs.com

Common parameters

Operation-specific parameters

Click an operation in the List of operations by function topic to query the specific parameters of the operation. For more information, see List of operations by function.

Signature method

You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Content Moderation implements symmetric encryption with an AccessKey pair to verify the identity of the request sender.

An AccessKey pair is an identity credential issued to Alibaba Cloud accounts and RAM users that is similar to a logon username and password. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. The AccessKey ID is used to verify the identity of the user, while the AccessKey secret is used to encrypt and verify the signature string. You must keep your AccessKey secret strictly confidential.

1. Create a canonicalized query string.
   1. Arrange the request parameters (including all common and operation-specific parameters except Signature) in alphabetical order.
      Note If you use the GET method to send a request, the request parameters are included as a part of the request URL. The first parameter follows the question mark (?) in the URL, and the other parameters follow an ampersand (&).
   2. Encode the request parameters and their values in UTF-8 based on RFC 3986. The following rules apply in the encoding process:
      • Uppercase letters, lowercase letters, digits, and some special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.
      • Other characters must be percent encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
      • Extended UTF-8 characters are encoded in the %XY%ZA… format.
      • Spaces must be encoded as %20. Do not encode spaces as plus signs (+).
        The preceding encoding method is similar to but slightly different from the application/x-www-form-urlencoded MIME-type encoding algorithm. If you use java.net.URLEncoder in the Java standard library, use percentEncode to encode request parameters and their values. In the encoded query string, replace the plus sign (+) with %20, the asterisk (*) with %2A, and %7E with a tilde (~). This way, you can obtain an encoded string that matches the preceding encoding rules.

        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;
        }

   3. Use equal signs (=) to connect the encoded request parameters and their values.
   4. Use ampersands (&) to connect the encoded request parameters. These parameters must be arranged in the same order as those in Step i.

   Then, a canonicalized query string (CanonicalizedQueryString) that follows the request structure is obtained.

2. Create a string-to-sign from the encoded canonicalized query string.
   1. Create a string-to-sign (StringToSign). You can also use percentEncode to encode the canonicalized query string that is created in the previous step. Comply with the following rules to create a string-to-sign:

      StringToSign=
        HTTPMethod + "&" + //HTTPMethod: the HTTP method that is used to send a request, such as GET.
        percentEncode("/") + "&" + //percentEncode("/"): Encode the forward slash (/) in UTF-8 as %2F.
        percentEncode(CanonicalizedQueryString) //Encode the canonicalized query string created in Step 1.

   2. Calculate the HMAC-SHA1 value of StringToSign based on RFC 2104. The Java Base64 encoding method is used in this example.

      Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

      Note When you calculate the signature, the key value that is specified by RFC 2104 is your AccessKey secret with an ampersand (&) which has an ASCII value of 38.
   3. Encode the Signature parameter based on RFC 3986 and add it to the canonicalized query string.

Sample code

• Example 1: Concatenate parameters

  The following example describes how to call the DescribeKeywordLib operation to query custom text libraries. Assume that AccessKeyID is set to testid and AccessKeySecret is set to testsecret.

  1. Create a 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

  2. Create a 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

  3. Calculate the signature. The key value that is used for calculation is testsecret& because AccessKeySecret is set to testsecret. The calculated signature is OLeaidS1JvxuMvnyHOwuJ+uX5qY=. The Java Base64 encoding method is used in this example.

     Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

  4. Add Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D that has been encoded based on RFC 3986 to the URL in Step i.

     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

  You can use a browser or tools such as cURL and Wget to initiate an HTTP request based on the new URL. The HTTP request calls the DescribeKeywordLib operation to query custom text libraries.

• Example 2: Use the standard library of the programming language

  The following example describes how to call the DescribeKeywordLib operation to query custom text libraries. Assume that AccessKeyID is set to testid and AccessKeySecret is set to testsecret, and all request parameters are placed in a Java Map<String, String> object.

  1. Predefine the encoding method.

     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;
     }

  2. Predefine the time format for the Timestamp parameter. Set the Timestamp parameter in the ISO 8601 format. The time must be in UTC+0.

     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);
     }

  3. Create a request string.

     final String HTTP_METHOD = "GET";
     Map parameters = new HashMap();
     // Specify request parameters.
     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");
     // Arrange the request parameters.
     String[] sortedKeys = parameters.keySet().toArray(new String[]{});
     Arrays.sort(sortedKeys);
     final String SEPARATOR = "&";
     // Create a string-to-sign.
     StringBuilder stringToSign = new StringBuilder();
     stringToSign.append(HTTP_METHOD).append(SEPARATOR);
     stringToSign.append(percentEncode("/")).append(SEPARATOR);
     StringBuilder canonicalizedQueryString = new StringBuilder();
     for(String key : sortedKeys) {
     // Encode the key and value.
       canonicalizedQueryString.append("&")
       .append(percentEncode(key)).append("=")
       .append(percentEncode(parameters.get(key)));
     }
     // Encode the canonicalized query string.
     stringToSign.append(percentEncode(
       canonicalizedQueryString.toString().substring(1)));

  4. Calculate the signature. The key value that is used for calculation is testsecret& because AccessKeySecret is set to testsecret. The calculated signature is OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D.

     // The following sample code demonstrates how to calculate the signature.
     final String ALGORITHM = "HmacSHA1";
     final String ENCODING = "UTF-8";
     key = "testsecret&";
     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));

     Encode the Signature parameter based on RFC 3986 and add the parameter to the URL. The following URL is obtained:

     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

  5. Use browsers or tools such as cURL and Wget to send HTTP requests and obtain the response.

API response

Click an operation in the List of operations by function topic to query the response of the operation. For more information, see List of operations by function.