Skip to Content
API 參考規則、觸發器與回呼

規則、觸發器與回呼

驗證寫入、自動化資料表事件、檢視階段性工作，並管理各範圍支援的回呼憑證。

GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/rules

取得資料表規則

用途

回傳資料表已正規化的驗證、核准、通道與不變條件規則。

適用時機

適合顯示規則編輯器，或在變更資料前檢查實際套用的寫入限制。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/rules
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/rules
  • 公司/private/module/custom_tables/company/tables/{table_id}/rules

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableAccessRequired
部門可使用CustomTableAccessRequired
公司可使用CustomTableAccessRequired

參數

欄位位置型別必填說明
table_idpathuuid是要取得規則的資料表 UUID。

回應結構

TableRulesResponse
欄位型別必填說明
rulesobject[]否未指定
table_idstring是未指定
warningsstring[]否Non-fatal notices about the saved rule set — e.g. a content-masking notice when a require_approval rule is saved on a table with column_acl or grant visible_columns restrictions (approval-gate spec §4).

範例

取得資料表的唯一值規則

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "rules": [
    {
      "type": "unique",
      "id": "rule_a1b2c3d4",
      "name": "訂單編號不可重複",
      "columns": [
        "訂單編號"
      ],
      "case_insensitive": true,
      "when": null
    }
  ],
  "warnings": []
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
PUT
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/rules

取代資料表規則

用途

驗證並以原子方式取代後續資料表寫入所套用的完整規則集。

適用時機

預覽完整的目標規則集後使用；PUT 會在單一交易中取代已儲存的規則清單。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/rules
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/rules
  • 公司/private/module/custom_tables/company/tables/{table_id}/rules

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要取代規則的資料表 UUID。

請求結構

TableRulesPayload
欄位型別必填說明
rulesobject[]是Full rules list (PUT semantics; max 10). Each rule: {"type": "compare" | "unique" | "no_overlap" | "exists" | "not_exists" | "count_limit" | "transition" | "check" | "require" | "require_approval" | "channel" | "invariant" | "immutable_when", "name"?: str, "id"?: "rule_<hex>", "when"?: [predicates], ...type-specific fields}. A "count_limit" rule caps a live-row bucket at {"max": int >= 1}: with "table_id" + "match" it counts the exists-style cross-table bucket; without "table_id" it counts THIS table's rows matching "where" predicates ("$row.<col>" values partition per row, e.g. employee eq $row.employee). A "no_overlap" rule additionally takes "min_gap"?: number — minimum separation between intervals in the same scope partition (numeric bounds: plain number; datetime: minutes; date: days; touching at exactly min_gap is allowed) — and bounds its intervals EITHER with "start_column"+"end_column" OR with "interval_column" (ONE interval-type column whose {start, end} cell carries both bounds; datetime class, min_gap in minutes) — never both. A "channel" rule (SCP v1.3) takes EITHER {"column", "require_present", "read_op"?: "subset" | "overlaps"} or {"policy": <node tree>}, plus "enforcement": "observe" | "enforce" — see ChannelRuleFlat / ChannelRulePolicy. An "invariant" rule takes {"policy": <node tree>, "enforcement"} and is principal-blind: it holds for every writer on every path — see InvariantRule. An "immutable_when" rule takes {"prior_when": [predicates], "columns": [refs]} and takes no "when": prior_when is the lock condition evaluated against the row's PRE-image (the row before the write); while it matches, the listed columns may not change (400 on violation). Locks stored inline columns only (not computed/link).

回應結構

TableRulesResponse
欄位型別必填說明
rulesobject[]否未指定
table_idstring是未指定
warningsstring[]否Non-fatal notices about the saved rule set — e.g. a content-masking notice when a require_approval rule is saved on a table with column_acl or grant visible_columns restrictions (approval-gate spec §4).

範例

設定不分大小寫的唯一值規則

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "rules": [
      {
        "type": "unique",
        "name": "訂單編號不可重複",
        "columns": [
          "訂單編號"
        ],
        "case_insensitive": true
      }
    ]
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "rules": [
    {
      "type": "unique",
      "id": "rule_a1b2c3d4",
      "name": "訂單編號不可重複",
      "columns": [
        "訂單編號"
      ],
      "case_insensitive": true,
      "when": null
    }
  ],
  "warnings": []
}

