数据擦除 API

数据擦除 API 是从 Pushwoosh 自助擦除主体个人数据的方式（即 GDPR 的删除权）。擦除操作不可撤销：可使用它从您自己的系统中镜像 Control Panel 的 数据请求 页面，以及订阅者卡片上的 擦除个人数据 操作。

基础 URL

https://rpc-api.svc-nue.pushwoosh.com

所有端点均通过 HTTPS 提供。请求和响应使用 application/json，但 Upload 除外，它使用 multipart/form-data。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的 服务器 API 令牌：

Authorization: Api YOUR_API_TOKEN

该令牌必须对 application_codes 中列出的每个应用程序拥有修改权限。这与令牌写入这些应用程序设备数据所需的权限相同。

约定

• 字段命名： 请求正文接受 lowerCamelCase（例如 applicationCodes、identifierType）。响应使用 proto 字段名封送，采用 snake_case（task_id、identifier_hash 等）。下方的示例和对象参考均使用这种大小写。
• 标识符： 主体通过 identifier_type（SUBJECT_IDENTIFIER_USER_ID、SUBJECT_IDENTIFIER_HWID 或 SUBJECT_IDENTIFIER_EMAIL）加上该单一类型的 identifiers 列表来指定。电子邮件标识符的匹配不区分大小写。
• 先试运行，再引用它： 使用 dry_run: true 调用 Create 只会统计将被擦除的内容，不会写入任何数据。在正式调用中将该试运行的 task_id 作为 confirmation_dry_run_task_id 引用是可选的，但如果引用了，它必须与该试运行本身的应用程序和标识符完全匹配，并且必须在该试运行完成后的 15 分钟内调用，否则该调用将被拒绝。
• 报告绝不会以明文形式携带标识符。 GetTaskReport 和 GetJournalReport 都会将每个标识符报告为其 sha256 哈希值（identifier_hash），并且报告正文在 JSON 响应中以 base64 编码的 CSV 形式呈现。

错误响应

HTTP 状态	含义
400 Bad Request	参数无效，例如 identifier_type、identifiers 或 application_codes 为空、标识符超过 10,000 个、应用程序超过 50 个、标识符 × 应用程序超过 50,000、标识符字符串为空，或（仅 Upload）CSV 文件缺失/不可读。当引用的 confirmation_dry_run_task_id 与其指定的已完成试运行不匹配、过旧（超过 15 分钟），或根本不是一个已完成的试运行时，也会以线路上的 FailedPrecondition 形式返回。
401 Unauthorized	缺少或无效的 Authorization 标头。
403 Forbidden	该令牌对请求的某个应用程序没有修改/设备数据权限，或调用者无权读取所请求的任务/报告。
404 Not Found	未找到该任务，或该任务不属于调用者的帐户。
413 Payload Too Large	（仅 Upload）上传的文件超过 5 MB。
429 Too Many Requests	该帐户在过去 24 小时内已启动 20 个数据擦除任务（包括试运行）。

端点

方法	路径	描述
POST	/api/data_erasure/tasks	创建一个擦除（或试运行）任务
POST	/api/data_erasure/upload	从上传的标识符 CSV 创建一个擦除任务
GET	/api/data_erasure/tasks	列出该帐户的擦除任务
GET	/api/data_erasure/tasks/{task_id}	获取一个擦除任务
GET	/api/data_erasure/tasks/{task_id}/rows	列出一个任务的逐标识符结果
GET	/api/data_erasure/tasks/{task_id}/report	以 CSV 形式下载一个任务的报告
GET	/api/data_erasure/report	将某个时间段内的所有任务下载为一个 CSV 文件

Create

开始擦除所列应用程序中所列主体的个人数据。使用 dry_run: true 时，任务只会统计将被擦除的内容。

POST /api/data_erasure/tasks

请求正文

参数	类型	必需	描述
identifierType	string	是	SUBJECT_IDENTIFIER_USER_ID、SUBJECT_IDENTIFIER_HWID 或 SUBJECT_IDENTIFIER_EMAIL。
identifiers	array of strings	是	该单一类型的主体标识符，每个任务最多 10,000 个，不允许空值。
applicationCodes	array of strings	是	要从中擦除数据的 应用程序代码，最多 50 个。无法在一次调用中擦除该帐户的每个应用程序，因此需要显式列出每一个。identifiers.length × applicationCodes.length 不得超过 50,000，因为报告中每个标识符 × 每个应用程序对应一行。
dryRun	boolean	否	统计将被擦除的内容，不写入任何数据。默认为 false。
confirmationDryRunTaskId	integer	否	测量过此次精确擦除的已完成试运行的 task_id。请参阅 约定。

请求示例

{
  "identifierType": "SUBJECT_IDENTIFIER_EMAIL",
  "identifiers": ["subject@example.com"],
  "applicationCodes": ["XXXXX-XXXXX"],
  "dryRun": true
}

响应

字段	类型	描述
task_id	integer	创建的任务的 ID。在本页的其他所有端点中使用它。

危险

擦除操作无法撤销。擦除某个主体会移除其在所有指定应用程序中的数据，但不会取消已为该主体安排或排队的消息，例如延迟发送或正在运行的 Journey 的下一步。

Upload

创建与 Create 相同类型的任务，但标识符来自上传的 CSV 而不是 JSON 数组。适用于批量主体列表。

POST /api/data_erasure/upload

请求（multipart/form-data）

