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
欄位型別必填說明
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是Total number of records matching the query (before pagination)

範例

列出第一頁已刪除資料列

請求
{
  "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,
          "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,
          "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,
          "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"
  }
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
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
}

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found in this chatroom"
}
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:15:00"
  }
}

錯誤

狀態發生條件錯誤本文
404資料列不存在、不在垃圾桶中，或不屬於此表。
{
  "detail": "Record not found or not deleted"
}
409資料列刪除後結構已不相容，現有值無法通過新結構驗證。
{
  "detail": {
    "detail": "Cannot restore record: schema has changed incompatibly",
    "conflicts": []
  }
}
409資料表的 require_approval 規則把此次還原暫存為 staged change，等待覆核核准（GA 預設開啟）。
{
  "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"
  }
}
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
批次操作歷程與版本