Content Moderation:Text Moderation 2.0 PLUS SDK Integration Guide

Java SDK

Java 1.8 and later versions are supported.

For the source code, see Java SDK source code or Java SDK source code (OSS path).

Add the following dependency to the pom.xml file to use the SDK in a Maven project.

1. Add the following dependency to the dependencies section.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>green20220302</artifactId>
  <version>2.2.11</version>
</dependency>

2. Java SDK code example for integration.

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.aliyun.green20220302.Client;
import com.aliyun.green20220302.models.TextModerationPlusRequest;
import com.aliyun.green20220302.models.TextModerationPlusResponse;
import com.aliyun.green20220302.models.TextModerationPlusResponseBody;
import com.aliyun.teaopenapi.models.Config;


public class TextModerationPlusDemo {

    public static void main(String[] args) throws Exception {
        Config config = new Config();
        /**
         * The AccessKey of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey of an Alibaba Cloud account for API access is highly risky. We recommend that you use a RAM user for API access or O&M.
         * Common methods to obtain environment variables:
         * Method 1:
         *     Obtain the AccessKey ID of the RAM user: System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
         *     Obtain the AccessKey secret of the RAM user: System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
         * Method 2:
         *     Obtain the AccessKey ID of the RAM user: System.getProperty("ALIBABA_CLOUD_ACCESS_KEY_ID");
         *     Obtain the AccessKey secret of the RAM user: System.getProperty("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
         */
        config.setAccessKeyId("We recommend that you obtain the AccessKey ID of the RAM user from environment variables");
        config.setAccessKeySecret("We recommend that you obtain the AccessKey secret of the RAM user from environment variables");
        //Modify the region and endpoint as needed
        config.setRegionId("ap-southeast-1");
        config.setEndpoint("green-cip.ap-southeast-1.aliyuncs.com");
        //Read timeout period in milliseconds (ms).
        config.setReadTimeout(6000);
        //Connection timeout period in milliseconds (ms).
        config.setConnectTimeout(3000);
        //Set the HTTP proxy.
        //config.setHttpProxy("http://xx.xx.xx.xx:xxxx");
        //Set the HTTPS proxy.
        //config.setHttpsProxy("https://xx.xx.xx.xx:xxxx");
        Client client = new Client(config);

        JSONObject serviceParameters = new JSONObject();
        serviceParameters.put("content", "Test text content");

        TextModerationPlusRequest textModerationPlusRequest = new TextModerationPlusRequest();
        // Detection type
        textModerationPlusRequest.setService("comment_multilingual_pro_global");
        textModerationPlusRequest.setServiceParameters(serviceParameters.toJSONString());

        try {
            TextModerationPlusResponse response = client.textModerationPlus(textModerationPlusRequest);
            if (response.getStatusCode() == 200) {
                TextModerationPlusResponseBody result = response.getBody();
                System.out.println(JSON.toJSONString(result));
                System.out.println("requestId = " + result.getRequestId());
                System.out.println("code = " + result.getCode());
                System.out.println("msg = " + result.getMessage());
                Integer code = result.getCode();
                if (200 == code) {
                    TextModerationPlusResponseBody.TextModerationPlusResponseBodyData data = result.getData();
                    System.out.println(JSON.toJSONString(data, true));
                } else {
                    System.out.println("text moderation not success. code:" + code);
                }
            } else {
                System.out.println("response not success. status:" + response.getStatusCode());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python SDK

Python 3.6 and later versions are supported.

For the source code, see Python SDK source code.

1. Run the following command to import the dependencies.

pip install alibabacloud_green20220302==2.2.11

2. Python SDK code example for integration.

# coding=utf-8
# python version >= 3.6
from alibabacloud_green20220302.client import Client
from alibabacloud_green20220302 import models
from alibabacloud_tea_openapi.models import Config
import json

config = Config(
    # The AccessKey of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey of an Alibaba Cloud account for API access is highly risky. We recommend that you use a RAM user for API access or O&M.
    # We strongly recommend that you do not store the AccessKey ID and AccessKey secret in your code. Otherwise, your AccessKey may be leaked, which threatens the security of all resources under your account.
    # Common methods to obtain environment variables:
    # Obtain the AccessKey ID of the RAM user: os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
    # Obtain the AccessKey secret of the RAM user: os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
    access_key_id='We recommend that you obtain the AccessKey ID of the RAM user from environment variables',
    access_key_secret='We recommend that you obtain the AccessKey secret of the RAM user from environment variables',
    # Connection timeout period in milliseconds (ms)
    connect_timeout=10000,
    # Read timeout period in milliseconds (ms)
    read_timeout=3000,
    region_id='ap-southeast-1',
    endpoint='green-cip.ap-southeast-1.aliyuncs.com'
)

clt = Client(config)

serviceParameters = {
    'content': 'Test text content'
}
textModerationPlusRequest = models.TextModerationPlusRequest(
    # Detection type
    service='comment_multilingual_pro_global',
    service_parameters=json.dumps(serviceParameters)
)

try:
    response = clt.text_moderation_plus(textModerationPlusRequest)
    if response.status_code == 200:
        # Call successful
        result = response.body
        print('response success. result:{}'.format(result))
    else:
        print('response not success. status:{} ,result:{}'.format(response.status_code, response))
except Exception as err:
    print(err)

PHP SDK

PHP 5.6 and later versions are supported.

For the source code, see PHP SDK source code.

1. Run the following command to import the dependencies.

composer require alibabacloud/green-20220302 2.2.10

2. PHP SDK code example for integration.

<?php
require('vendor/autoload.php');

use AlibabaCloud\SDK\Green\V20220302\Models\TextModerationPlusRequest;
use AlibabaCloud\Tea\Exception\TeaUnableRetryError;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\SDK\Green\V20220302\Green;

$config = new Config([
    /**
     * The AccessKey of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey of an Alibaba Cloud account for API access is highly risky. We recommend that you use a RAM user for API access or O&M.
     * We strongly recommend that you do not store the AccessKey ID and AccessKey secret in your code. Otherwise, your AccessKey may be leaked, which threatens the security of all resources under your account.
     * Common methods to obtain environment variables:
     * Obtain the AccessKey ID of the RAM user: getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
     * Obtain the AccessKey secret of the RAM user: getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
     */
    "accessKeyId" => 'We recommend that you obtain the AccessKey ID of the RAM user from environment variables',
    "accessKeySecret" => 'We recommend that you obtain the AccessKey secret of the RAM user from environment variables',
    // Set the HTTP proxy.
    // "httpProxy" => "http://10.10.xx.xx:xxxx",
    // Set the HTTPS proxy.
    // "httpsProxy" => "https://10.10.xx.xx:xxxx",
    "endpoint" => "green-cip.ap-southeast-1.aliyuncs.com",
    "regionId" => "ap-southeast-1"

]);
// Note: Reuse the instantiated client as much as possible to avoid repeatedly establishing connections and improve detection performance.
$client = new Green($config);

$request = new TextModerationPlusRequest();
$request->service = "comment_multilingual_pro_global";
$serviceParameters = array("content" => "Test content");

$request->serviceParameters = json_encode($serviceParameters);

$runtime = new RuntimeOptions();
$runtime->readTimeout = 6000;
$runtime->connectTimeout = 3000;

try {
    $response = $client->textModerationPlusWithOptions($request, $runtime);
    print_r($response->body);
    if (200 != $response->statusCode) {
        print_r("response not success. code:" . $response->statusCode);
        return;
    }
    $body = $response->body;
    print_r("requestId = " . $body->requestId . "\n");
    print_r("code = " . $body->code . "\n");
    print_r("message = " . $body->message . "\n");
    if (200 != $body->code) {
        print_r("text moderation not success. code:" . $body->code);
    }
    $data = $body->data;
    print_r("data = " . json_encode($data));
} catch (TeaUnableRetryError $e) {
    var_dump($e->getMessage());
    var_dump($e->getErrorInfo());
    var_dump($e->getLastException());
    var_dump($e->getLastRequest());
}

Go SDK

1. Run the following command to import the dependencies.

go git clone --branch v2.2.11 github.com/alibabacloud-go/green-20220302/v2

2. Go SDK code example for integration.

package main

import (
	"encoding/json"
	"fmt"
	openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
	green20220302 "github.com/alibabacloud-go/green-20220302/v2/client"
	util "github.com/alibabacloud-go/tea-utils/v2/service"
	"github.com/alibabacloud-go/tea/tea"
	"net/http"
)

func main() {
	// Code leaks may lead to AccessKey leaks and threaten the security of all resources under your account. The following code is for reference only. We recommend that you use a more secure STS approach.
	config := &openapi.Config{
		/**
		 * The AccessKey of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey of an Alibaba Cloud account for API access is highly risky. We recommend that you use a RAM user for API access or O&M.
		 * We strongly recommend that you do not store the AccessKey ID and AccessKey secret in your code. Otherwise, your AccessKey may be leaked, which threatens the security of all resources under your account.
		 * Common methods to obtain environment variables:
		 * Obtain the AccessKey ID of the RAM user: os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
		 * Obtain the AccessKey secret of the RAM user: os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
		 */
		AccessKeyId: tea.String("We recommend that you obtain the AccessKey ID of the RAM user from environment variables"),
		AccessKeySecret: tea.String("We recommend that you obtain the AccessKey secret of the RAM user from environment variables"),
		// Set the HTTP proxy.
		// HttpProxy: tea.String("http://xx.xx.xx.xx:xxxx"),
		// Set the HTTPS proxy.
		// HttpsProxy: tea.String("https://username:password@xxx.xxx.xxx.xxx:9999"),
		RegionId: tea.String("ap-southeast-1"),
		Endpoint: tea.String("green-cip.ap-southeast-1.aliyuncs.com"),
		/**
		 * Set the timeout period. The server-side end-to-end processing timeout period is 10 seconds. Configure the timeout period accordingly.
		 * If you set ReadTimeout to a value less than the time required for server-side processing, your program will receive a ReadTimeout exception.
		 */
		ConnectTimeout: tea.Int(3000),
		ReadTimeout: tea.Int(6000),
	}
	client, _err := green20220302.NewClient(config)
	if _err != nil {
		panic(_err)
	}

	// Create a RuntimeObject instance and set the runtime parameters.
	runtime := &util.RuntimeOptions{}
	runtime.ReadTimeout = tea.Int(10000)
	runtime.ConnectTimeout = tea.Int(10000)

	serviceParameters, _ := json.Marshal(
		map[string]interface{}{
			"content": "Test content",
		},
	)
	request := green20220302.TextModerationPlusRequest{
		Service: tea.String("comment_multilingual_pro_global"),
		ServiceParameters: tea.String(string(serviceParameters)),
	}

	result, _err := client.TextModerationPlusWithOptions(&request, runtime)
	if _err != nil {
		panic(_err)
	}

	if *result.StatusCode != http.StatusOK {
		fmt.Printf("response not success. status:%d\n", *result.StatusCode)
		return
	}
	body := result.Body
	fmt.Printf("response success. requestId:%s, code:%d, msg:%s\n", *body.RequestId, *body.Code, *body.Message)
	if *body.Code != http.StatusOK {
		fmt.Printf("text moderation not success. code:%d\n", *body.Code)
		return
	}

	data := body.Data
	fmt.Printf("text moderation data:%s\n", *data)
}

Node.js SDK

For the source code, see Node.js SDK source code.

1. Run the following command to import the dependencies.

npm install @alicloud/green20220302@2.2.10

2. Node.js SDK code example for integration.

const Green20220302 = require('@alicloud/green20220302');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
// Note: Reuse the instantiated client as much as possible to improve detection performance. Avoid repeatedly establishing connections.
// Code leaks may lead to AccessKey leaks and threaten the security of all resources under your account. The following code is for reference only.
class Client {
    static createClient() {
        const config = new OpenApi.Config({
            // Required. Make sure the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID is set in the code running environment.
            accessKeyId: process.env['ALIBABA_CLOUD_ACCESS_KEY_ID'],
            // Required. Make sure the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET is set in the code running environment.
            accessKeySecret: process.env['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
            endpoint: `green-cip.ap-southeast-1.aliyuncs.com`,
        });
        return new Green20220302.default(config);
    }

    static async main() {
        const client = Client.createClient();
        // Construct the request object
        const textModerationPlusRequest = new Green20220302.TextModerationPlusRequest({
            // Text Enhanced Plus detection service, refer to: https://www.alibabacloud.com/help/document_detail/2684669.html#p-t7m-66g-cv6.
            "service": "comment_multilingual_pro_global",
            "serviceParameters": JSON.stringify({
                // Text to be detected. 
                "content": "Test text"})
            });
        // Create runtime configuration object
        const runtime = new Util.RuntimeOptions();
        try {
            // Send the request and get the response
            const response = await client.textModerationPlusWithOptions(textModerationPlusRequest, runtime);
            console.log(JSON.stringify(response.body));
        } catch (error) {
            // This is just for display purposes. Please handle exceptions carefully in your project. Do not simply ignore exceptions.
            // Error message
            console.log('Error occurred:', error.message);
        }
    }
}

Client.main();

C# SDK

For the source code, see C# SDK source code.

1. Run the following command to import the dependencies.

dotnet add package AlibabaCloud.SDK.Green20220302 --version 2.2.10

2. C# SDK code example for integration.

// This file is auto-generated, don't edit it. Thanks.
using Newtonsoft.Json;
namespace AlibabaCloud.SDK.Green20220302
{
    public class TextModerationPlusAutoRoute
    {
        public static void Main(string[] args)
        {
            /**
            * The AccessKey of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey of an Alibaba Cloud account for API access is highly risky. We recommend that you use a RAM user for API access or O&M.
            * We strongly recommend that you do not store the AccessKey ID and AccessKey secret in your code. Otherwise, your AccessKey may be leaked, which threatens the security of all resources under your account.
            * Common methods to obtain environment variables:
            * Obtain the AccessKey ID of the RAM user: Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID")
            * Obtain the AccessKey secret of the RAM user: Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
            */
            String accessKeyId = "We recommend that you obtain the AccessKey ID of the RAM user from environment variables";
            String accessKeySecret = "We recommend that you obtain the AccessKey secret of the RAM user from environment variables";
            // Modify the region and endpoint as needed
            String endpoint = "green-cip.ap-southeast-1.aliyuncs.com";
            //Note: Reuse the instantiated client as much as possible to avoid repeatedly establishing connections and improve detection performance.
            Client client = createClient(accessKeyId, accessKeySecret, endpoint);
            // Runtime parameter settings, only effective for requests that use this runtime parameter instance
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtimeOptions =
                new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            //Build a text detection request.
            Models.TextModerationPlusRequest textModerationPlusRequest =
                new Models.TextModerationPlusRequest();
            //Text Plus detection service example: nickname_detection_pro
          	//For supported services, refer to: https://www.alibabacloud.com/help/document_detail/2684669.html#p-t7m-66g-cv6
          	textModerationPlusRequest.Service = "comment_multilingual_pro_global";
            Dictionary<string, object> task = new Dictionary<string, object>();
            task.Add(
                "content",
                "Test text"
            );
            textModerationPlusRequest.ServiceParameters = JsonConvert.SerializeObject(task);
            try
            {
                //Call the API to get the detection result.
                Models.TextModerationPlusResponse response = client.TextModerationPlusWithOptions(
                    textModerationPlusRequest,
                    runtimeOptions
                );
                
                Console.WriteLine(response.Body.RequestId);
                Console.WriteLine(JsonConvert.SerializeObject(response.Body));
            }
            catch (Exception _err)
            {
                Console.WriteLine(_err);
            }
        }
        //Create a request client
        public static Client createClient(
            String accessKeyId,
            String accessKeySecret,
            String endpoint
        )
        {
            AlibabaCloud.OpenApiClient.Models.Config config =
                new AlibabaCloud.OpenApiClient.Models.Config
                {
                    AccessKeyId = accessKeyId,
                    AccessKeySecret = accessKeySecret,
                    //Set the HTTP proxy.
                    //HttpProxy = "http://10.10.xx.xx:xxxx",
                    //Set the HTTPS proxy.
                    //HttpsProxy = "https://username:password@xxx.xxx.xxx.xxx:9999",
                    //The endpoint to access.
                    Endpoint = endpoint,
                };
            return new Client(config);
        }
    }
}

Native HTTPS calls

• Call Method

  Service request address: https://green-cip.{region}.aliyuncs.com

  Protocol: HTTPS

  Method: POST

• Common Request Parameters

  The input parameters for Text Moderation 2.0 API operations include common request parameters and specific API request parameters. Common request parameters are parameters that every API operation uses. The following table describes the common request parameters in detail.

  Name	Type	Required	Description
  Format	String	Yes	The format of the returned message. Valid values: JSON (default) XML
  Version	String	Yes	The API version in the YYYY-MM-DD format. The version of this API is 2022-03-02.
  AccessKeyId	String	Yes	The AccessKey ID that Alibaba Cloud issues to a user for service access.
  Signature	String	Yes	The signature string. For more information about how to calculate a signature, see the signature method section below.
  SignatureMethod	String	Yes	The signature method. HMAC-SHA1 is supported.
  Timestamp	String	Yes	The timestamp of the request. The timestamp uses the ISO 8601 standard and UTC time. The format is yyyy-MM-ddTHH:mm:ssZ. For example, 2022-12-12T01:13:14Z indicates 09:13:14 on December 12, 2022 (UTC+8).
  SignatureVersion	String	Yes	The version of the signature algorithm. Set the value to 1.0.
  SignatureNonce	String	Yes	A unique random number used to prevent replay attacks. You must use a different random number for each request.
  Action	String	Yes	Text Enhanced Plus API: TextModerationPlus

• Common Response Parameters

  The system returns a unique request ID (RequestId) for each API request you send, regardless of whether the request is successful. Other response parameters include label and confidence. Different services return different parameters. For more information, see the documentation for the specific service.

• Code Examples

  The following response examples are formatted for readability. The actual response results are not formatted with line breaks or indentation.

  The following is a request example for Text Moderation 2.0 -International Business Multilingual Detection. For other API operations, refer to the specific API documentation for business input parameters:

  https://green-cip.ap-southeast-1.aliyuncs.com/ 
      ?Format=JSON
      &Version=2022-03-02
      &Signature=vpEEL0zFHfxXYzSFV0n7%2FZiFL9o%3D
      &SignatureMethod=Hmac-SHA1
      &SignatureNonce=15215528852396
      &SignatureVersion=1.0
      &Action=TextModerationPlus
      &AccessKeyId=123****cip
      &Timestamp=2022-12-12T12:00:00Z
      &Service=comment_multilingual_pro_global
      &ServiceParameters={"content": "Test text"}

  The following is a JSON code example of the response parameters for Text Moderation 2.0 -International Business Multilingual Detection:

  {
      "Code": 200,
      "Data": {
          "Result": [
              {
                  "Label": "political_entity",
                  "Description":"Suspected political entity",
                  "Confidence": 100.0,
                  "RiskWords": "Word A,Word B,Word C"
              },
              {
                  "Label": "political_figure",
                  "Description":"Suspected political figure",
                  "Confidence": 100.0,
                  "RiskWords": "Word A,Word B,Word C"
              }
          ],
          "RiskLevel": "high"
      },
      "Message": "OK",
      "RequestId": "AAAAAA-BBBB-CCCCC-DDDD-EEEEEEEE****"
  }

• Signature Method

  The Text Moderation 2.0 service authenticates each access request. Therefore, each request must include signature information. The Text Moderation 2.0 service uses the AccessKey ID and AccessKey secret to implement symmetric encryption and verify the identity of the request sender.

  The AccessKey ID and AccessKey secret are officially issued to you by Alibaba Cloud (you can apply for and manage them on the Alibaba Cloud website). The AccessKey ID is used to identify the user. The AccessKey secret is the key used to encrypt the signature string and verify the signature string on the server. You must keep your AccessKey secret strictly confidential. Only you and Alibaba Cloud know it.

  When you access the service, follow these steps to sign the request:

  1. Use request parameters to construct a canonicalized query string.

     1. Sort all request parameters (including the common request parameters and custom parameters of the API operation, but excluding the Signature parameter) in alphabetical order.

     2. Encode the names and values of the request parameters. The names and values must be URL-encoded in UTF-8.

        Note

        Generally, URL encoding libraries (such as java.net.URLEncoder in Java) encode according to the rules of the application/x-www-form-urlencoded MIME type. You can directly use this method for encoding, then replace the plus sign (+) with %20, the asterisk (*) with %2A, and %7E with the tilde (~) in the encoded string to obtain the encoded string described by the above rules.

        The URL encoding rules are as follows:

        • Characters A-Z, a-z, 0-9, and characters hyphen (-), underscore (_), period (.), and tilde (~) are not encoded.

        • Other characters are encoded in the format of %XY, where XY is the hexadecimal representation of the ASCII code of the character. For example, the encoding for the double quotation mark (") is %22.

        • Extended UTF-8 characters are encoded in the format of %XY%ZA….

        • It should be noted that the space character ( ) must be encoded as %20, not as a plus sign (+).

     3. Connect the marshaled parameter names and values with an equal sign (=).

     4. Connect the strings with equal signs in alphabetical order of parameter names using the & symbol to form the canonicalized query string.

  2. Use the canonicalized string constructed in a.i to create the string for calculating the signature according to the following rules.

     StringToSign=
     HTTPMethod + "&" +
     percentEncode（"/"） + "&" +
     percentEncode（CanonicalizedQueryString）

     Note

     Where HTTPMethod is the HTTP method used to submit the request, such as POST. percentEncode (/) is the value obtained by encoding the character (/) according to the URL encoding rules described in a.ii, which is %2F. percentEncode (CanonicalizedQueryString) is the string obtained by encoding the canonicalized query string constructed in a.i according to the URL encoding rules described in a.ii.

  3. According to the definition in RFC2104, calculate the signature HMAC value using the string for signing above.

     Note

     Note that the key used for calculating the signature is the user's AccessKey Secret with an & character (ASCII: 38) appended to it. The hash algorithm used is SHA1.

  4. Encode the HMAC value above into a string according to Base64 encoding rules to obtain the signature value (Signature).

  5. Add the obtained signature value as the Signature parameter to the request parameters to complete the request signing process.

     Note

     When submitting the obtained signature value as the final request parameter value to the Content Moderation server, you must URL encode it according to RFC3986 rules, just like other parameters.