列一旦 posted 就凍結數量與單價

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "rules": [
      {
        "type": "immutable_when",
        "name": "posted-locks-qty",
        "prior_when": [
          {
            "column": "狀態",
            "op": "eq",
            "value": "posted"
          }
        ],
        "columns": [
          "數量",
          "單價"
        ]
      }
    ]
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "rules": [
    {
      "type": "immutable_when",
      "id": "rule_b2c3d4e5",
      "name": "posted-locks-qty",
      "prior_when": [
        {
          "column": "狀態",
          "op": "eq",
          "value": "posted"
        }
      ],
      "columns": [
        "數量",
        "單價"
      ],
      "when": null
    }
  ],
  "warnings": []
}

錯誤

狀態發生條件錯誤本文
400至少一筆規則的類型、欄位參照、運算式或選項無效。
{
  "detail": "rules[0]: invalid rule type 'unknown'. valid types: compare, unique, no_overlap, exists, not_exists, transition, check, require, require_approval, channel, invariant, immutable_when"
}
400immutable_when 規則缺少 prior_when 或 columns、帶了一般的 when、被鎖欄位超過 20 個，或鎖到計算欄／link 欄。detail 是純字串，有 hint 時會在句點後併入。
{
  "detail": "immutable_when requires a non-empty prior_when predicate list (the lock condition, evaluated against the row's pre-image). e.g. [{\"column\": \"status\", \"op\": \"eq\", \"value\": \"posted\"}]"
}
409仍有未解決的階段性變更依賴 require_approval 規則，因此不能變更該規則。
{
  "detail": {
    "error": "approval_rule_locked",
    "pending_count": 2
  }
}
423資料表目前被結構遷移鎖定。
{
  "detail": "Table is currently locked for operation: add_column"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/rules/preview

預覽資料表規則

用途

驗證候選規則集，並在有上限的樣本上評估，不儲存規則。

適用時機

取代正式規則前使用，特別是不變條件與跨資料表限制。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/rules/preview
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/rules/preview
  • 公司/private/module/custom_tables/company/tables/{table_id}/rules/preview

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要評估候選規則的資料表 UUID。

請求結構

TableRulesPreviewPayload
欄位型別必填說明
rulesobject[]是Full rules list (PUT semantics; max 10). Each rule: {"type": "compare" | "unique" | "no_overlap" | "exists" | "not_exists" | "count_limit" | "transition" | "check" | "require" | "require_approval" | "channel" | "invariant" | "immutable_when", "name"?: str, "id"?: "rule_<hex>", "when"?: [predicates], ...type-specific fields}. A "count_limit" rule caps a live-row bucket at {"max": int >= 1}: with "table_id" + "match" it counts the exists-style cross-table bucket; without "table_id" it counts THIS table's rows matching "where" predicates ("$row.<col>" values partition per row, e.g. employee eq $row.employee). A "no_overlap" rule additionally takes "min_gap"?: number — minimum separation between intervals in the same scope partition (numeric bounds: plain number; datetime: minutes; date: days; touching at exactly min_gap is allowed) — and bounds its intervals EITHER with "start_column"+"end_column" OR with "interval_column" (ONE interval-type column whose {start, end} cell carries both bounds; datetime class, min_gap in minutes) — never both. A "channel" rule (SCP v1.3) takes EITHER {"column", "require_present", "read_op"?: "subset" | "overlaps"} or {"policy": <node tree>}, plus "enforcement": "observe" | "enforce" — see ChannelRuleFlat / ChannelRulePolicy. An "invariant" rule takes {"policy": <node tree>, "enforcement"} and is principal-blind: it holds for every writer on every path — see InvariantRule. An "immutable_when" rule takes {"prior_when": [predicates], "columns": [refs]} and takes no "when": prior_when is the lock condition evaluated against the row's PRE-image (the row before the write); while it matches, the listed columns may not change (400 on violation). Locks stored inline columns only (not computed/link).

回應結構

RulesPreviewResponse
欄位型別必填說明
invariant_violationsinteger否Sampled rows that already fail the candidate INVARIANT rules. Reported once, not per room: an invariant has no principal. Such rows stay readable but become uneditable until repaired.
roomsRulesPreviewRoomImpact[]否Per acting room, for the CHANNEL rules. Empty when the candidate carries no channel rule or the table has no chatroom grants.
sample_capinteger是The sampling cap applied.
sampled_rowsinteger是Live rows actually evaluated (the first N by sort_order). EVERY count below is out of this number, not out of total_rows.
table_idstring是The table previewed.
total_rowsinteger是Live rows in the table. Greater than sampled_rows ⇒ the preview was truncated and says so in warnings.
warningsstring[]否Truncation notices and lockout alarms, in plain language.

範例

預覽唯一值規則

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "rules": [
      {
        "type": "unique",
        "name": "訂單編號不可重複",
        "columns": [
          "訂單編號"
        ],
        "case_insensitive": true
      }
    ]
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "sampled_rows": 1,
  "total_rows": 1,
  "sample_cap": 200,
  "rooms": [],
  "invariant_violations": 0,
  "warnings": []
}

