五次呼叫建立第一張表

這個流程使用聊天室 scope 建立「訂單」資料表，查看後端建立的欄位，再新增、搜尋與讀取一筆資料。五個 request shape 都直接取自 endpoint catalog；範例 UUID 是合成值，真正執行時請換成你的聊天室 ID，以及前一步回傳的 table、column 與 record ID。

開始之前

先依照驗證說明取得 JWT，並確認你對目標聊天室與新資料表具備相應權限。下列 curl 假設目前 shell 已有這些變數：


export BASE_URL='https://api.scfg.io'
export TOKEN='<從應用程式登入取得的 JWT>'
export CHATROOM_ID='<實際的聊天室 UUID>'

1. 建立資料表

精確 request shape（catalog entry tables.create）：


POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables
Authorization: Bearer $TOKEN
Content-Type: application/json
 
{
  "name": "訂單",
  "description": "客戶訂單",
  "schema_definition": {
    "columns": [
      { "name": "品項", "type": "string", "required": true, "max_length": 120 },
      { "name": "數量", "type": "integer", "default_value": 1 }
    ]
  }
}

Copy-paste curl：


curl --request POST \
  "$BASE_URL/private/module/custom_tables/chatroom/$CHATROOM_ID/tables" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "訂單",
    "description": "客戶訂單",
    "schema_definition": {
      "columns": [
        { "name": "品項", "type": "string", "required": true, "max_length": 120 },
        { "name": "數量", "type": "integer", "default_value": 1 }
      ]
    }
  }'

成功時會回傳 201。把回應的 id 放進 TABLE_ID；回應的 settings.column_mapping 也會列出顯示名稱對應的內部欄位 key。


export TABLE_ID='<id from tables.create response>'

在 Playground 開啟（選擇 tables.create）。

2. 查看實際建立的欄位

精確 request shape（catalog entry columns.list）：


GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/columns
Authorization: Bearer $TOKEN

Copy-paste curl：


curl \
  "$BASE_URL/private/module/custom_tables/chatroom/$CHATROOM_ID/tables/$TABLE_ID/columns" \
  --header "Authorization: Bearer $TOKEN"

不要假設欄位名稱就是查詢用 key。從回應找出名稱為「數量」的欄位，把它的內部 id（col_<hex>）存成 QUANTITY_COLUMN：


export QUANTITY_COLUMN='<internal id for 數量>'

在 Playground 開啟（選擇 columns.list）。

3. 新增一筆資料

精確 request shape（catalog entry records.create）：


POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records?include_incoming=false
Authorization: Bearer $TOKEN
Content-Type: application/json
 
{
  "data": { "品項": "筆記本", "數量": 2 },
  "created_by_ai": false
}

Copy-paste curl：


curl --request POST \
  "$BASE_URL/private/module/custom_tables/chatroom/$CHATROOM_ID/tables/$TABLE_ID/records?include_incoming=false" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "data": { "品項": "筆記本", "數量": 2 },
    "created_by_ai": false
  }'

新增資料時可以使用顯示名稱作為 data 的 key。成功時會回傳 201；把回應的資料列 id 存成 RECORD_ID。


export RECORD_ID='<id from records.create response>'

在 Playground 開啟（選擇 records.create）。

4. 搜尋剛新增的資料

精確 request shape（catalog entry records.search）：


POST /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/search?expand_links=false
Authorization: Bearer $TOKEN
Content-Type: application/json
 
{
  "filters": { "col_b2222222_2222_4222_8222_222222222222": 2 },
  "sort_by": "col_b2222222_2222_4222_8222_222222222222",
  "sort_order": "asc",
  "limit": 20,
  "offset": 0
}

Copy-paste curl 使用第二步取得的真實內部欄位 key：


curl --request POST \
  "$BASE_URL/private/module/custom_tables/chatroom/$CHATROOM_ID/tables/$TABLE_ID/records/search?expand_links=false" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "filters": { "$QUANTITY_COLUMN": 2 },
  "sort_by": "$QUANTITY_COLUMN",
  "sort_order": "asc",
  "limit": 20,
  "offset": 0
}
JSON

搜尋的 filter 與 sort 使用內部 col_<hex> key；回傳的 records 則會以顯示名稱呈現資料。

在 Playground 開啟（選擇 records.search）。

5. 依 ID 讀取資料

精確 request shape（catalog entry records.get）：


GET /private/module/custom_tables/chatroom/11111111-1111-4111-8111-111111111111/tables/22222222-2222-4222-8222-222222222222/records/33333333-3333-4333-8333-333333333333?expand_links=false
Authorization: Bearer $TOKEN

Copy-paste curl：


curl \
  "$BASE_URL/private/module/custom_tables/chatroom/$CHATROOM_ID/tables/$TABLE_ID/records/$RECORD_ID?expand_links=false" \
  --header "Authorization: Bearer $TOKEN"

這次讀取應回傳第三步建立的資料列；data 會使用「品項」與「數量」等顯示名稱。

在 Playground 開啟（選擇 records.get）。

接下來

先讀欄位型別，了解每種欄位的建立格式、合法值與顯示行為；接著開啟流程精靈，執行預設的「建立系統（Build a system）」流程，把單張表延伸成含標籤、grant 與 insight 開關的完整系統。