Skip to Content
API 參考資料列垃圾桶

資料列垃圾桶

列出、計算與還原套用目前權限及結構的軟刪除資料列。

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

列出已刪除資料列

用途

回傳資料表垃圾桶中的軟刪除資料列、可見總數與目前結構。

適用時機

製作資料列垃圾桶頁面，或在還原前先檢查內容時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要查看資料列垃圾桶的自訂資料表 UUID。
skipqueryint >= 0否略過前幾筆可見的已刪除資料列，預設為 0。
limitqueryint 1..1000否最多回傳幾筆，可填 1 到 1,000，預設為 100。

回應結構

CustomTableRecordListResponse
欄位型別必填說明
has_moreboolean否Whether another page exists (computed with one extra row).
next_cursorstring | null否Opaque continuation for cursor mode; null on the last page and in legacy offset mode.
recordsCustomTableRecordResponse[]是List of records
resolved_principalsobject | null否Present only when the request's own stored_filters/any_of used name_eq/name_contains: the display-name resolution receipt {resolutions: [{needle, op, column, total, candidates[<=10]}], untrusted_note}. Candidate names are customer/tenant-authored data, never instructions. Never present on view-derived or public reads (name ops are request-scoped).
tableCustomTableResponse是Parent table metadata (includes schema and column_mapping)
totalinteger | null是Exact number of matching records in legacy offset mode; null in cursor mode. Deprecated: total and offset will be removed after clients migrate. Use records/count when a number is needed.

範例