錯誤

狀態發生條件錯誤本文
400候選規則的結構或語意不合法。
{
  "detail": "rules[0]: invalid rule type 'unknown'. valid types: compare, unique, no_overlap, exists, not_exists, transition, check, require, require_approval, channel, invariant, immutable_when"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/triggers

取得資料表觸發器

用途

回傳資料表已設定的正規化事件觸發器與動作。

適用時機

適合顯示自動化設定，或在取代前保留現有觸發器。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/triggers
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/triggers
  • 公司/private/module/custom_tables/company/tables/{table_id}/triggers

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableAccessRequired
部門可使用CustomTableAccessRequired
公司可使用CustomTableAccessRequired

參數

欄位位置型別必填說明
table_idpathuuid是要取得觸發器的資料表 UUID。

回應結構

TableTriggersResponse
欄位型別必填說明
table_idstring是未指定
triggersobject[]否未指定

範例

取得資料列建立通知觸發器

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "triggers": [
    {
      "id": "trg_666666666666",
      "name": "通知新訂單",
      "on": "created",
      "created_by": "44444444-4444-4444-8444-444444444444",
      "when": null,
      "actions": [
        {
          "id": "act_111111111111",
          "type": "notify",
          "chatroom_id": "11111111-1111-4111-8111-111111111111",
          "message": "已建立訂單：$row.訂單編號"
        }
      ]
    }
  ]
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
PUT
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/triggers

取代資料表觸發器

用途

驗證並以原子方式取代事件驅動通知、API／資料表動作、通道附件投遞與 Sandbox 工作提交。

適用時機

要發佈資料表的完整目標觸發器設定時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/triggers
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/triggers
  • 公司/private/module/custom_tables/company/tables/{table_id}/triggers

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要取代觸發器的資料表 UUID。

請求結構

TableTriggersPayload
欄位型別必填說明
triggersobject[]是Full triggers list (PUT replace semantics; at most 50 triggers). Each trigger authors 1 to 5 actions from the ten supported types: webhook, api_call, create_record, update_record, notify, send_channel_message, invoke_command, delete_record, materialize_slots, and submit_sandbox_job. Saved configs preserve exactly one stable identity per action; server-minted values use act_<12 hex>. GET echoes it as action.id, which clients must round-trip when replacing the list. materialize_slots fails closed before any slot insert when more than 1000 live source rows are scanned; truncating slot inserts at 1000 per tick remains success.

回應結構

TableTriggersResponse
欄位型別必填說明
table_idstring是未指定
triggersobject[]否未指定

範例

建立資料列時通知聊天室

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "triggers": [
      {
        "name": "通知新訂單",
        "on": "created",
        "actions": [
          {
            "type": "notify",
            "chatroom_id": "11111111-1111-4111-8111-111111111111",
            "message": "已建立訂單：$row.訂單編號"
          }
        ]
      }
    ]
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "triggers": [
    {
      "id": "trg_666666666666",
      "name": "通知新訂單",
      "on": "created",
      "created_by": "44444444-4444-4444-8444-444444444444",
      "when": null,
      "actions": [
        {
          "id": "act_111111111111",
          "type": "notify",
          "chatroom_id": "11111111-1111-4111-8111-111111111111",
          "message": "已建立訂單：$row.訂單編號"
        }
      ]
    }
  ]
}

