This topic describes the method for constructing a request to call the Content Moderation API. This method is applicable if you initiate HTTP or HTTPS requests based on the API URL.

Note Content Moderation provides SDKs in multiple programming languages and supports third-party SDKs. You can use the SDKs to eliminate the need of constructing API requests by yourself. For more information, see SDK overview.

Protocols

You can send requests over HTTP or HTTPS.

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

Type Description Remarks
API endpoint The endpoint for the Content Moderation API. Example: http(https)://green.cn-shanghai.aliyuncs.com.
Common request parameters The common parameters required in all API requests. For more information, see Common request parameters.
Operation-specific parameters The parameters that are specific to each operation. For more information, see the definition of each operation.

API endpoint

To call the Content Moderation API to manage custom term libraries, custom text pattern libraries, and custom image libraries, you must send a request to the following endpoint:
http(s)://green.cn-shanghai.aliyuncs.com
Notice Only the preceding endpoint is supported. Use the preceding endpoint to call the Content Moderation API in all regions of China. The server can automatically synchronize data if you initiate a request in a region other than cn-shanghai.

Common request parameters

Parameter Type Required Description
Action String Yes The operation that you want to perform. For more information, see List of operations by function.
AccessKeyId String Yes The AccessKey ID provided to you by Alibaba Cloud. The AccessKey is used to call API operations.
Signature String Yes The signature string of the current request. For more information about how signatures are calculated, see Signature method.
SignatureMethod String Yes The encryption method of the signature string. Set the value to HMAC-SHA1.
SignatureVersion String Yes The version of the signature encryption algorithm. Set the value to 1.0.
SignatureNonce String Yes A unique, random number used to prevent replay attacks. You must use different numbers for different requests.
Timestamp String Yes The timestamp of the request. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. Example: 2018-01-01T12:00:00Z.
Version String Yes The version number of the API. The value must be in the YYYY-MM-DD format. Set the value to 2017-08-23.
Format String No The format in which to return the response. Valid values:
  • json
  • xml

Default value: xml.

Operation-specific parameters

Click an operation in List of operations by function to query the specific parameters of the operation.

Sign signatures

You must sign all HTTP or HTTPS API requests to gurantee security. Alibaba Cloud uses the request signature to verify the identity of the request sender. 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 When you use the GET method to submit requests, specify these parameters in the request URL following the question mark (?) and connect the remaining parameters with ampersands (&).
    2. Encode the request parameters and their values in UTF-8 based on RFC 3986. Encoding rules are as follows:
      • 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 %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 %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 (~). In 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 an equal sign (=) to connect each encoded request parameter and its value.
    4. Use an ampersand (&) to connect the encoded request parameters. Note that these parameters must be arranged in the same order as that in Step a.

    Now, you have obtained a canoncalized query string (CanonicalizedQueryString) that follows the API request structure.

  2. Create a string-to-sign from the encoded canonicalized query string.
    1. Create StringToSign. You can also use percentEncode to encode the canonicalized query string constructed in the previous step. The rules are as follows:
      StringToSign=
         HTTPMethod + "&" + // HTTPMethod: the HTTP method used to send a request, such as GET.
        percentEncode("/") + "&" + // percentEncode("/"): the UTF-8 encoded value of the forward slash (/), which is %2F.
        percentEncode(CanonicalizedQueryString) // Your canonicalized query string.
    2. Calculate the HMAC-SHA1 value of StringToSign based on RFC 2104. This example uses the Java Base64 encoding method.
      Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )
      Note When you calculate the signature, the key value specified by RFC 2104 is your AccessKeySecret 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. In the case of AccessKeyID=testid and AccessKeySecret=testsecret, the signature process is as follows:
    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 HMAC value of the string-to-sign. In the case of AccessKeySecret=testsecret, the key value used for calculation is testsecret&. The calculated signature value is OLeaidS1JvxuMvnyHOwuJ+uX5qY=. This example uses the Java Base64 encoding method.
      Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )
    4. Add the Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D string that has been encoded based on RFC 3986 to the URL in Step a.
      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 through 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. The value of the Timestamp parameter must be specified in the ISO 8601 standard. 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 query 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 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. In the case of AccessKeySecret=testsecret, the key value used for calculation is testsecret&. The calculated signature value is OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D.
      // The following 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 new URL is as follows:
      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 List of operations by function to query the response of the operation.