Skip to Content
API 參考建立、診斷與遷移

建立、診斷與遷移

初始化資料表與結構、產生測試資料、執行診斷，並追蹤背景遷移工作。

POST
路由範本/private/module/custom_tables/{scope}/tables/bootstrap

建立資料表並寫入初始資料

用途

一次建立一張資料表，並依序走一般新增流程寫入最多 200 筆種子資料。

適用時機

新功能初始化時，結構與少量初始資料需要一起建立時使用。

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

範圍

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

請求結構

TableBootstrapRequest
欄位型別必填說明
created_by_aiboolean否Mark seeded records AI-authored
rowsobject[]否Seed record data dicts (display-name OR internal keys), inserted synchronously in order; max 200 (use bulk-insert for more)
tableCustomTableCreate是Table definition (same as POST .../tables)

回應結構

TableBootstrapResponse
欄位型別必填說明
recordsCustomTableRecordResponse[]否The seeded records in insertion order
tableCustomTableResponse是The created table (same as POST .../tables)

範例

建立庫存資料表與第一筆庫存

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "table": {
      "name": "庫存",
      "description": "目前庫存量",
      "schema_definition": {
        "columns": [
          {
            "name": "品項",
            "type": "string",
            "required": true
          },
          {
            "name": "數量",
            "type": "integer"
          }
        ]
      }
    },
    "rows": [
      {
        "品項": "筆記本",
        "數量": 20
      }
    ],
    "created_by_ai": false
  }
}
回應201
{
  "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": null,
          "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": null,
          "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": 0,
    "created_at": "2026-07-19T02:20:00",
    "updated_at": "2026-07-19T02:25:00"
  },
  "records": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "data": {
        "id": "77777777-7777-4777-8777-777777777777",
        "品項": "筆記本",
        "數量": 20
      },
      "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": 1,
      "expanded": null,
      "incoming_links": null,
      "can_edit": true,
      "pending_approval": null,
      "created_at": "2026-07-19T02:20:00",
      "updated_at": "2026-07-19T02:25:00"
    }
  ]
}

錯誤

狀態發生條件錯誤本文
400某筆種子資料無法通過一般新增驗證。
{
  "detail": "Seed row 0: Validation errors: Field '品項' is required"
}
400在 chatroom 或 company scope 的 bootstrap 上送了 `settings.default_permissions.audience: "company"`。detail 就是這一整句，而且整個呼叫在資料表列寫入之前就失敗——沒有表，也沒有種子資料列。這種分享只有在部門 scope 的表上才有意義，在那裡它取代了逐部門建立授權列。
{
  "detail": "settings.default_permissions.audience \"company\" is only valid on department-scoped tables"
}
400`audience` 帶了 `"scope"` 與 `"company"` 以外的值——該值會以 `repr` 形式回拋，所以 `"everyone"` 會呈現成 `'everyone'`。與 default-permissions 的 PATCH 不同，這條通道收的是 raw settings dict 而非 Pydantic `Literal`，因此錯誤的值會一路走到文法閘門，回 `400` 而不是一般的 `422` 驗證 body。
{
  "detail": "settings.default_permissions.audience must be \"scope\" or \"company\", got 'everyone'"
}
422資料表規格不合法，或 rows 超過 200 筆。
{
  "detail": [
    {
      "type": "too_long",
      "loc": [
        "body",
        "rows"
      ],
      "msg": "List should have at most 200 items",
      "input": []
    }
  ]
}
POST
路由範本/private/module/custom_tables/{scope}/tables/bootstrap-schema

建立互相連結的多張資料表

用途

以請求內 alias 表示跨表參照，依相依順序建立最多 20 張資料表。

適用時機

要一次初始化一組有 link、rollup 或 lookup 相依關係的資料表時使用。

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

範圍

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

請求結構

SchemaBootstrapRequest
欄位型別必填說明
tablesSchemaBootstrapTable[]是Table specs (max 20); aliases must be unique within the request

回應結構

SchemaBootstrapResponse
欄位型別必填說明
tablesSchemaBootstrapResultEntry[]否未指定

範例