傳送附件欄位並提交 pinned Sandbox task version

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "triggers": [
      {
        "name": "傳送附件並建立 Sandbox 工作",
        "on": "created",
        "actions": [
          {
            "type": "send_channel_message",
            "recipient": "created_by_client",
            "message": "訂單附件：$row.訂單編號",
            "attachments": [
              {
                "column": "col_a1111111_1111_4111_8111_111111111111"
              }
            ]
          },
          {
            "type": "submit_sandbox_job",
            "chatroom_id": "11111111-1111-4111-8111-111111111111",
            "task_version_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
            "timeout_seconds": 900,
            "input": {
              "order_id": "$row.訂單編號"
            }
          }
        ]
      }
    ]
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "triggers": [
    {
      "id": "trg_777777777777",
      "name": "傳送附件並建立 Sandbox 工作",
      "on": "created",
      "actions": [
        {
          "type": "send_channel_message",
          "recipient": "created_by_client",
          "message": "訂單附件：$row.訂單編號",
          "attachments": [
            {
              "column": "col_a1111111_1111_4111_8111_111111111111"
            }
          ],
          "id": "act_222222222222"
        },
        {
          "type": "submit_sandbox_job",
          "chatroom_id": "11111111-1111-4111-8111-111111111111",
          "task_version_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
          "timeout_seconds": 900,
          "input": {
            "order_id": "$row.訂單編號"
          },
          "id": "act_333333333333"
        }
      ],
      "created_by": "44444444-4444-4444-8444-444444444444",
      "when": null
    }
  ]
}

錯誤

狀態發生條件錯誤本文
400觸發事件、條件或動作無效，或動作數量超出支援範圍。
{
  "detail": "triggers[0]: actions must be a list of 1..5"
}
400資料表帶有通道範圍限制政策，無法與觸發器併用。
{
  "detail": "this table carries a channel-scoped constraint policy; triggers are not supported on channel-governed tables"
}
400某個 trigger 保留原 id 卻更改了 schedule.type；schedule identity 依 kind 區分，請讓舊 id 退役，並用新 id 建立新 kind。
{
  "detail": "schedule_kind_change_requires_new_trigger_id: trigger 'trg_666666666666' changes its schedule type in place. retire the old trigger id and create the new schedule kind under a new trigger id"
}
409Locked-graph 重新驗證或非資料庫的 compile／refresh failure，使伺服器無法安全更新所有先前仍有效的相依 commands。這個結構化錯誤與下方 flat-detail database errors 不同；trigger JSON、schema history 紀錄與所有 command definition 更新會在同一個交易中一起回滾。
{
  "detail": {
    "error": "command_dependency_refresh_failed",
    "message": "a dependent Custom Table command cannot accept the candidate triggers"
  }
}
409Trigger-update transaction 中遇到 MySQL 1205 lock-wait timeout 或 1213 deadlock。完整 transaction 已回滾；這個可重試 409 使用 flat string detail，不是 command_dependency_refresh_failed。
{
  "detail": "Concurrent write conflict (lock); please retry the request."
}
500發生其他 database operational failure。完整 transaction 已回滾，response 會淨化成 flat detail：Database operation failed.。
{
  "detail": "Database operation failed."
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/triggers/schedule-preview

預覽排程觸發器的評估結果

用途

以 scheduler 自己的 evaluator 唯讀地評估這張表上每一個 schedule trigger，回傳每個 trigger 的機器可讀原因計數與時鐘狀態。

適用時機

當 scheduler tick 健康卻一直回報零筆 run，而你需要知道資料列是缺日期、仍在未來、被 when 排除、已經消耗，還是真的到期時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/triggers/schedule-preview
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/triggers/schedule-preview
  • 公司/private/module/custom_tables/company/tables/{table_id}/triggers/schedule-preview

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要評估其 schedule triggers 的資料表 UUID。

回應結構

TableSchedulePreviewResponse
欄位型別必填說明
evaluated_atstring (date-time)是未指定
live_recordsinteger是未指定
record_limitinteger否未指定
table_idstring是未指定
triggers(InvalidSchedulePreview | DateColumnReachedSchedulePreview | IntervalSchedulePreview | DailySchedulePreview | CronSchedulePreview)[]否未指定

範例

預覽一張含 date trigger、interval trigger 與一個損毀儲存 trigger 的表

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "table_id": "22222222-2222-4222-8222-222222222222",
  "evaluated_at": "2026-08-27T05:02:13",
  "live_records": 2,
  "record_limit": 1000,
  "triggers": [
    {
      "kind": "date_column_reached",
      "trigger_id": "trg_666666666666",
      "config_status": "valid",
      "already_fired": 1,
      "records_scanned": 2,
      "missing_schedule_value": 0,
      "invalid_schedule_value": 0,
      "scheduled_for_future": 1,
      "when_filter_mismatch": 0,
      "due_now": 0,
      "unscanned": 0,
      "truncated": false,
      "warnings": []
    },
    {
      "kind": "interval",
      "trigger_id": "trg_777777777777",
      "config_status": "valid",
      "last_consumed_window_at": "2026-08-27T05:00:00",
      "due_at": null,
      "due_now": false,
      "active_run": false,
      "warnings": [
        "when_ignored_for_recordless_schedule"
      ]
    },
    {
      "kind": "invalid",
      "trigger_id": "trg_888888888888",
      "stored_schedule_type": "monthly",
      "config_status": "invalid",
      "error_codes": [
        "unsupported_schedule_type"
      ],
      "warnings": []
    }
  ]
}

