CodeVeil 数据保护

本指南展示如何使用 CodeVeil 保护敏感数据：掩码处理 PII、使用格式保留式混淆让测试数据保持真实、运行至多 10,000 条记录的大批量作业，以及在作业完成时通过 webhooks 接收通知。

掩码处理敏感字段

CodeVeil 在保留格式与引用完整性的同时，对 PII、财务数据和健康记录进行掩码处理——同一个客户在其出现的每一处都会映射到相同的掩码值。将记录发送到掩码端点，并说明需要保护哪些字段：

curl -X POST https://api.keepflow.ai/v1/codeveil/mask \
  -H "Authorization: Bearer kf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "name": "Jane Doe", "email": "[email protected]", "iban": "DE89370400440532013000" }
    ],
    "fields": {
      "name": "name",
      "email": "email",
      "iban": "iban"
    }
  }'

格式保留式混淆

有用的测试数据，关键在于它必须看起来、表现起来都和真实数据一样。CodeVeil 混淆后的输出会保持与原始数据相同的结构、类型和关系：电子邮件仍是看似有效的邮箱，IBAN 仍保留其国家代码和校验位形态，电话号码仍保留其格式。

{
  "name": "Marta Lindqvist",
  "email": "[email protected]",
  "iban": "DE21500105174829471138"
}

由于格式得以保留，你可以将掩码后的数据集直接放入预发布或测试环境，而每一项校验、连接和外键关系都依然有效。

批量处理

对于大型数据集，可向批处理端点在单次请求中提交至多 10,000 条记录。作业以异步方式运行，因此你无需保持连接处于打开状态：

curl -X POST https://api.keepflow.ai/v1/codeveil/batch \
  -H "Authorization: Bearer kf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/hooks/codeveil",
    "records": [ /* up to 10,000 records */ ],
    "fields": { "email": "email", "ssn": "national_id" }
  }'

该响应会返回一个作业 ID，你可用它来轮询状态，或者也可以等待 webhook。

{
  "data": { "job_id": "job_9f2a", "status": "processing", "record_count": 10000 }
}

完成 Webhooks

无需轮询，只需注册一个 callback_url，CodeVeil 便会在作业完成时向其发送 POST 请求。负载使用 data.processed 事件：

{
  "event": "data.processed",
  "timestamp": "2026-07-17T09:12:00Z",
  "data": {
    "job_id": "job_9f2a",
    "status": "completed",
    "record_count": 10000,
    "download_url": "https://api.keepflow.ai/v1/codeveil/results/job_9f2a"
  }
}

在信任该负载之前，请先用你的 webhook 密钥验证 X-KeepFlow-Signature 请求头，然后从 download_url 获取掩码后的数据集。结果在作业完成后保留 24 小时。