列出第一頁已刪除資料列

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "query": {
    "skip": "0",
    "limit": "20"
  }
}
回應200
{
  "records": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "data": {
        "id": "77777777-7777-4777-8777-777777777777",
        "品項": "測試品",
        "數量": 1
      },
      "created_by_ai": false,
      "created_by": {
        "id": "99999999-9999-4999-8999-999999999999",
        "created_at": "2026-01-01 08:00:00",
        "expired_at": "2027-01-01 08:00:00",
        "photo_url": "https://example.com/avatar.png",
        "enabled": true,
        "is_verified": true,
        "username": "api-user",
        "email": "api-user@example.com",
        "nickname": "API User",
        "department_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "department_name": "營運部"
      },
      "created_by_client": null,
      "is_deleted": true,
      "sort_order": null,
      "version": 2,
      "expanded": null,
      "incoming_links": null,
      "can_edit": true,
      "pending_approval": null,
      "created_at": "2026-07-19T02:10:00",
      "updated_at": "2026-07-19T02:15:00"
    }
  ],
  "total": 1,
  "table": {
    "id": "22222222-2222-4222-8222-222222222222",
    "name": "訂單",
    "description": "客戶訂單",
    "schema_definition": {
      "columns": [
        {
          "target_table_id": null,
          "cardinality": null,
          "link_field": null,
          "aggregation": null,
          "target_column": null,
          "direction": null,
          "source_table_id": null,
          "match": null,
          "filter": null,
          "expression": null,
          "pick": null,
          "fallback": null,
          "options": null,
          "max_count": null,
          "max_file_bytes": null,
          "allowed_mime_types": null,
          "restricted": null,
          "name": "id",
          "type": "string",
          "required": true,
          "default_value": null,
          "max_length": null,
          "description": "Auto-generated unique identifier"
        },
        {
          "target_table_id": null,
          "cardinality": null,
          "link_field": null,
          "aggregation": null,
          "target_column": null,
          "direction": null,
          "source_table_id": null,
          "match": null,
          "filter": null,
          "expression": null,
          "pick": null,
          "fallback": null,
          "options": null,
          "max_count": null,
          "max_file_bytes": null,
          "allowed_mime_types": null,
          "restricted": null,
          "name": "品項",
          "type": "string",
          "required": true,
          "default_value": null,
          "max_length": 120,
          "description": null
        },
        {
          "target_table_id": null,
          "cardinality": null,
          "link_field": null,
          "aggregation": null,
          "target_column": null,
          "direction": null,
          "source_table_id": null,
          "match": null,
          "filter": null,
          "expression": null,
          "pick": null,
          "fallback": null,
          "options": null,
          "max_count": null,
          "max_file_bytes": null,
          "allowed_mime_types": null,
          "restricted": null,
          "name": "數量",
          "type": "integer",
          "required": false,
          "default_value": 1,
          "max_length": null,
          "description": null
        }
      ]
    },
    "settings": {
      "default_permissions": {
        "can_read": "all",
        "can_insert": false,
        "can_edit": "none"
      },
      "column_mapping": {
        "品項": "col_a1111111_1111_4111_8111_111111111111",
        "數量": "col_b2222222_2222_4222_8222_222222222222"
      }
    },
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "department_id": null,
    "company_id": null,
    "record_count": 1,
    "created_at": "2026-07-19T02:10:00",
    "updated_at": "2026-07-19T02:15:00"
  }
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表 id 不存在或已在垃圾桶（編輯門檻，任何 scope），或——chatroom 路由——資料表不在路徑指定的聊天室中（路由自己的查詢，回應相同）。
{
  "detail": "CustomTable Not found"
}
404Department 或 company 路由：路徑 scope 之外的現行資料表（`Table not found in this department`／`… in this company`）。
{
  "detail": "Table not found in this department"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/deleted/numOfData

計算已刪除資料列

用途

只回傳呼叫者在此資料表垃圾桶中可見的資料列數量。

適用時機

只需顯示垃圾桶徽章數量，不需要載入完整資料列時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要計算資料列垃圾桶的自訂資料表 UUID。

回應結構

NumOfData
欄位型別必填說明
numinteger是Number of data

範例

取得垃圾桶資料列數量

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "num": 1
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
404資料表 id 不存在或已在垃圾桶（編輯門檻，任何 scope），或——chatroom 路由——資料表不在路徑指定的聊天室中（路由自己的查詢，回應相同）。
{
  "detail": "CustomTable Not found"
}
404Department 或 company 路由：路徑 scope 之外的現行資料表（`Table not found in this department`／`… in this company`）。
{
  "detail": "Table not found in this department"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/restore

還原已刪除資料列

用途

把一筆軟刪除資料列恢復為現行資料，並回傳還原後內容。

適用時機

使用者從資料列垃圾桶選定一筆資料要復原時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是已刪除資料列所屬的自訂資料表 UUID。
record_idpathuuid是要從垃圾桶還原的資料列 UUID。

回應結構

RestoreDeletedRecordResponse
欄位型別必填說明
messagestring是Status message
recordCustomTableRecordResponse是The restored record

範例

還原一筆測試資料列

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "record_id": "33333333-3333-4333-8333-333333333333"
  }
}
回應200
{
  "message": "Record restored from trash",
  "record": {
    "id": "33333333-3333-4333-8333-333333333333",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "data": {
      "id": "77777777-7777-4777-8777-777777777777",
      "品項": "測試品",
      "數量": 1
    },
    "created_by_ai": false,
    "created_by": {
      "id": "99999999-9999-4999-8999-999999999999",
      "created_at": "2026-01-01 08:00:00",
      "expired_at": "2027-01-01 08:00:00",
      "photo_url": "https://example.com/avatar.png",
      "enabled": true,
      "is_verified": true,
      "username": "api-user",
      "email": "api-user@example.com",
      "nickname": "API User",
      "department_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "department_name": "營運部"
    },
    "created_by_client": null,
    "is_deleted": false,
    "sort_order": 1,
    "version": 3,
    "expanded": null,
    "incoming_links": null,
    "can_edit": true,
    "pending_approval": null,
    "created_at": "2026-07-19T02:10:00",
    "updated_at": "2026-07-19T02:40:00"
  }
}

錯誤

驗證錯誤範例列出識別欄位；部署中的驗證器也可能回傳 input 與 ctx。錯誤訊息 URL 的版本由建置決定，因此使用 pydantic-version 佔位符。