錯誤

狀態發生條件錯誤本文
404這個 scope 沒有該資料表，或該表已在垃圾桶。
{
  "detail": "Table not found in this chatroom"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/trigger-runs

列出觸發器執行記錄

用途

回傳資料表非同步觸發動作的分頁執行記錄。

適用時機

適合監測自動化健康狀態、檢查失敗，或在重試前找到執行記錄。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/trigger-runs
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/trigger-runs
  • 公司/private/module/custom_tables/company/tables/{table_id}/trigger-runs

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要列出觸發器執行記錄的資料表 UUID。
statusqueryenum:pending|running|done|failed|stuck否選填的執行狀態：pending、running、done、failed 或 stuck。
skipqueryint >= 0否略過前幾筆符合條件的執行記錄，預設為 0。
limitqueryint 1..200否最多回傳幾筆執行記錄，可填 1 到 200。

回應結構

TriggerRunListResponse
欄位型別必填說明
runsTriggerRunResponse[]是未指定
totalinteger是未指定

範例

列出失敗的觸發器執行記錄

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "query": {
    "status": "failed",
    "skip": "0",
    "limit": "50"
  }
}
回應200
{
  "runs": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "trigger_id": "trg_666666666666",
      "record_id": "33333333-3333-4333-8333-333333333333",
      "record_version": 1,
      "event": "created",
      "status": "failed",
      "attempts": 3,
      "error": "Webhook returned HTTP 500",
      "chain_id": "77777777-7777-4777-8777-777777777777",
      "depth": 0,
      "payload": {
        "event": "created",
        "table_id": "22222222-2222-4222-8222-222222222222",
        "record_id": "33333333-3333-4333-8333-333333333333",
        "data": {
          "訂單編號": "ORD-1001"
        }
      },
      "action_results": [
        {
          "action_index": 0,
          "ok": false,
          "error": "HTTP 500"
        }
      ],
      "created_at": "2026-07-19T03:00:00",
      "updated_at": "2026-07-19T03:05:00"
    }
  ],
  "total": 1
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/trigger-runs/{run_id}/retry

重試觸發器執行

用途

將符合條件的失敗、待執行或過期執行記錄重新放回觸發器佇列。

適用時機

排除下游錯誤後，重排 failed、pending 或逾時 running 執行；已完成的 run 不能重試。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/trigger-runs/{run_id}/retry
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/trigger-runs/{run_id}/retry
  • 公司/private/module/custom_tables/company/tables/{table_id}/trigger-runs/{run_id}/retry

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是擁有觸發器執行記錄的資料表 UUID。
run_idpathuuid是要重試的觸發器執行 UUID。

回應結構