以 alias 建立客戶與訂單資料表

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "tables": [
      {
        "alias": "orders",
        "name": "訂單",
        "columns": [
          {
            "name": "編號",
            "type": "string",
            "required": true
          },
          {
            "name": "客戶",
            "type": "link",
            "target_table_alias": "customers",
            "cardinality": "one"
          }
        ]
      },
      {
        "alias": "customers",
        "name": "客戶",
        "columns": [
          {
            "name": "名稱",
            "type": "string",
            "required": true
          }
        ]
      }
    ]
  }
}
回應201
{
  "tables": [
    {
      "alias": "orders",
      "table": {
        "id": "55555555-5555-4555-8555-555555555555",
        "name": "訂單",
        "description": null,
        "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": null,
              "description": null
            },
            {
              "target_table_id": "44444444-4444-4444-8444-444444444444",
              "cardinality": "one",
              "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": "link",
              "required": false,
              "default_value": null,
              "max_length": null,
              "description": null
            }
          ]
        },
        "settings": {
          "default_permissions": {
            "can_read": "all",
            "can_insert": false,
            "can_edit": "none"
          },
          "column_mapping": {
            "編號": "col_d4444444_4444_4444_8444_444444444444",
            "客戶": "col_e5555555_5555_4555_8555_555555555555"
          }
        },
        "chatroom_id": "11111111-1111-4111-8111-111111111111",
        "department_id": null,
        "company_id": null,
        "record_count": 0,
        "created_at": "2026-07-19T02:20:00",
        "updated_at": "2026-07-19T02:25:00"
      }
    },
    {
      "alias": "customers",
      "table": {
        "id": "44444444-4444-4444-8444-444444444444",
        "name": "客戶",
        "description": null,
        "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": null,
              "description": null
            }
          ]
        },
        "settings": {
          "default_permissions": {
            "can_read": "all",
            "can_insert": false,
            "can_edit": "none"
          },
          "column_mapping": {
            "名稱": "col_c3333333_3333_4333_8333_333333333333"
          }
        },
        "chatroom_id": "11111111-1111-4111-8111-111111111111",
        "department_id": null,
        "company_id": null,
        "record_count": 0,
        "created_at": "2026-07-19T02:20:00",
        "updated_at": "2026-07-19T02:25:00"
      }
    }
  ]
}

錯誤

狀態發生條件錯誤本文
400alias 重複，或欄位參照請求中不存在的 alias。
{
  "detail": "Table 'orders' references unknown alias 'customers'"
}
400alias 之間形成循環相依，無法先建立任何一張目標表。
{
  "detail": "Circular link references among aliases ['orders', 'customers']; create these tables individually then add the link column"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/test-data

產生測試資料

用途

依欄位型別產生隨機資料列，用於開發、效能與遷移測試。

適用時機

只在可丟棄或明確隔離的測試資料表需要快速造資料時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要插入隨機測試資料的自訂資料表 UUID。

請求結構

TestDataInsertRequest
欄位型別必填說明
record_countinteger是Number of test records to insert

回應結構

TestDataInsertResponse
欄位型別必填說明
background_processingboolean是Whether the insertion is running in background
inserted_countinteger | null否Number of records inserted (for synchronous operations)
messagestring是Status message
migration_idstring | null否Migration ID for tracking background operations
requested_recordsinteger | null否Number of records requested for background processing
total_requestedinteger | null否Total number of records requested

範例

同步產生一筆測試資料

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "record_count": 1
  }
}
回應200
{
  "background_processing": false,
  "inserted_count": 1,
  "total_requested": 1,
  "requested_records": null,
  "migration_id": null,
  "message": "Successfully inserted 1 test records"
}

錯誤

狀態發生條件錯誤本文
400資料表結構無法產生相容資料，或插入流程失敗。
{
  "detail": "Test data insertion failed: unsupported column type"
}
423資料表已被鎖定（detail 使用 Table is locked for operation: <op>；test-data 會取得 test_data_insertion）。
{
  "detail": "Table is locked for operation: test_data_insertion"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/diagnosis

診斷資料表結構與資料

用途

驗證所有資料列、找出結構與完整性問題，並提供效能建議。

適用時機

大量匯入、結構遷移後，或懷疑既有資料不符合目前結構時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要執行診斷的自訂資料表 UUID。

回應結構

TableDiagnosisResponse
欄位型別必填說明
background_processingboolean是Whether the diagnosis is running in background
diagnosis_resultsobject | null否Complete diagnosis results (for synchronous operations)
estimated_recordsinteger | null否Estimated number of records to process
messagestring是Status message
migration_idstring | null否Migration ID for tracking background operations

範例

同步診斷小型資料表

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111",
    "table_id": "22222222-2222-4222-8222-222222222222"
  }
}
回應200
{
  "background_processing": false,
  "migration_id": "88888888-8888-4888-8888-888888888888",
  "estimated_records": null,
  "diagnosis_results": {
    "total_records": 1,
    "valid_records": 1,
    "invalid_records": 0,
    "validation_errors": [],
    "schema_issues": [],
    "data_integrity_issues": [],
    "performance_recommendations": []
  },
  "message": "Diagnosis completed"
}

錯誤

