单条内容审查

介绍如何调用接口在WebService应用通道中进行单条内容的审查。

请求方式

POST

接口地址URL

/skg/v1/dlp/channel/webserviceapp/<WebService应用ID>/<请求模式>

请求参数

以下表格对接口地址中的参数做了介绍。
参数名称 参数位置 是否必须 描述
<WebService应用ID> URL参数 是 WebService的应用ID。登录统一内容安全管理平台UCSS，并进入DLP管理 > 策略元素 > WebService应用页面，在页面列表的ID栏中，查找对应的WebService ID。

Note: WebService ID需要绑定到数据防泄漏DLP策略中才能生效。

具体绑定步骤如下：
  1. 在UCSS > DLP管理 > 策略元素 > WebService应用页面，点击添加按钮，添加一个WebService应用，仅填写名称即可。添加完成后会自动生成ID。
  2. 在DLP管理 > 策略页面，选择编辑或新建一个策略。
  3. 点击下方的来源/目标选项卡，点击添加匹配，在下拉菜单中，点击目标。
  4. 在添加目标匹配页面，在条件行，选择添加目标。在选项的最后面，勾选WebService应用，点击添加按钮，将刚刚创建的WebService加入进来。
  5. 点击确定保存匹配设置。再次点击确定保存策略。
<请求模式> URL参数 是 指定请求模式为同步或异步。具体参数值包括：
  • sync
  • async

以下表格对请求头的参数做了介绍。

元数据参数

metadata参数定义

