卓信服务为CP提供卓信ID校验、群对群更新转换等服务,用于实现跨CP的数据应用。
接口域名: zxid-api.mobileservice.cn(生产环境)、sandbox-zxid-api.mobileservice.cn(沙盒环境)
接口协议: HTTPS、JSON
接口列表:
/data/ConvertZIDGroup
群对群转换/verify/VerifyZIDs
验证 ZID 接口 公共请求参数:
参数名 | 类型 | 说明 |
---|---|---|
Access-Key-Id | string | 通过管理后台申请分配的密钥标识。 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程” |
Partner-Id | string | 当前用户的 PartnerId 。 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程” |
Signature | string | 信息签名字符串,参考签名方式。 |
Signature-Method | string | 信息签名方法,目前固定为 HMAC-SHA256 。 |
Signature-Nonce | string | 64 字节以内的随机串,用于防止重放攻击,每次请求必须提供不同的值。 |
Timestamp | string | UTC时间戳,从UTC1970年1月1日0时0分0秒起至现在的总秒数。如 1632634877。 |
签名方式:
使用请求参数构造标准请求字符串(Standard Query String),包括文档中的“公共请求参数”,但不包括“公共请求参数”中的 Signature 参数。将标准请求字符串进行排序,此排序是大小写敏感的,请使用标准文档中的大小写格式。
具体排序示例: Access-Key-Id, Partner-Id, Signature-Method, Signature-Nonce, Timestamp 。
将参数值使用英文等号 &
进行连接,即得到标准请求字符串。
示例:accesskeyid&partnerid&HMAC-SHA256&67a4ac92-c53e-440d-b777-2b14f7a61a5c&1632634877
按照 RFC2104 对上面的 StringToSign 字符串计算签名 HMAC 值。计算签名时使用的 Key 就是用户持有的 AccessKeySecret ( 该参数必须先向卓信官方申请才能使用,申请流程见“使用指南 -> 申请流程”),使用的哈希算法为 SHA256 。
注意事项:
时间戳 Timestamp 不能偏差过多,目前允许误差为 5 分钟。
群对群更新转换为各 CP 方提供了一种批量地将失效卓信 ID 转换为最新卓信 ID 的方法,目前限定单次转换的卓信ID数量不少于 1000 个、不大于 10w 个(建议先在沙盒环境测试,沙盒环境限制为单次转换的卓信ID数量不少于 2 个、不大于 10w 个,沙盒环境与正式环境数据不互通)。服务端接受请求后会对收到的卓信 ID 进行合法性和是否过期进行检查,要求 99% 以上的 ID 应当为合法且过期的(考虑合作方服务器时间不同步,存在合作方判断过期,实际未过期的小概率可能性),才会认为此次请求有效。
最大响应时间:1w ZID 条件下 2s 内返回、10w ZID 条件下 10s 内返回。
接口名 | ConvertZIDGroup | ||
---|---|---|---|
路径 | /data/ConvertZIDGroup | ||
请求参数 | zids | List<String> | 待查询 ZID 群数组,数量范围:[1000, 10w] |
返回参数 | zids jointDebugRemaining |
List<String> int |
查询后最新的 ZID 群数组,按过期时间排序。 当该请求为正式环境联调模式请求时,将返回该值,表明用户还剩余多少次联调请求限额。 |
请求 / Request :
{
"zids": [
"Z01-1631983930-YUYZOgAWp64tVh1b-3662",
"Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
"Z01-1632047870-YUcS/gCxlxlLbzSB-B6BF",
"Z01-1631983641-YUYYGQBcsunUsZvX-E1FB",
"Z01-1631981930-YUYRagDuJV072tyx-E81D",
"Z01-1632037734-YUbrZgAd3bZUfNmE-A1EC",
"Z01-1631984838-YUYcxgArlLU3XB+6-F244",
"Z01-1631989788-YUYwHAC6CkUtLDMj-34C5",
"Z01-1632031977-YUbU6QDfWMMrI7+8-1EC2",
// ...
]
}
返回 / Response :
{
"zids": [
"Z01-1642462621-YcLkjaIiuala89Az-J1ck",
"Z01-1642421712-YcKJawklLa81jU-a-Pqkz",
"Z01-1642169267-YcKjas71jNquaICP-2c1M",
// ...
],
"jointDebugRemaining": 1000
// 当该请求为正式环境联调模式请求时,将返回该值,表明用户还剩余多少次联调请求限额。
}
注:
考虑到有初期接入客户一开始正式环境的 ZID 不足 1000 个,无法通过常规手段调用群对群翻译接口。
为了保障初期接入,我们为客户开设一个短期的白名单:
验证 ZID 接口接受一组 ZID 输入(输入数量 ≤ 10w ),按原顺序返回传入的 ZID 的验证结果。
接口名 | VerifyZIDs | ||
---|---|---|---|
路径 | /verify/VerifyZIDs | ||
请求参数 | zids | List<String> | 待验证 ZID 数组,大小范围:≤ 10w |
返回参数 | realZIDs fakeZIDs |
List<String> List<String> |
验证通过的 ZID 数组 验证未通过的 ZID 数组 |
请求 / Request :
{
"zids": [
"Z01-1631983930-YUYZOgAWp64tVh1b-3662",
"Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
"Z01-1632047870-YUcS/gCxlxl12345-1234",
"abcd1234",
"",
" ",
"abcd1234",
// ...
]
}
返回 / Response :
{
"realZIDs": [
"Z01-1631983930-YUYZOgAWp64tVh1b-3662",
"Z01-1632005937-YUZvMQAM0O6M7zYx-CCA4",
// ...
],
"fakeZIDs": [
"Z01-1632047870-YUcS/gCxlxl12345-1234",
"abcd1234",
"",
" ",
"abcd1234",
// ...
]
}
卓信ID群对群转换服务是为了便于各CP方维护基于卓信ID生成的用户群信息,支持数字营销、统计分析等应用场景而提供的失效卓信ID更新服务,该服务不可用于单个个体的卓信ID转换,各CP不得尝试通过变更单一ID来变相获取单一卓信ID的转换能力。卓信服务将通过定期巡检方式进行检查,对于违规CP,我们将停止提供相应的群对群转换服务。
以上文档对您是否有帮助?