狀態發生條件錯誤本文
400診斷流程無法讀取或驗證目前資料表。
{
  "detail": "Diagnosis failed: invalid table schema"
}
423資料表已被鎖定（detail 使用 Table is locked for operation: <op>；diagnosis 會取得 diagnosis）。
{
  "detail": "Table is locked for operation: diagnosis"
}
GET
路由範本/private/module/custom_tables/{scope}/tables/{table_id}/migration/status

取得資料表遷移鎖定狀態

用途

回傳指定資料表目前是否被遷移鎖定、鎖定資訊與快速資料列數。

適用時機

在可能衝突的結構或資料寫入前，顯示資料表是否暫時忙碌時使用。

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

範圍

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

參數

欄位位置型別必填說明
table_idpathuuid是要檢查鎖定狀態的自訂資料表 UUID。

回應結構

TableMigrationStatusResponse
欄位型別必填說明
is_lockedboolean是Whether the table is currently locked
lock_infoobject是Lock information if table is locked
record_countinteger是Current number of records in the table
table_idstring是Table ID

範例

確認資料表目前未被鎖定

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

錯誤

狀態發生條件錯誤本文
404資料表不存在，或不屬於指定範圍。
{
  "detail": "Table not found"
}
GET
路由範本/private/module/custom_tables/{scopeName}/migrations/{migration_id}/status

依遷移 ID 取得工作進度

用途

回傳背景遷移或診斷工作的狀態、進度、處理筆數與錯誤。

適用時機

端點回傳 migration_id 後，用來輪詢直到 completed 或 failed。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/migrations/{migration_id}/status
  • 部門/private/module/custom_tables/department/migrations/{migration_id}/status
  • 公司/private/module/custom_tables/company/migrations/{migration_id}/status

範圍

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

參數

欄位位置型別必填說明
migration_idpathuuid是全域唯一的背景遷移 UUID。

回應結構

MigrationStatusResponse
欄位型別必填說明
created_atstring是Migration creation timestamp
error_messagestring | null否Error message if migration failed
migrated_recordsinteger是Number of records processed
migration_idstring是Migration ID
operationstring是Migration operation type
progressinteger是Progress percentage (0-100)
statusstring是Current migration status
table_idstring是Table ID
total_recordsinteger是Total records to process
updated_atstring是Last update timestamp

範例

取得已完成診斷工作的進度

請求
{
  "pathParams": {
    "migration_id": "88888888-8888-4888-8888-888888888888"
  }
}
回應200
{
  "migration_id": "88888888-8888-4888-8888-888888888888",
  "table_id": "22222222-2222-4222-8222-222222222222",
  "operation": "diagnosis",
  "status": "completed",
  "progress": 100,
  "total_records": 5001,
  "migrated_records": 5001,
  "error_message": null,
  "created_at": "2026-07-19T02:20:00",
  "updated_at": "2026-07-19T02:25:00"
}

錯誤

狀態發生條件錯誤本文
404找不到此遷移，或無法解析其所屬資料表。
{
  "detail": "Migration not found"
}
GET
路由範本/private/module/custom_tables/{scopeName}/migrations/{migration_id}/diagnosis-results

取得背景診斷結果

用途

依診斷工作的 migration_id 回傳完整驗證、結構、完整性與效能結果。

適用時機

背景 diagnosis 已完成，且需要取得詳細問題清單時使用。

實際掛載路徑
  • 聊天室/private/module/custom_tables/chatroom/migrations/{migration_id}/diagnosis-results
  • 部門/private/module/custom_tables/department/migrations/{migration_id}/diagnosis-results
  • 公司/private/module/custom_tables/company/migrations/{migration_id}/diagnosis-results

範圍

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

參數

欄位位置型別必填說明
migration_idpathuuid是背景診斷工作的全域唯一 UUID。

回應結構

TableDiagnosisResponse
欄位型別必填說明
background_processingboolean是Whether the diagnosis is running in background
diagnosis_resultsobject | null否Complete diagnosis results (for synchronous operations)
estimated_recordsinteger | null否Estimated number of records to process
messagestring是Status message
migration_idstring | null否Migration ID for tracking background operations

範例

取得已完成的背景診斷結果

請求
{
  "pathParams": {
    "migration_id": "88888888-8888-4888-8888-888888888888"
  }
}
回應200
{
  "background_processing": false,
  "migration_id": null,
  "estimated_records": null,
  "diagnosis_results": {
    "total_records": 1,
    "valid_records": 1,
    "invalid_records": 0,
    "validation_errors": [],
    "schema_issues": [],
    "data_integrity_issues": [],
    "performance_recommendations": []
  },
  "message": "Background diagnosis completed"
}

錯誤

狀態發生條件錯誤本文
404診斷尚未產生結果、已過期，或 migration_id 不存在。
{
  "detail": "Diagnosis results not found"
}
Last updated on
自訂 API 工具Root 維運操作