URL风险异步检测API

内容安全URL风险检测能力,帮助用户识别第三方URL链接是否存在欺诈、色情、赌博等风险,守护平台内容生态。本文介绍使用异步API接口进行URL风险检测的方法。

接入指引

  1. 注册阿里云账号:立即注册,按照操作提示完成账号注册。

  2. 开通内容安全按量付费:请确保您已开通服务,开通不收费,接口接入使用后系统会按使用量自动出账,详情请参见计费说明。您也可以购买按量抵扣资源包,资源包相较于后付费存在一定阶梯抵扣,适合使用量级可预期和较大的用户。

  3. 创建AccessKey:请确保您已通过RAM创建AccessKey,如果您使用的是子账号AccessKey,您需要通过主账号给子账号赋予AliyunYundunGreenWebFullAccess权限,具体操作,请参见RAM授权

  4. 开发接入:推荐使用SDK方式调用,具体方法请详见URL风险检测接入指南

  5. URL风险检测异步服务包含以下2个接口:

    • UrlAsyncModeration:提交URL风险检测任务

    • DescribeUrlModerationResult:获取URL风险检测结果

提交审核任务

使用说明

  • 业务接口:UrlAsyncModeration

  • 支持的地域及接入地址:

地域

外网接入地址

内网接入地址

支持服务

华东2(上海)

https://green-cip.cn-shanghai.aliyuncs.com

https://green-cip-vpc.cn-shanghai.aliyuncs.com

url_detection_pro

  • 计费信息

    该接口为收费接口。仅对HTTP状态码为200的请求进行计量计费,产生其他错误码时不会计费。关于计费方式,请参见URL风险检测介绍及计费说明

  • 返回结果:异步检测任务不会实时返回检测结果,您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留3天。

    • callback获取检测结果:提交异步检测任务时,在请求参数中传入callback参数,用来自动接收检测结果。

    • 轮询获取检测结果:提交异步检测任务时,无需传入callback参数;提交异步检测任务后,调用结果查询接口获取检测结果。异步检测当前为排队检测,结果会在24小时内检测完毕。

  • 支持URL格式

    URL风险检测服务支持符合以下格式的URL地址:http(s)://{IP或域名}{:端口}{/路径}

    说明
    1. URL地址可以没有HTTP或HTTPS前缀

    2. 域名部分是数字、字母组成,英文点号分隔,一级域名2-6个字母

    3. 端口部分支持1-4个数字

    4. 路径支持数字、字母、及常见字符,例如_!~*'().;?:@&=+$,%#-)等,不能有中文

    如果输入URL地址不符合该格式,会返回错误码 400。

QPS限制

本接口的单用户QPS限制为100次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。如果您业务量级较大或者有紧急扩容需求需要更大QPS,请联系您的商务经理。

调试

在接入前,您也可以通过阿里云OpenAPI在线调试提交URL风险检测任务的接口,查看调用示例代码及SDK依赖信息,方便概览接口的使用方法和参数。

重要

在线调试能力是基于当前登录账号调用内容安全的API接口,因此调用量会计入账号的收费用量中。

请求参数

名称

类型

是否必选

示例值

描述

Service

String

url_detection_pro

图片检测增强版支持的检测服务。取值:

  • url_detection_pro:URL风险链接检测

ServiceParameters

JSONString

内容检测对象的相关参数集。JSON字符串格式,关于每个字符串的描述,请参见表 1. ServiceParameters

表 1. ServiceParameters

名称

类型

是否必选

示例值

描述

url

String

https://help.aliyun.com/

待检测的URL。 说明 请确保该URL符合URL格式要求。且一次请求请确保仅传入1条URL。

dataId

String

url123****

检测对象对应的数据ID。 由大小写英文字母、数字、下划线(_)、短划线(-)、英文句号(.)组成,不超过64个字符,可以用于唯一标识您的业务数据。

callback

String

http://www.aliyundoc.com

检测结果回调通知您的URL,支持使用HTTP和HTTPS协议的地址。该字段为空时,您必须定时轮询检测结果。

callback接口必须支持POST方法、UTF-8编码的传输数据,以及表单参数ReqIdChecksumContent

内容安全按照以下规则和格式设置ReqIdChecksumContent,调用您的callback接口返回检测结果。

  • ReqId:提交异步检测任务返回的请求ID。

  • Checksum:字符串格式,由用户uid + seed + content拼成字符串,通过SHA256算法生成。用户UID即阿里云账号ID,可以在阿里云控制台查询。为防篡改,您可以在获取到推送结果时,按上述算法生成字符串,与Checksum做一次校验。说明用户UID必须是阿里云账号的UID,而不是RAM用户的UID。

  • Content:JSON字符串格式,请自行解析反转成JSON对象。关于Content结果的示例,请参见查询检测结果的返回示例。

说明

您的服务端callback接口收到内容安全推送的结果后,如果返回的HTTP状态码为200,则表示接收成功,其他的HTTP状态码均视为接收失败。接收失败时,内容安全将最多重复推送16次检测结果,直到接收成功。重复推送16次后仍未接收成功,则不再推送,建议您检查callback接口的状态。