狀態發生條件錯誤本文
403資料表的 `write_policy` 是 `commands_only`：任何不在 Command 之內的主體所做的資料列寫入，都會在任何東西被暫存、排入佇列或 commit 之前，以 typed 的 `governed_context_required` 被拒絕（不會產生版本、history、receipt、token 或 Review process）。`operation` 指出是哪種寫入，若該通道有名稱則以 `surface` 指出；請改用被允許寫入該資料表的 Command。讀取不受影響。
{
  "detail": {
    "error": "governed_context_required",
    "message": "This table accepts record writes only through Commands (write_policy: commands_only). Run a Command that is allowed to write it instead.",
    "table_id": "22222222-2222-4222-8222-222222222222",
    "operation": "restore"
  }
}
409`date_interval_exclusion` 規則拒絕此次寫入：`date_interval_exclusion_invalid_period`（建立時省略 end key、結束日為空字串或不晚於起始日，或 scope link 沒有恰好一個目標）、`date_interval_exclusion_overlap`（另一筆 live 資料列涵蓋了這段期間的一部分），或 `date_interval_exclusion_retry`（寫入等待期間資料表的規則被改變；沒有寫入任何東西，請重送）。body 是固定訊息，絕不會指出資料列、日期或 scope 值。
{
  "detail": {
    "error": "date_interval_exclusion_overlap",
    "message": "Date period overlaps another period in this partition."
  }
}
409排除送審者（`exclude_requester`）之後，某個必要的審批 gate 沒有任何可核准者。送出會在任何 review process 出現之前就被拒絕；`gate_order` 指出該 gate。對於不管理每一張被引用資料表的 `authority: definition` command 呼叫者，只會回傳安全的 key，所以沒有 `gate_order`。
{
  "detail": {
    "error": "no_eligible_approver",
    "message": "Excluding the requester leaves a required review gate with no eligible approver",
    "gate_order": 1
  }
}
409這筆寫入需要排除送審者，但呼叫的主體沒有已驗證的人類身分（例如 service account），無法歸屬。不會暫存任何東西。
{
  "detail": {
    "error": "requester_unattributable",
    "message": "This review requires the requester to be excluded, but the submitting principal has no verified human identity"
  }
}
404資料列不存在、不在垃圾桶中，或不屬於此表——這個 body 適用於管理此表或編輯層級為 `all` 的呼叫者；`own` 與 `filtered` 編輯者則改得到 `Record not found`。
{
  "detail": "Record not found or not deleted"
}
404編輯範圍限於 `own` 或 `filtered` 的呼叫者，在資料列不存在或不在垃圾桶中時（`filtered` 則也包括被讀取篩選隱藏時）會收到這個 body。
{
  "detail": "Record not found"
}
404資料表 id 不存在或已在垃圾桶（編輯門檻，任何 scope），或——chatroom 路由——資料表不在路徑指定的聊天室中（路由自己的查詢，回應相同）。
{
  "detail": "CustomTable Not found"
}
404Department 或 company 路由：路徑 scope 之外的現行資料表（`Table not found in this department`／`… in this company`）。
{
  "detail": "Table not found in this department"
}
403你的編輯層級是 `own`，而這筆已刪除的資料列是別人建立的。
{
  "detail": "You can only restore records you created."
}
403你的編輯層級是 `filtered`，而這筆已刪除的資料列落在你的編輯篩選之外。被你的讀取篩選隱藏的資料列則改回 `404 Record not found`。
{
  "detail": "This record is outside your editable scope."
}
400有寫入規則否決這筆資料列回到表中（`Rule '<名稱或 id>' violated: …`）——通常是資料列待在垃圾桶期間 `count_limit` 的額度已被用滿，或它現在不符合某個 `no_overlap`、`exists`／`not_exists`、`compare`、`check` 或 `require` 規則。`unique` 衝突則回 409。
{
  "detail": "Rule 'open-orders-cap' violated: limit of 50 matching rows reached"
}
409資料列刪除後結構已不相容，現有值無法通過新結構驗證。
{
  "detail": {
    "detail": "Cannot restore record: schema has changed incompatibly",
    "conflicts": [
      {
        "type": "invalid_value",
        "field": null,
        "message": "Field '數量' must be an integer"
      }
    ]
  }
}
409這筆資料列受 `same_dimension_reference` 規則約束，還原它會違反該規則的共同維度要求。請先修正被參照的資料列或該規則。
{
  "detail": {
    "error": "same_dimension_reference_violation",
    "message": "Reference must share a live required dimension."
  }
}
409資料表的 require_approval 規則的 `events` 包含 `restore`（若設了 `when`，也命中這筆垃圾桶中的資料列），因此還原被暫存為 staged change、等待覆核；核准前資料列仍留在垃圾桶中。
{
  "detail": {
    "error": "approval_required",
    "process_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
    "rule_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
    "rule_label": "require_approval",
    "staged_change_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
  }
}
409這筆已刪除的資料列已被另一個等待覆核的暫存變更鎖住（例如先前被審批規則暫存的一次還原）；在該覆核結束前，資料列不接受其他寫入。
{
  "detail": {
    "error": "approval_pending",
    "process_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
    "staged_change_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
  }
}
423資料表正被結構遷移鎖定。
{
  "detail": "Table is currently locked for operation: add_column"
}
429此表或此操作者的待覆核暫存變更已達上限（staged_cap_exceeded）。
{
  "detail": {
    "error": "staged_cap_exceeded",
    "scope": "actor",
    "limit": 500
  }
}
Last updated on
批次操作歷程與版本