TriggerRunResponse
欄位型別必填說明
action_resultsobject[] | null否Per-action results written by the worker
attemptsinteger是未指定
chain_idstring是未指定
created_atstring (date-time)是未指定
depthinteger是未指定
errorstring | null是未指定
eventstring是未指定
idstring是未指定
payloadobject | null否Trigger-time row snapshot + change metadata (the webhook payload)
record_idstring | null是未指定
record_versioninteger是未指定
statusstring是pending | running | done | failed
table_idstring是未指定
trigger_idstring是未指定
updated_atstring (date-time)是未指定

範例

將失敗的觸發器執行重新排入佇列

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "run_id": "55555555-5555-4555-8555-555555555555"
  }
}
回應200
{
  "id": "55555555-5555-4555-8555-555555555555",
  "table_id": "22222222-2222-4222-8222-222222222222",
  "trigger_id": "trg_666666666666",
  "record_id": "33333333-3333-4333-8333-333333333333",
  "record_version": 1,
  "event": "created",
  "status": "pending",
  "attempts": 3,
  "error": null,
  "chain_id": "77777777-7777-4777-8777-777777777777",
  "depth": 0,
  "payload": {
    "event": "created",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333",
    "data": {
      "訂單編號": "ORD-1001"
    }
  },
  "action_results": [
    {
      "action_index": 0,
      "ok": false,
      "error": "HTTP 500"
    }
  ],
  "created_at": "2026-07-19T03:00:00",
  "updated_at": "2026-07-19T03:05:00"
}

錯誤

