Docs
文档目录

内容审核 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)三种模式,自动对表内文本列或桶内图片执行合规检测,并记录完整的审核判定审计日志。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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 为异步后置)。

输入:

参数位置类型必填默认/枚举说明
resourceTypebodystring是枚举 collections, buckets资源类型:collections(数据表)/ buckets(存储桶)。
resourceIdbodystring是—资源 ID(表 ID 或桶 ID);一个资源至多一份配置,重复创建返回 409。
databaseIdbodystring否—resourceType=collections 时必填:所属数据库 ID。
modebodystring是枚举 pre, post, hybrid(2.9.0 起)审核模式:pre(写入前置拦截);post / hybrid 为审核二期异步后置模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre。
requireManualReviewOnViolationbodyboolean否默认 true违规转人工复核(2.9.0):true 违规文档隔离(quarantined);false 私密扣留,仍须按审核状态检查及原有权限判断可见性(private_hold)。
contentTypesbodystring[]是—参与审核的内容类型数组:数据表传 ["text"](按表 schema 自动筛出 string/varchar/text/mediumtext/longtext 列,含数组列);桶传 ["image"](实际生效取决于环境、项目、桶配置与审核服务)。
enabledbodyboolean否—是否启用;创建时缺省为 true,实际审核还受环境、项目和资源配置影响。

输出:返回 201 + moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。
requireManualReviewOnViolationboolean违规转人工复核开关(默认 true)。
contentTypesstring[]参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。
statusstring配置状态:active / disabled_by_global(被项目级总开关停用)。

调用示例:

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}

读取某资源的审核配置。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdquerystring否—resourceType=collections 时必填的所属库 ID(query 传入)。

输出:返回 moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。
requireManualReviewOnViolationboolean违规转人工复核开关(默认 true)。
contentTypesstring[]参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。
statusstring配置状态:active / disabled_by_global(被项目级总开关停用)。

调用示例:

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 省略时保留原配置。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdbodystring否—resourceType=collections 时必填。
modebodystring否枚举 pre, post, hybrid审核模式;post / hybrid 二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre。
requireManualReviewOnViolationbodyboolean否默认 true违规转人工复核(2.9.0):true 违规文档隔离(quarantined);false 私密扣留,仍须按审核状态检查及原有权限判断可见性(private_hold)。
contentTypesbodystring[]否—参与审核的内容类型数组。
enabledbodyboolean否—true 开启 / false 暂停(保留配置,可随时重新开启)。

输出:返回更新后的 moderationConfig:

字段类型说明
$idstring配置 ID。
$createdAtstring配置创建时间(ISO 8601)。
$updatedAtstring配置最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核的资源 ID(表或桶)。
databaseIdstringresourceType=collections 时的所属库 ID。
enabledboolean是否启用审核:配置存在且 enabled=true 后内容才真正被审核。
modestring审核模式:pre / post / hybrid(post / hybrid 为审核二期模式,二期关闭时新建或更新不接受这些模式;已有配置执行时回退 pre)。
requireManualReviewOnViolationboolean违规转人工复核开关(默认 true)。
contentTypesstring[]参与审核的内容类型:text / image(实际生效取决于环境、项目、桶配置与审核服务)。
statusstring配置状态: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}

删除审核配置:移除后该资源不再被审核;历史日志不受影响。

输入:

参数位置类型必填默认/枚举说明
resourceTypepathstring是枚举 collections, buckets资源类型:collections / buckets。
resourceIdpathstring是—资源 ID。
databaseIdbodystring否—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

分页查询审核日志:每条记录一次审核判定,可按资源、判定结果等属性过滤。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []Query 查询串数组(SDK Query 生成),最多 100 条、每条最长 4096 字符;可过滤 resourceType、resourceId、databaseId、result、timestamp、userId、contentType 等属性。
totalqueryboolean否默认 true设为 false 时响应 total 恒为 0,跳过计数以加速查询。

输出:返回 moderationLogList(total + logs[]),元素为 moderationLog:

字段类型说明
$idstring日志 ID。
$createdAtstring日志创建时间(ISO 8601)。
$updatedAtstring日志最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核资源 ID。
databaseIdstringresourceType=collections 时的所属库 ID。
userIdstring触发写入的用户 ID。
timestampinteger审核发生时间(Unix 秒)。
contentTypestring本次审核的内容类型(text / image)。
contentPreviewstring被审核内容的截断预览(脱敏)。
resultstring判定结果:pass / block / review / error。
labelsstring[]审核服务返回的风险标签(如 porn、violence)。
confidencenumber审核服务置信度(0–1)。
suggestionstring审核服务建议:pass / review / block。
providerstring审核服务商标识(如 alibaba)。
requestIdstring审核服务请求 ID,用于追踪。
errorstringresult=error 时的错误信息。
credentialSourcestring本次审核调用使用的凭证来源:platform / project。

调用示例:

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}

读取单条审核日志的完整判定详情。

输入:

参数位置类型必填默认/枚举说明
logIdpathstring是—日志 ID。

输出:返回 moderationLog:

字段类型说明
$idstring日志 ID。
$createdAtstring日志创建时间(ISO 8601)。
$updatedAtstring日志最近更新时间(ISO 8601)。
resourceTypestring资源类型:collections / buckets。
resourceIdstring被审核资源 ID。
databaseIdstringresourceType=collections 时的所属库 ID。
userIdstring触发写入的用户 ID。
timestampinteger审核发生时间(Unix 秒)。
contentTypestring本次审核的内容类型(text / image)。
contentPreviewstring被审核内容的截断预览(脱敏)。
resultstring判定结果:pass / block / review / error。
labelsstring[]审核服务返回的风险标签(如 porn、violence)。
confidencenumber审核服务置信度(0–1)。
suggestionstring审核服务建议:pass / review / block。
providerstring审核服务商标识(如 alibaba)。
requestIdstring审核服务请求 ID,用于追踪。
errorstringresult=error 时的错误信息。
credentialSourcestring本次审核调用使用的凭证来源:platform / project。

调用示例:

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"
}

错误与边界

与 Server SDK 的对应

service.method端点
Moderation.createConfig / getConfig / updateConfig / deleteConfig/moderation-configs*
Moderation.listLogs / getLog/moderation-logs*