内容审核 API
对项目内可写入资源(数据库集合 / Storage 桶)的内容审核配置与审核日志:对数据表文本,pre 模式在写入前审核;存储图片则先写入存储设备,再按配置审核。2.9.0 起新增 post(先落库再异步审核)与 hybrid(按平台文本长度阈值分流)模式——新建或更新时需平台开启二期;关闭时不接受这两种模式,已有配置执行时回退同步审核。二期同时引入 requireManualReviewOnViolation(违规转人工复核)与文档 moderationStatus(checking / pending / published / quarantined / private_hold / action_error);未发布文档的审核状态检查允许创建者、最后修改者及特权身份;实际读取仍需满足适用认证和数据库权限。含属性过滤条件的列表 total 可能高估。
服务与资源边界
内容审核 API(/v1/moderation-configs*、/v1/moderation-logs*)为项目内的结构化数据表(collections)与对象存储桶(buckets)提供声明式内容安全防线:支持配置前置同步拦截(pre)、后置异步审核(post)与按长度分流混合审核(hybrid)三种模式,自动对表内文本列或桶内图片执行合规检测,并记录完整的审核判定审计日志。
资源与基础路径
Base URL:
https://<your-endpoint>/v1。配置按资源定位:
resourceType(collections/buckets)+resourceId(集合或桶 ID);resourceType=collections时必须附带databaseId(databases)。一个资源至多一份配置。日志:
moderationLog({logId}),记录每次审核判定。
认证与权限
认证与请求头约定见 通用约定。本域 scope:moderation.config.read / moderation.config.write(配置)、moderation.log.read(日志)。
端点总览
Moderation 模块共提供 6 个端点:包括 4 个资源级审核策略配置端点(创建、按 resourceType/resourceId 读取、更新、删除)与 2 个审核判定日志查询端点(分页列表与单条详情)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /moderation-configs | 创建审核配置 |
GET /moderation-configs/{resourceType}/{resourceId} | 读取配置 |
PATCH /moderation-configs/{resourceType}/{resourceId} | 更新配置 |
DELETE /moderation-configs/{resourceType}/{resourceId} | 删除配置 |
GET /moderation-logs | 审核日志列表 |
GET /moderation-logs/{logId} | 审核日志详情 |
端点详解
审核规则一旦在目标表或存储桶上启用(enabled: true),业务侧无需修改原有的数据库 createRow/updateRow 或存储 createFile 调用代码,系统按资源和环境配置处理写入内容。数据表异步审核中,违规记录根据 requireManualReviewOnViolation 进入 quarantined 或 private_hold;可见性仍须按审核状态检查和原有权限判断。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。
POST /v1/moderation-configs
为可写入资源创建内容审核配置:创建且 enabled=true 后,该资源的写入与更新经审核门禁(pre 前置拦截;审核二期的 post / hybrid 为异步后置)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
resourceType | body | string | 是 | 枚举 collections, buckets | 资源类型:collections(数据表)/ buckets(存储桶)。 |
resourceId | body | string | 是 | — | 资源 ID(表 ID 或桶 ID);一个资源至多一份配置,重复创建返回 409。 |
databaseId | body | string | 否 | — | resourceType=collections 时必填:所属数据库 ID。 |
mode | body | string | 是 | 枚举 pre, post, hybrid(2.9.0 起) | 审核模式:pre(写入前置拦截);post / hybrid 为审核二期异步后置模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre。 |
requireManualReviewOnViolation | body | boolean | 否 | 默认 true | 违规转人工复核(2.9.0):true 违规文档隔离(quarantined);false 私密扣留,仍须按审核状态检查及原有权限判断可见性(private_hold)。 |
contentTypes | body | string[] | 是 | — | 参与审核的内容类型数组:数据表传 ["text"](按表 schema 自动筛出 string/varchar/text/mediumtext/longtext 列,含数组列);桶传 ["image"](实际生效取决于环境、项目、桶配置与审核服务)。 |
enabled | body | boolean | 否 | — | 是否启用;创建时缺省为 true,实际审核还受环境、项目和资源配置影响。 |
输出:返回 201 + moderationConfig:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 配置 ID。 |
$createdAt | string | 配置创建时间(ISO 8601)。 |
$updatedAt | string | 配置最近更新时间(ISO 8601)。 |
resourceType | string | 资源类型:collections / buckets。 |
resourceId | string | 被审核的资源 ID(表或桶)。 |
databaseId | string | resourceType=collections 时的所属库 ID。 |
enabled | boolean | 是否启用审核:配置存在且 enabled=true 后内容才真正被审核。 |
mode | string | 审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。 |
requireManualReviewOnViolation | boolean | 违规转人工复核开关(默认 true)。 |
contentTypes | string[] | 参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。 |
status | string | 配置状态:active / disabled_by_global(被项目级总开关停用)。 |
与 databases / storage 的写入链路联动:审核在
createRow/updateRow过程中自动执行,无需单独调用审核方法。二期模式下文档带moderationStatus与moderationJobId(document模型 2.9.0 新增字段)。命中拒绝规则时原始写请求被拦并返回
moderation_rejected,同时产生一条moderationLog。
调用示例:
curl -X POST "https://<your-endpoint>/v1/moderation-configs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"mode": "pre",
"contentTypes": ["text"],
"enabled": true
}'响应示例:
{
"$id": "mc_forum_comments",
"$createdAt": "2026-09-14T02:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:00:00.000+00:00",
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"enabled": true,
"mode": "pre",
"contentTypes": [
"text"
],
"status": "active"
}GET /v1/moderation-configs/{resourceType}/{resourceId}
读取某资源的审核配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
resourceType | path | string | 是 | 枚举 collections, buckets | 资源类型:collections / buckets。 |
resourceId | path | string | 是 | — | 资源 ID。 |
databaseId | query | string | 否 | — | resourceType=collections 时必填的所属库 ID(query 传入)。 |
输出:返回 moderationConfig:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 配置 ID。 |
$createdAt | string | 配置创建时间(ISO 8601)。 |
$updatedAt | string | 配置最近更新时间(ISO 8601)。 |
resourceType | string | 资源类型:collections / buckets。 |
resourceId | string | 被审核的资源 ID(表或桶)。 |
databaseId | string | resourceType=collections 时的所属库 ID。 |
enabled | boolean | 是否启用审核:配置存在且 enabled=true 后内容才真正被审核。 |
mode | string | 审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。 |
requireManualReviewOnViolation | boolean | 违规转人工复核开关(默认 true)。 |
contentTypes | string[] | 参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。 |
status | string | 配置状态:active / disabled_by_global(被项目级总开关停用)。 |
配置不存在返回
404+moderation_config_not_found。
调用示例:
curl "https://<your-endpoint>/v1/moderation-configs/collections/comments?databaseId=forum" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "mc_forum_comments",
"$createdAt": "2026-09-14T02:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:00:00.000+00:00",
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"enabled": true,
"mode": "pre",
"contentTypes": [
"text"
],
"status": "active"
}PATCH /v1/moderation-configs/{resourceType}/{resourceId}
更新审核配置:切换启停、调整内容类型或模式;只更新传入字段,contentTypes 省略时保留原配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
resourceType | path | string | 是 | 枚举 collections, buckets | 资源类型:collections / buckets。 |
resourceId | path | string | 是 | — | 资源 ID。 |
databaseId | body | string | 否 | — | resourceType=collections 时必填。 |
mode | body | string | 否 | 枚举 pre, post, hybrid | 审核模式;post / hybrid 二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre。 |
requireManualReviewOnViolation | body | boolean | 否 | 默认 true | 违规转人工复核(2.9.0):true 违规文档隔离(quarantined);false 私密扣留,仍须按审核状态检查及原有权限判断可见性(private_hold)。 |
contentTypes | body | string[] | 否 | — | 参与审核的内容类型数组。 |
enabled | body | boolean | 否 | — | true 开启 / false 暂停(保留配置,可随时重新开启)。 |
输出:返回更新后的 moderationConfig:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 配置 ID。 |
$createdAt | string | 配置创建时间(ISO 8601)。 |
$updatedAt | string | 配置最近更新时间(ISO 8601)。 |
resourceType | string | 资源类型:collections / buckets。 |
resourceId | string | 被审核的资源 ID(表或桶)。 |
databaseId | string | resourceType=collections 时的所属库 ID。 |
enabled | boolean | 是否启用审核:配置存在且 enabled=true 后内容才真正被审核。 |
mode | string | 审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。 |
requireManualReviewOnViolation | boolean | 违规转人工复核开关(默认 true)。 |
contentTypes | string[] | 参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。 |
status | string | 配置状态:active / disabled_by_global(被项目级总开关停用)。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/moderation-configs/collections/comments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "enabled": false, "databaseId": "forum" }'响应示例:
{
"$id": "mc_forum_comments",
"$createdAt": "2026-09-14T02:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:05:00.000+00:00",
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"enabled": false,
"mode": "pre",
"contentTypes": [
"text"
],
"status": "active"
}DELETE /v1/moderation-configs/{resourceType}/{resourceId}
删除审核配置:移除后该资源不再被审核;历史日志不受影响。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
resourceType | path | string | 是 | 枚举 collections, buckets | 资源类型:collections / buckets。 |
resourceId | path | string | 是 | — | 资源 ID。 |
databaseId | body | string | 否 | — | resourceType=collections 时必填(body 传入)。 |
输出:204 No Content,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/moderation-configs/collections/comments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "databaseId": "forum" }'响应示例:204 No Content:无响应体(配置已删除)。
GET /v1/moderation-logs
分页查询审核日志:每条记录一次审核判定,可按资源、判定结果等属性过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | Query 查询串数组(SDK Query 生成),最多 100 条、每条最长 4096 字符;可过滤 resourceType、resourceId、databaseId、result、timestamp、userId、contentType 等属性。 |
total | query | boolean | 否 | 默认 true | 设为 false 时响应 total 恒为 0,跳过计数以加速查询。 |
输出:返回 moderationLogList(total + logs[]),元素为 moderationLog:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 日志 ID。 |
$createdAt | string | 日志创建时间(ISO 8601)。 |
$updatedAt | string | 日志最近更新时间(ISO 8601)。 |
resourceType | string | 资源类型:collections / buckets。 |
resourceId | string | 被审核资源 ID。 |
databaseId | string | resourceType=collections 时的所属库 ID。 |
userId | string | 触发写入的用户 ID。 |
timestamp | integer | 审核发生时间(Unix 秒)。 |
contentType | string | 本次审核的内容类型(text / image)。 |
contentPreview | string | 被审核内容的截断预览(脱敏)。 |
result | string | 判定结果:pass / block / review / error。 |
labels | string[] | 审核服务返回的风险标签(如 porn、violence)。 |
confidence | number | 审核服务置信度(0–1)。 |
suggestion | string | 审核服务建议:pass / review / block。 |
provider | string | 审核服务商标识(如 alibaba)。 |
requestId | string | 审核服务请求 ID,用于追踪。 |
error | string | result=error 时的错误信息。 |
credentialSource | string | 本次审核调用使用的凭证来源:platform / project。 |
写入被拦(
moderation_rejected)后,先到日志里确认result=block的记录与labels。
调用示例:
curl "https://<your-endpoint>/v1/moderation-logs?queries%5B0%5D=equal(%22resourceId%22%2C%22comments%22)&queries%5B1%5D=equal(%22result%22%2C%22block%22)&total=true" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"
# 推荐经 SDK Query.equal('resourceId','comments') 生成查询串,避免手写转义响应示例:
{
"total": 1,
"logs": [
{
"$id": "ml_01J5Z8XK2Q",
"$createdAt": "2026-09-14T02:31:00.000+00:00",
"$updatedAt": "2026-09-14T02:31:00.000+00:00",
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"userId": "user_42",
"timestamp": 1757812260,
"contentType": "text",
"contentPreview": "加微信立返现金…",
"result": "block",
"labels": [
"porn",
"violence"
],
"confidence": 0.95,
"suggestion": "block",
"provider": "alibaba",
"requestId": "req_9f2c8ab1",
"error": "",
"credentialSource": "platform"
}
]
}GET /v1/moderation-logs/{logId}
读取单条审核日志的完整判定详情。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
logId | path | string | 是 | — | 日志 ID。 |
输出:返回 moderationLog:
| 字段 | 类型 | 说明 |
|---|---|---|
$id | string | 日志 ID。 |
$createdAt | string | 日志创建时间(ISO 8601)。 |
$updatedAt | string | 日志最近更新时间(ISO 8601)。 |
resourceType | string | 资源类型:collections / buckets。 |
resourceId | string | 被审核资源 ID。 |
databaseId | string | resourceType=collections 时的所属库 ID。 |
userId | string | 触发写入的用户 ID。 |
timestamp | integer | 审核发生时间(Unix 秒)。 |
contentType | string | 本次审核的内容类型(text / image)。 |
contentPreview | string | 被审核内容的截断预览(脱敏)。 |
result | string | 判定结果:pass / block / review / error。 |
labels | string[] | 审核服务返回的风险标签(如 porn、violence)。 |
confidence | number | 审核服务置信度(0–1)。 |
suggestion | string | 审核服务建议:pass / review / block。 |
provider | string | 审核服务商标识(如 alibaba)。 |
requestId | string | 审核服务请求 ID,用于追踪。 |
error | string | result=error 时的错误信息。 |
credentialSource | string | 本次审核调用使用的凭证来源:platform / project。 |
日志不存在返回
404+moderation_log_not_found;删除配置不会删除历史日志。
调用示例:
curl "https://<your-endpoint>/v1/moderation-logs/ml_01J5Z8XK2Q" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "ml_01J5Z8XK2Q",
"$createdAt": "2026-09-14T02:31:00.000+00:00",
"$updatedAt": "2026-09-14T02:31:00.000+00:00",
"resourceType": "collections",
"resourceId": "comments",
"databaseId": "forum",
"userId": "user_42",
"timestamp": 1757812260,
"contentType": "text",
"contentPreview": "加微信立返现金…",
"result": "block",
"labels": [
"porn",
"violence"
],
"confidence": 0.95,
"suggestion": "block",
"provider": "alibaba",
"requestId": "req_9f2c8ab1",
"error": "",
"credentialSource": "platform"
}错误与边界
配置重复:
409+moderation_config_already_exists;配置/日志不存在:404+moderation_config_not_found/moderation_log_not_found。命中拒绝规则:原始写请求被拦,返回
moderation_rejected(附判定摘要),同时产生一条日志;审核服务不可用时返回moderation_unavailable——配置存在时是放行还是拦截取决于平台策略,调用方不应假定可用性。pre语义不变:已存在内容不会追溯审核;删除配置不会删除历史日志。post/hybrid(2.9.0,需平台开启审核二期)下违规内容不拦截写入,而是进入异步审核状态机;配置缺失或卡死由平台 reconcile 任务按当前配置语义重判。resourceType=collections而缺databaseId:参数错误。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Moderation.createConfig / getConfig / updateConfig / deleteConfig | /moderation-configs* |
Moderation.listLogs / getLog | /moderation-logs* |