Review Text Message

Introduces how to call the interface to perform content review of text content in the WebService application channel.

Request method

POST
URL

Interface Address

/skg/v1/dlp/channel/webserviceapp/<WebService Application ID>/<Text Request Mode>

Request Parameters

Parameter Name Parameter Location Required Description
<WebService Application ID> URL Parameter Yes ID of the WebService application.
<Text Request Mode> URL Parameter Yes Specify the request mode of the text content as synchronous or asynchronous.
  • message_sync
  • message_async

Metadata Parameters

Supports scanning of text content.

Definition of metadata parameters.

Parameter Name Type Applicable Status Description
user String (Required) Synchronous and Asynchronous User name that generates the event - supports domain users, in the format domain\username.
customAttribute String (Optional) Synchronous and Asynchronous Supports user-defined parameter names.
queryID String (Required) Synchronous and Asynchronous Event query ID associated with this request, must be unique. If the request does not generate an event, the event details cannot be queried.
Note: queryid corresponds to the traffic UUID in the third-party cloud service.
redaction Dict (Optional) Synchronous and Asynchronous Related to redaction functionality. Whether to enable redaction. For specific redaction settings, please refer to the sendBack parameter.
"redaction": {
    "enable": true # Redaction request takes effect when enable is true
}
sendBack Dict (Optional) Synchronous and Asynchronous Related to redaction functionality. Handling of redacted content.
Note: To use the redaction feature, set the value of the redaction parameter to true.

This field requires an input of a required type attribute, indicating the way the file is returned. The Type attribute supports the following options:

response: Return the redacted content to the current path

httpUpload: Send the redacted content to the specified URL

s3: Upload the redacted content to Amazon S3 storage

Note: This step also applies to storage in Swift, COS, OSS, etc. For specific related configuration parameters, please refer to the section objectinfo Parameters for Reviewing Cloud Service Stored Content in Asynchronous Mode.
  • response: Return the redacted content to the current path. The following is a code example:
    "sendBack": {
        "type": "response" # Return the redacted content to the current path
    },
  • httpUpload: Send the redacted content to the specified URL. The following is a code example:
    "sendBack": {
        "type": "httpUpload",
        "url": "http://172.11.11.6/callback" # Send the redacted content to this url
    },
  • S3: Upload the redacted content to cloud storage. The following is a code example applicable to S3:
    "sendBack": {
        "type": "s3",
        "s3Bucket": "test",
        "s3Region": "", # Upload the redacted file to this location. The value here is the region name when using s3.
        # If running on EC2 and using AWS IAM role, the following three items can be omitted, then the following three accessKey, secretKey, endpointUrl can be omitted
        "accessKey": "aws_accessKey",
        "secretKey": "aws_secretKey",
        "endpointUrl": ""
    },
operation int (Optional) Synchronous and Asynchronous Operation ID. Defined when creating the WebService application, and the operation name corresponding to the operation ID will be displayed in the Webservice Operation field of the API traffic log. There are four defaults, and users can also define their own:
  • 1 - Read
  • 2 - Write
  • 3 - Add
  • 4 - Delete
encoding String (Optional) Synchronous and Asynchronous File encoding
uploadtype String (Required) Asynchronous Only for asynchronous. Supports local files.
  • file
callback_url String (Optional) Asynchronous Only for asynchronous mode to fill in the callback function's url

Request Examples

The following examples show how to call the interface to send text content to Unified Content Web-Service Inspector (UCWI) for content security inspection in both synchronous and asynchronous modes.

  • In synchronous mode:
    POST /skg/v1/dlp/channel/webserviceapp/appid/message_sync
    Content-Type: multipart/form-data; boundary=${bound}
    --${bound}
    Content-Disposition: form-data; name="metadata"
    Content-Type: application/json
    {
        "user":"abc\enduser1",
        "queryID":"cd2fd109-c4d4-489f-9b27-53752f7827d6",
    }
    --${bound}
    Content-Disposition: form-data; name="inspectContent";
    Content-Type: text/plain
    %Message Content%
  • In asynchronous mode:
    POST /skg/v1/dlp/channel/webserviceapp/appid/message_async
    Content-Type: multipart/form-data; boundary=${bound}
    --${bound}
    Content-Disposition: form-data; name="metadata"
    Content-Type: application/json
    {
        "user":"abc\enduser1",
        "queryID":"cd2fd109-c4d4-489f-9b27-53752f7827d6",
        "callback_url":"http://172.22.113.49:5000/post/webserviceapp "
    }
    --${bound}
    Content-Disposition: form-data; name="inspectContent";
    Content-Type: text/plain
    %Message Content%

Python Request Example - WebService Channel (Synchronous Mode)