seed

String

abc****

随机字符串,该值用于回调通知请求中的签名。 由英文字母、数字、下划线(_)组成,不超过64个字符。由您自定义,用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。

说明

当使用callback时,该字段必须提供。

cryptType

String

SHA256

使用回调通知时(callback),设置对回调通知内容进行加密的算法。内容安全会将返回结果(由用户uid + seed + content拼接的字符串)按照您设置的加密算法加密后,再发送到您的回调通知地址。取值: ●SHA256(默认):使用SHA256加密算法。 ●SM3:使用国密HMAC-SM3加密算法,返回十六进制的字符串,且字符串由小写字母和数字组成。例如,abc经国密SM3加密后返回。

返回数据

名称

类型

示例值

描述

Code

Integer

200

状态码。更多信息,请参见Code 说明

Msg

String

OK

请求消息的响应消息。

RequestId

String

ABCD1234-1234-1234-1234-123****

请求ID。

Data

Object

检测结果。

ReqId

String

ABCD1234-1234-1234-1234-123****

请求ID。

DataId

String

img123******

检测对象对应的数据ID。

示例

请求示例

{
    "Service": "url_detection_pro",
    "ServiceParameters": {
        "url": "https://help.aliyun.com/",
        "dataId": "url123******"
    }
}

返回示例

{
    "Msg": "OK",
    "Code": 200,
    "RequestId": "ABCD1234-1234-1234-1234-1234XYZ",
    "Data": {
        "ReqId": "ABCD1234-1234-1234-1234-1234XYZ",
        "DataId": "url123******"
    }
}

获取审核任务结果

接口说明

  • 业务接口:DescribeUrlModerationResult,表示获取URL风险检测任务结果。

  • 计费信息:该接口不计费。

  • 查询超时:建议您将查询间隔设置为5分钟(即在提交异步检测任务5分钟之后查询结果),最长不能超出3天,否则结果将会自动删除。

QPS限制

本接口的单用户QPS限制为100次/秒。超过限制,API调用会被限流,这可能会影响您的业务,请合理调用。

调试

在接入前,您也可以通过阿里云OpenAPI在线调试获取URL风险检测任务结果的接口,查看调用示例代码及SDK依赖信息,方便概览接口的使用方法和参数。

请求参数

名称

类型

是否必选

示例值

描述

reqId

String

70ED13B0-BC22-576D-9CCF-1CC12FEAC477

请求ID。是指提交审核任务返回的RequestId字段。

返回数据

名称

类型

示例值

描述

RequestId

String

ABCD1234-1234-1234-1234-123****

本次调用请求的ID,是由阿里云为该请求生成的唯一标识符,可用于排查和定位问题。

Data

Object

URL风险检测结果。更多信息,请参见表 2.Data

Code

Integer

200

状态码。更多信息,请参见Code说明

Msg

String

OK

本次请求的响应消息。

表 2.Data

名称

类型

示例值

描述

Results

Array

URL检测的风险标签、置信分等参数结果。更多信息,请参见表 3.Result

DataId

String

img123******

检测对象对应的数据ID。

说明

如果在检测请求参数中传入了dataId,则此处返回对应的dataId。

ExtraInfo

Object

辅助参考信息。更多信息,请参见表 4.ExtraInfo

表 3.Result

名称

类型

示例值

描述

Label

String

sexual_url

URL目标地址经过检测运算后返回的标签。同一张URL可能会检出多个标签和分值。支持的标签如下:

  • sexual_url:疑似色情网站

  • gambling_url:疑似赌博网站

  • phishing_url:疑似钓鱼网站

  • other_risk_url:疑似欺诈和其他风险

  • safe_url:未检测到风险的网站

  • nonLabel:暂无法确定风险状态的网站

Confidence

Float

81.22

置信分值,0到100分,保留到小数点后2位。

表 4.ExtraInfo

名称

类型

示例值

描述

IcpType

String

企业

ICP备案类型。

IcpNo

String

ICP备123456789

ICP备案号。

示例

请求示例

{
    "ReqId": "ABCD1234-1234-1234-1234-123****"
}

返回示例

{
    "Msg": "OK",
    "Code": 200,
    "Data": {
        "DataId": "img123****",
        "Result": [
            {
                "Label": "sexual_url",
                "Confidence": 81.18
            }
        ],
        "ExtraInfo": {
            "IcpType": "企业",
            "IcpNo": "ICP备123456789"
        }
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

Code说明

以下为接口返回code的含义说明,系统仅对code返回为200的请求计量计费,其他code不会计费。

Code

说明

200

请求正常。

280

任务检测中。

400

请求参数为空。

401

请求参数错误。

402

请求参数长度不符合接口规定,请检查并修改。

403

请求超过QPS限制,请检查并调整并发。

405

异步检测超时,建议重试。

408

该账号无权限调用该接口,可能是账号未开通或者已欠费,或者调用账号未被授权访问。

500

系统异常。