搜狗首页  |   服务首页  |   客服热线:010-56898080

新服务(Restful)说明

服务说明

为了提升API接口的可读性和易用性,降低客户的调试维护成本,搜狗搜索推广API对接口进行了升级,支持通过Restful的方式进行对接。
目前仅支持搜索内容生态推广的高级样式通过Restful进行对接,后续会逐渐升级已有服务,同时也会对维持对WebService服务的支持。
为了提升稳定性、易用性,未来API的新服务只支持Restful对接,还望开发者能够逐渐向新服务进行迁移。

开发规范

新服务是采用HTTP+JSON格式的restful接口,通过发送post请求调用,post请求发送的数据是一个JSON格式的字符串。
所有接口需要使用HTTPS协议、JSON数据格式、UTF-8编码,接口说明格式如下:
> 请求方式:POST(HTTPS)
> 全局编码要求:UTF-8
> 请求协议:contentType: "application/json;charset=utf-8"
curl --location --request POST 'https://xuriapi.p4p.sogou.com' \
--header 'Content-Type: application/json' \
--data-raw '{
    "body": {},
    "header": {
        "adType": 1,
        "agentpassword": "",
        "agentusername": "",
        "apiusertype": "api",
        "password": "xxxxxx",
        "token": "xxxxxx",
        "username": "test@xxx.com"
    }
}'

请求地址

请求主域名: https://xuriapi.p4p.sogou.com
文中的SERVER_HOST都是用的此地址。

请求参数体

{
    "body":{//数组时是[]
    },
    "header":{
        "username":"xxx", //账户名称,必填
        "password":"",
        "agentusername":"",
        "agentpassword":"xxx",
        "apiusertype":"",
        "token":"xxxx", //token值,必填
        "adType":1 //平台类型,选填,1:网页搜索平台, 2:搜索内容生态
    }
}
参数说明:
元素名 含义 是否必填
agentusername 代理商账户/账户管家帐户名称 代理商账户/账户管家账户登录时必填
agentpassword 代理商账户/账户管家帐户密码 代理商账户/账户管家账户登录时必填
username 账户名称,代理商/账户管家登录时为被代管的账户 必填
password 账户密码 代理商账户/账户管家账户登录时非必填
token 账户token值 必填
adType 平台类型,区分操作物料平台
1:网页搜索推广
2:搜索内容生态推广
3:信息流推广
选填,默认是1
apiusertype 账户类型 通过账户管家账户登录时必填,需要取值为manageapi
软件厂商登录时必填,取值为soft
body 业务参数 必填,如果是数组格式,传递body:[{},{}..]
单一数据:body:{}
详细参照具体接口
注意:这里的header和body并非是http协议中的header头和body类型。只是代表参数的名称
每次请求都需要传递参数header,设置账户相关信息,业务参数放在body参数下面。
> 如果您是代理商,想操作您下面的用户,则您需要填入 agentusername、agentpassword、username、token这4 个属性;
> 如果您是普通用户,您只需填入 username 、 password 、及 token 这 3 个属性。

响应结果

响应结果包含一次请求的结果状态,包括成功 / 失败状态、操作时间、配额(已取消配额,可忽略)等相关数据。 API 的所有响应信息中包含相同的格式。建议您在程序实现时每次调用均把这些数据保存到本地日志文件中。响应头信息中包含的数据如下:
{
	"status":0,
    "desc":"xxx",
    "failures":[
        {
            "code": xx,
            "content":"xxx",
            "message":"xxx",
            "position":"xxx"
        },
        ...
    ],
    "oprs":xx,
    "oprtime":xx,
    "quota":1x,
    "rquota":xx,
    "data":{//数组时是[]
    }
}
参数说明:
元素名 类型 说明 是否必须
desc String 返回结果描述,值有四个:
success :执行成功
success with failures :部分执行成功,部分执行失败
failure :全部执行失败
system failure :系统认证失败或者系统内部错误。
failures array 错误信息数组,指明了错误原因。具体请见 错误信息
oprs Integer 当前操作执行的操作数
oprtime Integer 当前操作所持续的秒数
quota Integer 当前操作所消耗的配额(可忽略)
rquota Integer 当前操作后剩余配额(可忽略)
status Integer 0-success
1-success with failures
2-failure
3-system failure
data json 返回具体业务数据内容
单条数据: data:{}
多条数据: data:[{},{}]
详细参考具体接口

其他说明

出于系统保护的考虑,我们对接口的调用做了频次限制(QPS),各接口QPS统一限制为5。
达到限制后,可在下一秒继续请求。