参数名 类型 适用状态 说明
user String(必选) 同步和异步 生成事件的用户名 - 支持域用户，格式为域名\用户名。
customAttribute String(可选) 同步和异步 支持用户自定义的参数名。
filename String(可选) 同步和异步 文件名 - 可做根据文件名设置的策略匹配
注： 如果你使用的产品版本为3.3，那么filename为必选项
encoding String(可选) 同步和异步 文件编码
queryID String(必选) 同步和异步 与此请求关联的事件查询ID，保持唯一。若请求无事件生成则无法查询到事件详情。
注： queryid的值对应于第三方云服务中的流量UUID。
redaction Dict(可选） 同步和异步 脱敏功能相关。是否开启脱敏功能。具体的脱敏设置，请查阅sendBack参数。
 "redaction": {
        "enable": true # 当enable的值为true时，脱敏请求才生效
  }
sendBack Dict(可选） 同步和异步 脱敏功能相关。脱敏后内容的处理。
注： 如需使用脱敏功能，请将redaction参数值设置为true。

该字段要求输入一个必选的type属性，表示返回文件的方式，Type属性支持以下选项：

response：将脱敏后的内容返回至当前路径

httpUpload：将脱敏后的内容发送至指定URL

s3：将脱敏后的内容上传至Amazon S3存储空间

注： 此步骤同样适用于存储到Swift、COS、OSS等存储服务。具体相关配置参数，请参考章节异步模式下审查云服务存储内容的objectinfo参数。
  • response：将脱敏后的内容返回至当前路径。以下为代码示例：
      "sendBack": {
    "type": "response" # 将脱敏后的内容返回至当前路径
  },
  • httpUpload：将脱敏后的内容发送至指定URL。以下为代码示例：
     "sendBack": {
    "type": "httpUpload",
    "url": "http://172.11.11.6/callback" # 将脱敏后的内容返发送至该url
  },
  • S3：将脱敏后的内容上传至云存储。以下为适用于S3的代码示例：
     "sendBack": {
        "type": "s3",
        "s3Bucket": "test",
        "s3Region": "", # 将脱敏后的文件上传到该位置。此处的值为使用s3时的region name，
# 如果运行在EC2上并使用AWS IAM role，则以下三项可省略，则以下三项accessKey、secretKey、endpointUrl可省略
        "accessKey": "aws_accessKey",
        "secretKey": "aws_secretKey",
        "endpointUrl": ""
  },
md5 String(可选) 同步和异步 文件MD5值，用于记录和缓存加速。支持MD5和文档一同送检，也支持仅送检MD5。
"md5":"09e066b382d4225de3c0594aa89b5fi"
operation int(可选) 同步和异步 操作ID。创建WebService应用时定义，在API流量日志的Webservice操作字段中将会显示操作ID对应的操作名称。默认有以下四种，用户也可以自定义：
  • 1 - 读取
  • 2 - 写入
  • 3 - 添加
  • 4 - 删除
antivirus Bool(可选) 同步和异步 是否进行病毒检查，默认为False。
md5 String(可选) 同步和异步 文件MD5值，仅用于记录。
callback_url String(可选) 异步 只限于异步模式填写，call back的监听地址
uploadtype String(必选) 异步 只限于异步。支持AWS S3、阿里云OSS、腾讯云COS、Swift等云存储，以及本地文件和下载URL。
  • swift
  • oss
  • cos
  • s3
  • file
  • http
objectInfo Dict(可选） 异步 只限于异步模式并使用对象存储时使用。异步模式支持审查存储在亚马逊S3、Swfit、阿里云OSS、腾讯云COS等云服务的对象存储。具体设置参数，参阅章节：异步模式下审查云服务存储内容的objectinfo参数

返回参数

内容审查请求返回结果中包含以下参数：

名称 描述
result 请求是否成功，成功为0，失败为1
actionCode 请求成功时，用户可选择对符合请求条件的内容进行默认操作，默认操作包括1-允许数据传输和2-阻断数据传输
errorCode 请求失败时返回的错误代码
message 请求失败时返回的错误消息

Python请求示例 - WebService通道（同步模式）

以下示例为使用Python代码调用接口，以在同步模式下，对WebService通道中的文件进行内容安全审查。

注： 在如下Python代码示例中，导入的Header文件ucwi_config 和 ucwi_auth的需事先创建，如需详细参考示例，请参阅Header文件示例。
注： 在如下Python代码示例中，app_id为WebService应用ID，如需获取该ID，参照获取WebService应用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/{}/sync".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    "user": "ucwitestuser",
}

headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
    "request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()

if response.status_code != 200:
    print("Bad request, response code:", response.status_code)
    print(response.text)
else:
    result = response.json()
    # print(json.dumps(result, indent=4).decode('raw_unicode_escape'))
    if result["responseCode"] != 200:
        print("Bad request, response code:", result["responseCode"])
        print(result["message"])
    else:
        hint = "# 1:允许； 2：阻断；3：确认；4：删除附件；5：邮件加密；6：邮件隔离；7：终端系统加密；8：邮件内容加密；9：终端个人密钥加密"
        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请求示例 - WebService通道（异步模式）

以下示例为使用Python代码调用接口，以在异步模式下，上传WebService通道中的文件，以供内容安全审查。

注： 在如下Python代码示例中，导入的Header文件ucwi_config 和 ucwi_auth的需事先创建，如需详细参考示例，请参阅Header文件示例。
注： 在如下Python代码示例中，app_id为WebService应用ID，如需获取该ID，参照获取WebService应用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)

# 从UCSS上获取webserviceapp的id
app_id = "caafb22a-9f6d-4a06-a0e4-b12c170afdf5"
api = "/skg/v1/dlp/channel/webserviceapp/{}/async".format(app_id)
url = "{0}{1}".format(UCWIConfig.base_url, api)
file_path = "test.txt"

metadata = {
    # 数据是哪个用户发送的，用于检查时匹配策略和最后事件的显示
    "user": "ucwitestuser",
    # 上传文件的文件名，用于检查时匹配策略
    "filename": "test.txt",
    "queryID": str(uuid.uuid4()),
    # 可选参数，文件的编码方式，默认是UTF-8
    "encoding": "UTF-8",
    # 可选参数，是否执行反病毒操作，默认是False
    "antivirus": False,
    # 可选参数，默认为空字符串，用于最后事件的显示   
    "md5": "09e066b382d4225de7f3c0594aa89b5f",
    "uploadtype": "file",
    "callback_url": UCWIConfig.callback_url + "/webserviceapp"
}

headers = get_headers()
data = {"metadata": json.dumps(metadata)}
fd = open(file_path)
files = {
    "request": fd
}
response = requests.post(url, headers=headers, data=data, files=files, verify=False)
fd.close()

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

cURL请求示例 - WebService应用通道 （异步模式）

以下示例为使用cURL代码调用接口，以在异步模式下，上传WebService通道中的文件，以供内容安全审查。

以下示例适用于上传类型为S3的情况：
  • 带callback：
    curl -F 'metadata={"uploadtype": "s3", "callback_url": "http://172.22.113.12:9999/post/webserviceapp", "queryID": "000864b0-4b2c-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=http://172.22.78.91:8070/test-webserviceapp/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
  • 不带callback：
    curl -F 'metadata={"uploadtype": "s3", "queryID": "000864b0-4b2c-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=http://172.22.78.91:8070/test-webserviceapp/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
以下示例适用于上传类型为localhost的情况：
  • 带callback：
    curl -F 'metadata={"uploadtype": "localhost", "callback_url": "http://172.22.113.12:9999/post/webserviceapp", "queryID": "44130fdc-4b2e-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0410user1", "filename": "DLPencrypt.rar"}' 
-F 'request=@/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async
  • 不带callback：
    curl -F 'metadata={"uploadtype": "localhost","queryID": "44130fdc-4b2e-11e7-81f7-9ef3ee527981", "user": "hwshtest1\\hwsh0601user1", "filename": "DLPencrypt.rar"}' 
-F 'request=@/home/test/testfile4/DLPencrypt.rar' https://172.22.78.107:5443/skg/v1/dlp/channel/webserviceapp/e4dbd0d7-2fc6-4034-b4d8-3807af66bf91/async

返回示例

内容审查请求的回复如下。

  • 请求成功：
    {
"result" : 0,
"actionCode" : 1/2
}
actionCode: 1 - allow, 2 - block
    注： 若匹配策略，发现违规内容，系统还将返回策略匹配信息，具体请参照送检策略匹配返回值定义
  • 请求失败：
    {
"result" : 1,
"errorCode" : 500,
"message" : "Invalid parameter"
}