狀態發生條件錯誤本文
404這張資料表沒有指定觸發器執行記錄。
{
  "detail": "Trigger run not found"
}
409執行已完成，或處於其他不可重試的狀態。
{
  "detail": "run is done; only failed/pending (or stale-running) runs can be retried"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/staged-changes

列出階段性變更

用途

列出被 require_approval 規則暫緩的寫入，以及審核與套用狀態。

適用時機

適合監測需核准的寫入，或調查為何資料列被待審狀態擋住。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/staged-changes
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/staged-changes
  • 公司/private/module/custom_tables/company/tables/{table_id}/staged-changes

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableAccessRequired
部門可使用CustomTableAccessRequired
公司可使用CustomTableAccessRequired

參數

欄位位置型別必填說明
table_idpathuuid是要列出階段性變更的資料表 UUID。
statusqueryenum:pending|applying|applied|apply_failed|discarded否選填的進程狀態：pending、applying、applied、apply_failed 或 discarded。
change_typequeryenum:create|update|delete|restore|revert|batch_actions否選填的暫緩操作類型，例如 create、update、delete、restore、revert 或 batch_actions。
skipqueryint >= 0否略過前幾筆符合條件的階段性變更，預設為 0。
limitqueryint 1..200否最多回傳幾筆階段性變更，可填 1 到 200。

回應結構

StagedChangeListResponse
欄位型別必填說明
staged_changesStagedChangeResponse[]是Visible staged changes, newest first
totalinteger是Total visible staged changes matching the filters (before pagination)

範例

列出待審階段性變更

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "query": {
    "status": "pending",
    "skip": "0",
    "limit": "50"
  }
}
回應200
{
  "staged_changes": [],
  "total": 0
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/staged-changes/discard

捨棄階段性變更

用途

嘗試將指定的未解決核准寫入標記為已捨棄。

適用時機

被暫緩的寫入應直接作廢，而不是核准並套用時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/staged-changes/discard
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/staged-changes/discard
  • 公司/private/module/custom_tables/company/tables/{table_id}/staged-changes/discard

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是擁有階段性變更的資料表 UUID。

請求結構

StagedChangeDiscardRequest
欄位型別必填說明
staged_change_idsstring[]是Staged change ids to discard (1..50); each is looked up anchored to the path table_id

回應結構

StagedChangeDiscardResponse
欄位型別必填說明
discardedinteger是How many ids were discarded this call
resultsStagedChangeDiscardResult[]是One result per requested id, in request order

範例

捨棄一個階段性變更 ID

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "staged_change_ids": [
      "88888888-8888-4888-8888-888888888888"
    ]
  }
}
回應200
{
  "results": [
    {
      "staged_change_id": "88888888-8888-4888-8888-888888888888",
      "ok": false,
      "outcome": "not_found",
      "status": null
    }
  ],
  "discarded": 0
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/callback-tokens

簽發回呼 token

用途

建立綁定資料表的 token，供已驗證的公開回呼寫入，並只回傳一次密鑰。

適用時機

要為外部回呼程式配置新增，或新增與更新能力時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/callback-tokens
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/callback-tokens
  • 公司/private/module/custom_tables/company/tables/{table_id}/callback-tokens

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要綁定回呼 token 的資料表 UUID。

請求結構

CallbackTokenMintPayload
欄位型別必填說明
allowed_ops"create" | "create,update"否Operations the token may perform
namestring | null否Label shown in listings
valid_untilstring (date-time) | null否Expiry (UTC); null = no expiry. Expired tokens answer the uniform 404.

回應結構

CallbackTokenMintResponse
欄位型別必填說明
allowed_opsstring是未指定
secretstring是Bearer secret — shown ONCE, never retrievable again
table_idstring是未指定
token_idstring是The URL path segment: POST /public/module/custom_tables/callback/{token_id}
valid_untilstring (date-time) | null是未指定

範例

簽發可新增與更新的回呼 token

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "name": "訂單系統回呼",
    "allowed_ops": "create,update",
    "valid_until": null
  }
}
回應201
{
  "token_id": "99999999-9999-4999-8999-999999999999",
  "secret": "cbsec_catalog_example_only_0000000000000000",
  "table_id": "22222222-2222-4222-8222-222222222222",
  "allowed_ops": "create,update",
  "valid_until": null
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
422token 名稱、允許的操作集合或到期時間不合法。
{
  "detail": [
    {
      "type": "literal_error",
      "loc": [
        "body",
        "allowed_ops"
      ],
      "msg": "Input should be 'create' or 'create,update'",
      "input": "update",
      "ctx": {
        "expected": "'create' or 'create,update'"
      }
    }
  ]
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/callback-tokens

列出回呼 token

用途

回傳資料表回呼 token 的基本資訊、能力、到期時間與撤銷狀態。

適用時機

適合稽核整合，或在撤銷前找到 token ID。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/callback-tokens
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/callback-tokens
  • 公司/private/module/custom_tables/company/tables/{table_id}/callback-tokens

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是要列出回呼 token 的資料表 UUID。

回應結構

CallbackTokenListResponse
欄位型別必填說明
tokensCallbackTokenInfo[]是未指定

範例

列出回呼 token 基本資訊

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "tokens": [
    {
      "id": "99999999-9999-4999-8999-999999999999",
      "name": "訂單系統回呼",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "allowed_ops": "create,update",
      "valid_until": null,
      "revoked": false,
      "created_by": "44444444-4444-4444-8444-444444444444",
      "created_at": "2026-07-19T03:00:00"
    }
  ]
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
DELETE
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/callback-tokens/{token_id}

撤銷回呼 token

用途

永久停用一組資料表專屬憑證，使後續 public callback 寫入回傳與無效驗證相同的隱蔽 404。

適用時機

輪替憑證、停用整合，或懷疑憑證外洩時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/{chatroom_id}/tables/{table_id}/callback-tokens/{token_id}
  • 部門/private/module/custom_tables/department/{department_id}/tables/{table_id}/callback-tokens/{token_id}
  • 公司/private/module/custom_tables/company/tables/{table_id}/callback-tokens/{token_id}

範圍

範圍是否提供驗證與權限
聊天室可使用CustomTableModeratorRequired
部門可使用CustomTableModeratorRequired
公司可使用CustomTableModeratorRequired

參數

欄位位置型別必填說明
table_idpathuuid是擁有回呼 token 的資料表 UUID。
token_idpathuuid是要撤銷的回呼 token UUID。

回應結構

SuccessResponse
欄位型別必填說明
messagestring否未指定

範例

撤銷一組回呼 token

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "token_id": "99999999-9999-4999-8999-999999999999"
  }
}
回應200
{
  "message": "Callback token revoked"
}

錯誤

狀態發生條件錯誤本文
404這張資料表沒有該 token，或指定範圍無法看到它。
{
  "detail": "Callback token not found"
}
409撤銷在鎖競爭中落敗，「沒有」發生——token 仍然存活、仍接受 callback 寫入。重試直到拿到 200；只有 200 才確認撤銷完成。
{
  "detail": "Concurrent write conflict (lock); please retry the request."
}
Last updated on
公開讀取權杖複合指令