文档审核增强版帮助您检测常见文档中的风险或违规内容。本文介绍了使用API接口进行文档审核增强版的方法。
接入指引
注册阿里云账号:立即注册,按照操作提示完成账号注册。
开通内容安全按量付费:请确保已开通服务,具体操作,请参见开通服务。开通不收费,接口接入使用后系统会按使用量自动出账。您也可以购买按量抵扣资源包,资源包相较于后付费存在一定阶梯抵扣,适合使用量级可预期和较大的用户,具体信息,请参见购买按量抵扣资源包。
创建AccessKey:请确保您已通过RAM创建AccessKey,具体操作,请参见创建AccessKey。如果您使用的是RAM用户(子账号)AccessKey,您需要通过阿里云账号(主账号)给RAM用户赋予AliyunYundunGreenWebFullAccess权限,具体操作,请参见RAM授权。
开发接入:推荐使用SDK方式调用。具体信息,请参见文档审核增强版SDK及接入指南。
提交审核任务
接口说明
业务接口:FileModeration,文档仅提供异步检测接口。
支持的地域及接入地址:
地域
外网接入地址
内网接入地址
支持的服务
华东2(上海)
green-cip.cn-shanghai.aliyuncs.com
green-cip-vpc.cn-shanghai.aliyuncs.com
document_detection
华北2(北京)
green-cip.cn-beijing.aliyuncs.com
green-cip-vpc.cn-beijing.aliyuncs.com
华东1(杭州)
green-cip.cn-hangzhou.aliyuncs.com
green-cip-vpc.cn-hangzhou.aliyuncs.com
计费信息:
该接口为收费接口,会根据检测文档页数计费。
检测对象:支持检测常见文档。
返回结果:异步检测任务不会实时返回检测结果,您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留24小时。
callback获取检测结果:提交异步检测任务时,在请求参数中传入callback参数,用来自动接收检测结果。
轮询获取检测结果:提交异步检测任务时,无需传入callback参数;提交异步检测任务后,调用结果查询接口获取检测结果。
文档要求:
文档链接支持以下协议:HTTP和HTTPS。
文档支持以下格式:DOC、DOCX、PPT、PPTX、PPS、PPSX、PDF、XLS、XLSX、XLTX、XLTM、HTML、TXT(UTF-8编码)。
文档大小限制:单个文档不超过200 MB。如果超过200 MB,需要对文档进行压缩或拆分处理。
文档检测的时间依赖于文档的下载时间。请保证被检测的文档所在的存储服务稳定可靠,建议您使用阿里云OSS存储服务存储文档。
检测规则配置:
初次调用时请在内容安全控制台进行文档审核规则设置。如果您不设置,文档审核增强版API会采用默认配置。
QPS限制
本接口的单用户QPS限制为100次/秒,并发审核路数限制为20路(即同一时间只能处理20个任务)。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。
调试
在接入前,您也可以通过阿里云OpenAPI在线调试接口,查看调用示例代码及SDK依赖信息,方便概览接口的使用方法和参数。
在线调试能力是基于当前登录账号调用内容安全的API接口,因此调用量会计入账号的收费用量中。
请求参数
名称 | 类型 | 是否必须 | 示例值 | 描述 |
Service | String | 是 | document_detection | 审核服务类型。如下:
|
ServiceParameters | JSONString | 是 | 审核服务需要的参数集。JSON字符串格式,关于每个字符串的描述,请参见表1 ServiceParameters。 |
表1 ServiceParameters
名称 | 类型 | 是否必选 | 示例值 | 描述 |
url | String | 是 | http://www.aliyundoc.com/a.pdf | 待检测对象的URL,请确保该URL能通过公网访问到,且URL地址长度不超过2048个字符。 说明 URL地址中不能包含中文,且一次请求请确保仅传入1条URL。 |
docType | String | 否 | 如果url提供的文档是无后缀文件,需要指定文档格式,取值为doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。 说明 当文档类型是txt格式时,仅会检测文本内容,不会截图检测图像内容,建议txt格式文档直接提取文本调用文本审核增强版服务。 | |
callback | String | 否 | http://www.aliyundoc.com | 检测结果回调通知您的URL,支持使用HTTP和HTTPS协议的地址。该字段为空时,您必须定时轮询检测结果。 callback接口必须支持POST方法、UTF-8编码的传输数据,以及表单参数checksum和content。 内容安全按照以下规则和格式设置checksum和content,调用您的callback接口返回检测结果。
说明 您的服务端callback接口收到内容安全推送的结果后,如果返回的HTTP状态码为200,则表示接收成功,其他的HTTP状态码均视为接收失败。接收失败时,内容安全将最多重复推送16次检测结果,直到接收成功。重复推送16次后仍未接收成功,则不再推送,建议您检查callback接口的状态。 |
seed | String | 否 | abc**** | 随机字符串,该值用于回调通知请求中的签名。 由英文字母、数字、下划线(_)组成,不超过64个字符。由您自定义,用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。 说明 当使用callback时,该字段必须提供。 |
cryptType | String | 否 | SHA256 | 使用回调通知时(callback),设置对回调通知内容进行签名的算法。内容安全会将返回结果(由用户uid + seed + content拼接的字符串)按照您设置的加密算法计算签名,再发送到您的回调通知地址。取值:
|
dataId | String | 否 | fileId**** | 检测对象对应的数据ID。 由大小写英文字母、数字、下划线(_)、短划线(-)、英文句号(.)组成,不超过128个字符,可以用于唯一标识您的业务数据。 |
返回数据
名称 | 类型 | 示例值 | 描述 | |
Code | Integer | 200 | 状态码,和HTTP状态码一致。更多信息,请参考Code说明。 | |
Data | JSONObject | 审核结果数据。 | ||
TaskId | String | AAAAA-BBBBB | 检测的任务ID。 | |
Message | String | OK | 请求消息的响应消息。 | |
RequestId | String | ABCD1234-1234-1234-1234-123**** | 请求ID。 |
示例
请求示例
{
"Service": "document_detection",
"ServiceParameters":
{
"url": "http://www.aliyundoc.com/a.pdf",
"dataId": "fileId****"
}
}
正常返回示例
{
"Msg": "OK",
"Code": 200,
"Data":
{
"TaskId": "AAAAA-BBBBB-CCCCCCCC"
},
"RequestId": "ABCD1234-1234-1234-1234-123****"
}
获取文档审核任务结果
接口说明
业务接口:DescribeFileModerationResult,表示获取文档审核任务结果。
计费信息:该接口不计费。
查询超时:建议您将查询间隔设置为30秒(即在提交异步检测任务30秒后查询结果),最长不能超出24小时,否则结果将会自动删除。
QPS限制
本接口的单用户QPS限制为100次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。
调试
在接入前,您也可以通过阿里云OpenAPI在线调试接口,查看调用示例代码及SDK依赖信息,方便概览接口的使用方法和参数。
请求参数
名称 | 类型 | 是否必选 | 示例值 | 描述 |
Service | String | 是 | document_detection | 审核服务类型,需要和提交审核任务的审核服务类型保持一致。 |
ServiceParameters | JSONString | 是 | 审核服务需要的参数集。JSON字符串格式,关于每个字符串的描述,请参见表1 ServiceParameters。 |
表1 ServiceParameters
名称 | 类型 | 是否必选 | 示例值 | 描述 |
taskId | string | 是 | abcd**** | 要查询的检测任务的taskId,每次支持输入一个taskId。 说明 您在提交检测任务后,可以从返回数据中获取检测任务的taskId。 |
返回数据
名称 | 类型 | 示例值 | 描述 |
RequestId | String | ABCD1234-1234-1234-1234-123**** | 本次调用请求的ID,是由阿里云为该请求生成的唯一标识符,可用于排查和定位问题。 |
Data | Object | 文档内容检测结果。更多信息,请参见 表2 Data。 | |
Code | String | 200 | 状态码,和HTTP状态码一致。更多信息,请参考Code说明。 |
Message | String | OK | 本次请求的响应消息。 |
表2 Data
名称 | 类型 | 示例值 | 描述 |
DataId | String | fileId**** | 检测对象对应的数据ID。 说明 如果在检测请求参数中传入了DataId,则此处返回对应的DataId。 |
Url | String | http://www.aliyundoc.com/a.docx | 检测对象的URL。 |
DocType | String | 无后缀文件指定的格式,取值doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt。 | |
PageResult | JSONArray | 文档页检测结果,调用成功时(code=200),返回结果中包含一个结构体,具体结构,请参见表3 PageResult。 说明 code返回280表示在检测中,返回200表示检测完成。在检测中状态时,检测结果中包含从开始检测到当前时间的检测到结果。 |
表3 PageResult
名称 | 类型 | 示例值 | 描述 |
PageNum | Integer | 50 | 当前文档页数。 |
ImageUrl | String | http://oss.aliyundoc.com/a.png | 当前页截图url链接。 |
ImageResult | JSONArray | 当前页图片检测结果。具体结构描述,请参见表4 ImageResult。 说明 当文档文件是txt格式时,无图片检测结果。 | |
TextResult | JSONArray | 当前页文字检测结果。具体结构描述,请参见表6 TextResult。 |
表4 ImageResult
名称 | 类型 | 示例值 | 描述 |
Description | String | 对文档页面的图像内容审核 | 图片部分描述 |
Service | String | baselineCheck | 图片部分调用的服务 |
Location | JSONObject | {"x":0,"y":0,"w":100,"h":100} | (预留)图片部分坐标 |
LabelResult | JSONArray | 图片部分返回标签。具体结构描述,请参见表5 LabelResult。 |
表5 LabelResult
名称 | 类型 | 示例值 | 描述 |
Label | String | violent_explosion | 图片检测运算后返回的标签。同一张截图可能会检出多个标签和分值。具体参考图片审核增强版同步检测API。 |
Confidence | Float | 81.22 | 置信分值,0到100分,保留到小数点后2位。 |
表6 TextResult
名称 | 类型 | 示例值 | 描述 |
Description | String | 对文档页面的文字内容审核 | 文本部分描述 |
Service | String | pgc_detection | 文本部分调用的服务 |
Text | String | 这里是文字部分 | 文本部分内容 |
Labels | String | ad_compliance,C_customized | 文本部分返回标签,具体参考文本审核增强版API。 |
RiskWords | String | 风险词A,风险词B | 文本部分返回风险词 |
RiskTips | String | 广告法_通用禁用极限词 | 文本部分返回细分标签 |
示例
请求示例
{
"service": "document_detection",
"serviceParameters": {
"taskId": "abcd****"
}
}
正常返回示例
{
"Code": 200,
"Data": {
"DataId": "fileId*****",
"PageResult": [
{
"ImageResult": [
{
"Description": "对文档页面的图像内容审核",
"LabelResult": [
{
"label": "nonLabel"
}
],
"Service": "baselineCheck"
}
],
"ImageUrl": "http://oss.aliyundoc.com/a.png",
"PageNum": 1,
"TextResult": [
{
"Description": "对文档页面的文字内容审核",
"Labels": "",
"RiskTips": "",
"RiskWords": "",
"Service": "pgc_detection",
"Text": "内容安全产品测试用例a"
}
]
},
...
{
"ImageResult": [
{
"Description": "对文档页面的图像内容审核",
"LabelResult": [
{
"Confidence": 89.01,
"Label": "pornographic_adultContent_tii"
}
],
"Service": "baselineCheck"
}
],
"ImageUrl": "http://oss.aliyundoc.com/b.png",
"PageNum": 10,
"TextResult": [
{
"Description": "对文档页面的文字内容审核",
"Labels": "contraband,sexual_content",
"RiskTips": "违禁_违禁商品,色情_影视资源,色情_低俗",
"RiskWords": "风险词A,风险词B",
"Service": "ad_compliance_detection",
"Text": "内容安全产品测试用例b"
}
]
}
],
"Url": "http://www.aliyundoc.com/a.docx"
},
"Message": "SUCCESS",
"RequestId": "1D0854A7-AAAAA-BBBBBBB-CC8292AE5"
}
Code说明
以下为文档审核增强版接口返回Code的含义说明,系统仅对Code返回为200和280的请求计量计费,其他Code不会计费。
Code | 说明 |
200 | 请求正常或者检测完成。 |
280 | 检测中。 |
400 | 请求参数为空。 |
401 | 请求参数错误。 |
402 | 请求参数长度不符合接口规定,请检查并修改。 |
403 | 请求超过QPS限制,请检查并调整并发。 |
404 | 传入文件下载遇到错误,请检查或重试。 |
405 | 传入文件下载或者转换超时,可能是因为链接无法访问,请检查调整后重试。 |
406 | 传入的文件过大,请检查调整文件大小后再重试。 |
407 | 传入的文件格式暂不支持,请检查调整后重试。 |
408 | 该账号无权限调用该接口,可能是账号未开通或者已欠费,或者调用账号未被授权访问。 |
409 | 传入的RequestId不存在,可能是结果已经超过24小时有效期。 |
480 | 检测并发路数超过限制,请检查并调整并发。 |
500 | 系统异常。 |