字段	必需	描述
file	是	CSV 文件，最大 5 MB，单列中每行一个标识符。第一行可以为该列命名（user_id、userid、user id、hwid、email、identifier 或 subject，不区分大小写），而不是包含一个标识符。该行随后会作为表头被跳过，不计入统计。空白行会被跳过并单独计数。重复的标识符（对于电子邮件不区分大小写）会被合并为一个，并单独计数。
identifier_type	是	user_id、hwid 或 email，小写，与本页其他地方使用的 JSON identifierType 枚举值的大小写形式不同。一种类型适用于整个文件。
application_codes	是	以逗号分隔的应用程序代码。
dry_run	否	true/false。
confirmation_dry_run_task_id	否	与 Create 相同。

响应

{
  "task_id": 123,
  "identifier_count": 480,
  "duplicate_count": 3,
  "skipped_rows": 1
}

ListTasks

列出该帐户的擦除记录，最新的排在最前：记录谁在何时擦除了什么的审计日志。除非设置了 includeDryRuns，否则不包含试运行。

GET /api/data_erasure/tasks

查询参数

参数	类型	描述
limit / offset	integer	分页。
includeDryRuns	boolean	包含试运行（仅测量）任务。
from / to	string (RFC 3339)	保留在 [from, to) 区间内启动的任务。
applicationCode	string	保留涵盖此应用程序的任务。
initiatorUserId	integer	保留由此 Control Panel 用户启动的任务。0（默认值）保留所有发起者。
initiatorTokenId	integer	保留由此 API 令牌启动的任务。0（默认值）保留所有发起者。
initiatorEmail	string	保留由此 Control Panel 用户启动的任务，按电子邮件匹配，不区分大小写。

响应

字段	类型	描述
tasks	array of 数据擦除任务对象	匹配的任务。

GetTask

返回一个擦除任务及其状态和计数器。用它来跟踪由 Create 或 Upload 启动的任务。

GET /api/data_erasure/tasks/{task_id}

响应

字段	类型	描述
task	数据擦除任务对象	请求的任务。

ListTaskRows

返回一个任务的逐标识符结果：哪些被删除、未找到、跳过或失败。标识符以其 sha256 哈希值形式报告。

GET /api/data_erasure/tasks/{task_id}/rows

查询参数

参数	类型	描述
limit / offset	integer	分页。

响应

字段	类型	描述
rows	array of 数据擦除任务行对象	本页结果。

GetTaskReport

以 CSV 文件形式返回一个任务的完整报告：每个标识符 × 每个应用程序一行，附带其结果。ListTaskRows 则是逐页显示相同的行。

GET /api/data_erasure/tasks/{task_id}/report

响应

字段	类型	描述
filename	string	建议的文件名，例如 data-erasure-task-42.csv。
content_type	string	text/csv。
content	string (base64)	CSV 文件。列：task_id、created、identifier_type、identifier_hash、application_code、result、detail。

GetJournalReport

将某个时间段内的所有擦除记录以一个 CSV 文件形式返回：每个标识符 × 每个应用程序一行，每行都附带任务及其发起者信息。这是帐户交给审计人员的内容。

GET /api/data_erasure/report

查询参数

参数	类型	必需	描述
from	string (RFC 3339)	是	时间段的开始。
to	string (RFC 3339)	否	时间段的结束。默认为当前时间。
includeDryRuns	boolean	否	包含试运行任务。

警告

超过 2,000 个擦除任务的时间段会被拒绝，而不是被截断。请缩小时间段范围后重新调用。

响应

字段	类型	描述
filename	string	建议的文件名，例如 data-erasure-2026-01-01-2026-04-01.csv。
content_type	string	text/csv。
content	string (base64)	CSV 文件。列：task_id、task_created、initiator_user_id、initiator_email、initiator_token_id、dry_run、identifier_type、identifier_hash、application_code、result、detail、row_created。

数据擦除任务对象

字段	类型	描述
task_id	integer	任务 ID。
identifier_type	string	SUBJECT_IDENTIFIER_USER_ID、SUBJECT_IDENTIFIER_HWID 或 SUBJECT_IDENTIFIER_EMAIL。
application_codes	array of strings	该任务涵盖的应用程序。
dry_run	boolean	此任务是否仅测量了一个数量。
status	string	ERASURE_TASK_STATUS_PENDING、_IN_PROGRESS、_DONE 或 _FAILED。
total_count	integer	该任务涵盖的标识符 × 应用程序数量。
deleted_count	integer	已擦除的数量（对于试运行，则是将被擦除的数量）。
not_found_count	integer	未匹配到任何内容的数量。
failed_count	integer	失败的数量。原因请参阅 ListTaskRows 或报告。
fail_reason	string	当 status 为 ERASURE_TASK_STATUS_FAILED 时设置。
initiator_user_id	integer	启动该任务的 Control Panel 用户。当由 API 令牌启动时为 0。
initiator_token_id	integer	启动该任务的 API 令牌。当由 Control Panel 用户启动时为 0。
initiator_email	string	启动该任务的 Control Panel 用户的地址。对于 API 令牌为空。
created	string (RFC 3339)	任务的创建时间。
started_at	string (RFC 3339)	擦除工作的开始时间。
finished_at	string (RFC 3339)	任务达到最终状态的时间。

数据擦除任务行对象

字段	类型	描述
identifier_hash	string	标识符的 sha256 值。报告绝不会存储或返回标识符本身。
application_code	string	此行结果所对应的应用程序。
result	string	ERASURE_ROW_RESULT_DELETED、_NOT_FOUND、_SKIPPED 或 _FAILED。
detail	string	技术细节，主要在失败时设置。
created	string (RFC 3339)	此行的写入时间。

相关

数据请求（产品指南）

从 User Explorer 擦除个人数据