适用场景在开发与运维中敏感信息明文外泄是数据合规的常见风险。数据脱敏敏感信息掩码API 适合以下场景日志脱敏后端服务打印请求/响应日志时拦截手机号、身份证号等字段替换为138****8000形式避免审计时泄漏。前台展示列表页、详情页需要展示部分脱敏后的用户信息如“张*”、“138****8000”。数据导出 / 测试库从生产库导出数据到测试环境前一键清洗敏感字段防止开发人员接触明文。安全审计对于已落库的文本进行二次扫描和掩码满足等保合规要求。该 API 采用纯本地正则匹配不存储任何用户数据毫秒级返回适合在请求链路中作为中间件调用。接口能力边界维度说明支持类型phone手机号、idcard15/18 位身份证、bankcard16-19 位银行卡、email邮箱、name中文姓名类型组合请求时通过types参数逗号分隔指定例如phone,email。省略或设为all则自动检测所有支持类型文本长度单次请求text最长50000 字节约 5000 个中文字符超限将返回 400 错误性能纯内存正则匹配单条 100 字文本通常在 5ms 内返回QPS10 次/秒以官方文档为准建议批量调用时自行控制速率原文回显with_original参数控制detections中是否包含原文默认false避免日志泄漏请求参数与鉴权请求地址POST https://v1.apizero.cn/api/desensitize鉴权方式请求头中必须携带X-API-Key值为你的 API Key。获取方式请参考官方文档不在此赘述。请求头Content-Type: application/json X-API-Key: YOUR_API_KEY_HERE请求体JSON字段类型必填默认值说明textstring是无要脱敏的原始文本最长 50000 字节typesstring否all类型逗号分隔phone,idcard,bankcard,email,name或allwith_originalboolean否false是否在detections中回显原文字段建议保持false请求体示例脱敏手机和姓名无需原文{ text: 联系人张三电话 13812348000, types: phone,name, with_original: false }最小可运行示例curl以下命令使用环境变量$APIZERO_API_KEY保存密钥请提前设置或直接替换为你的 Key。curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { text: 您好我是李明身份证 110101199001011234银行卡 6222021234567890123邮箱 limingexample.com, types: idcard,bankcard,email,name, with_original: false } \ https://v1.apizero.cn/api/desensitize预期响应字段解释见下一节{ code: 0, msg: 成功, data: { masked_text: 您好我是李*身份证 110101********1234银行卡 622202******7890邮箱 l****example.com, detection_count: 4, detections: [ { type: name, masked: 李* }, { type: idcard, masked: 110101********1234 }, { type: bankcard, masked: 622202******7890 }, { type: email, masked: l****example.com } ], summary: { name: 1, idcard: 1, bankcard: 1, email: 1 }, types_applied: [idcard,bankcard,email,name] } }注意masked_text中的脱敏规则由服务端正则决定调用方无需自行实现掩码逻辑。代码接入Python以下示例使用requests库适合在 Python 项目中快速集成。import requests API_URL https://v1.apizero.cn/api/desensitize API_KEY your-api-key-here # 请替换 def desensitize(text, typesall, with_originalFalse): headers { X-API-Key: API_KEY, Content-Type: application/json } payload { text: text, types: types, with_original: with_original } resp requests.post(API_URL, jsonpayload, headersheaders) resp.raise_for_status() return resp.json() # 使用示例 result desensitize( text我叫王五手机 18612345678邮箱 wangwutest.com, typesphone,email,name ) print(result[data][masked_text]) # 输出: 我叫王*手机 186****5678邮箱 w****test.com返回字段解读成功响应中的data对象包含以下字段字段类型说明masked_textstring整段文本脱敏后的结果可直接用于展示或存储detection_countinteger本次检测并脱敏的敏感信息总数detectionsarray每项包含type类型和masked脱敏后的值summaryobject按类型统计的计数例如{phone: 1, name: 2}types_appliedarray[string]本次实际应用的脱敏类型列表与请求的types有关如果with_original为true则detections中还会增加original字段存放脱敏前的原文。建议仅在调试时开启生产环境保持 false。常见错误与排查HTTP 状态码code可能原因处理建议401–API Key 缺失或无效检查X-API-Key头是否正确Key 是否过期40010001text参数为空或超过 50000 字节检查文本长度使用len(text.encode(utf-8))确认字节数40010002types参数包含不支持的类型仅使用phone,idcard,bankcard,email,name或all500–服务端临时异常重试若持续失败请检查官方文档状态页调试技巧将with_original设为true并观察detections中的original值确认正则是否覆盖了你的文本格式。例如身份证末尾带X、座机号非手机号会被忽略因为当前只支持手机号。工程化注意事项避免在日志中记录原文即使 API 默认不返回原文也不应将masked_text与text同时记录到日志。建议在调用 API 之前就用一个临时变量传递原始文本仅存在于内存中。批量处理时注意 QPS 限流官方文档标明 QPS 为 10对于超过 10 条/秒的批量任务需在客户端添加限流器如 token bucket。可使用time.sleep(0.1)简单控制或使用asyncio并发加信号量。编码统一确保传给 API 的文本为 UTF-8 编码尤其是从文件或第三方系统读取的数据。特殊字符处理文本中若包含换行符、制表符等API 能够正常处理但请求 JSON 中text字段需正确转义curl 中建议使用单引号包裹避免 shell 转义。降级方案如果 API 不可用建议本地准备一套轻量正则作为兜底例如仅脱敏手机号避免核心链路中断。自定义脱敏类型当前 API 不支持自定义正则若有特殊格式如护照号、军官证号需自行在业务层处理。参考文档数据脱敏 API 文档页https://apizero.cn/aidocs/desensitize原始 Markdown 文档https://apizero.cn/aidocs/desensitize/raw.md