The following example shows how to use Python code to call the interface to upload text content in the WebService channel for content security review in synchronous mode.

Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
Note: In the following Python code example, app_id is the WebService application ID. To obtain this ID, refer to Obtaining WebService Application ID.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import uuid

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

app_id = "caafb22a-9f6d-4a06-a0e4-b12c170afdf5"
api = "/skg/v1/dlp/channel/webserviceapp/{}/message_sync".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    "user": "ucwitestuser",
    # The user sending the data, used for policy matching during content security review, and event display after content security review is completed
    "queryID": str(uuid.uuid4()),
    "origin_filename": file_path
}

with open(file_path) as f:
    content = f.read()
    # The content to be checked

headers = get_headers()
data = {
    "metadata": json.dumps(metadata),
    "inspectContent": content,
}

response = requests.post(url, headers=headers, data=data, verify=False)

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    result = response.json()
    if result["responseCode"] != 200:
        print("Bad request, response code:", result["responseCode"])
        print(result["message"])
    else:
        hint = "# 1: Allow; 2: Block; 3: Confirm; 4: Delete Attachment; 5: Email Encryption; 6: Email Quarantine; 7: Terminal System Encryption; 8: Email Content Encryption; 9: Terminal Personal Key Encryption"
        print("action:{}    {}".format(result["actionCode"], hint))
        if len(result["incident_info"]) == 0:
            print("not matched.")
        else:
            print("matched policy:")
            for policy in result["incident_info"]["matchedPolicies"]:
                print(json.dumps(policy, indent=2).encode('utf-8').decode('raw_unicode_escape'))

Python Request Example - WebService Channel (Asynchronous Mode)

The following example shows how to use Python code to call the interface to upload text content in the WebService channel for content security review in asynchronous mode.

Note: In the following Python code example, the imported header files ucwi_config and ucwi_auth need to be created beforehand. For detailed reference examples, see Header File Examples.
Note: In the following Python code example, app_id is the WebService application ID. To obtain this ID, refer to Obtaining WebService Application ID.
# -*- coding: utf-8 -*-
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from ucwi_config import UCWIConfig
from ucwi_auth import get_headers
import requests
import json
import os
import uuid

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

app_id = "caafb22a-9f6d-4a06-a0e4-b12c170afdf5"
api = "/skg/v1/dlp/channel/webserviceapp/{}/message_async".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    "user": "ucwitestuser",
    # The user sending the data, used for policy matching during content security review, and event display after content security review is completed
    "origin_filename": file_path,
    # The filename of the uploaded file, used for policy matching during content security review
    "queryID": str(uuid.uuid4()),
    # The UUID associated with this request, must be unique, used for event query in asynchronous mode
    #"encoding": "UTF-8",
    # Optional parameter, file encoding, default is UTF-8
    #"antivirus": False,
    # Optional parameter, whether to perform antivirus check, default value is False, i.e., ignore, change to True if antivirus check is needed
    #"md5": "09e066b382d4225de7f3c0594aa89b5f",
    # Optional parameter, default is an empty string, used for event display after content security review is completed
    "uploadtype": "file",
    "callback_url": UCWIConfig.callback_url + "/webserviceapp"
}

# The content to be checked
with open(file_path) as f:
    content = f.read()

headers = get_headers()
data = {
    "metadata": json.dumps(metadata),
    "inspectContent": content
}

response = requests.post(url, headers=headers, data=data, verify=False)

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    result = response.json()
    print(result["message"])

Return Parameters

Including the following:

Name Description
result Indicates whether the request was successful. 0 for success, 1 for failure.
actionCode When the request is successful, the user can choose to perform a default action on the content that meets the request conditions. Default actions include 1 - Allow data transfer and 2 - Block data transfer.
errorCode The error code returned when the request fails.
message The error message returned when the request fails.

Example for return code

The Content inspection request returns the following parameters in the results:
Full Name Description
result Whether the request is successful, 0 means success, and 1 means failure.
actionCode When the request is successful, the user can choose a remediation action on the detected content. The default operations include 1-allow data transmission and 2-block data transmission.
errorCode Error code returned when the request failed
message Error Message returned when the request failed

The response to the Content inspection request is as follows.

  • Request successfully
    {
    "result" : 0,
    "actionCode" : 1/2
    }
    actionCode: 1 - allow, 2 - block
    Note: If the policy is matched and the violation content is found, the system returns the policy matching information. Refer to The return value for policy match.
  • Request failed
    {
    "result" : 1,
    "errorCode" : 500,
    "message" : "Invalid parameter"
    }

Error code

If calling the API has an error, the following error codes are returned:
Error Code Description
400 Invalid parameter
404 Unknown Error
500 Invalid parameter