Skip to Content
API 參考JSONL IaC

JSONL IaC

規劃、套用、檢視狀態、匯出宣告式 JSONL，並取得其 typed authored contract，同時掌握命名空間與破壞性變更。

iac.contract 是三種 scope 各自經驗證的 GET .../tables/iac/contract 路由：

  • /private/module/custom_tables/chatroom/{chatroom_id}/tables/iac/contract
  • /private/module/custom_tables/department/{department_id}/tables/iac/contract
  • /private/module/custom_tables/company/tables/iac/contract

它回傳 IacDocumentContractResponse，欄位為 version、kinds、resource_types 與 line。Runtime line 是一條合法的 header 範例；OpenAPI response schema 則帶出完整的 discriminated IacLine union，補上原始 JSONL plan/apply request body 無法呈現的型別契約。

GET
路由範本/private/module/custom_tables/{scope}/tables/iac/contract

取得 JSONL IaC line contract

用途

回傳 authored kind、managed resource 清單與 typed IacLine carrier，讓 OpenAPI 暴露完整 discriminated union。

適用時機

建立 raw JSONL plan／apply body 的 editor、validator 或 client 時使用。

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

範圍

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

回應結構

IacDocumentContractResponse
欄位型別必填說明
kinds("header" | "table" | "column" | "rule" | "trigger" | "view" | "grant" | "client_access" | "record" | "command" | "insight_selection" | "public_read")[]是未指定
lineIacHeaderLine | IacTableLine | IacColumnLine | IacRuleLine | IacTriggerLine | IacViewLine | IacGrantLine | IacClientAccessLine | IacRecordLine | IacCommandLine | IacInsightSelectionLine | IacPublicReadLine是Optional first line of a JSONL doc: version + state namespace (spec §3.1).
resource_types("table" | "column" | "rule" | "trigger" | "view" | "grant" | "client_access" | "command" | "insight_selection" | "public_read")[]是未指定
versioninteger否未指定

範例

讀取 IaC union carrier

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  }
}
回應200
{
  "version": 1,
  "kinds": [
    "header",
    "table",
    "column",
    "rule",
    "trigger",
    "view",
    "grant",
    "client_access",
    "record",
    "command",
    "insight_selection",
    "public_read"
  ],
  "resource_types": [
    "table",
    "column",
    "rule",
    "trigger",
    "view",
    "grant",
    "client_access",
    "command",
    "insight_selection",
    "public_read"
  ],
  "line": {
    "kind": "header",
    "version": 1,
    "system": "",
    "description": ""
  }
}

錯誤

狀態發生條件錯誤本文
403呼叫者無法存取指定的聊天室、部門或公司 scope。
{
  "detail": "Insufficient permissions."
}
POST
路由範本/private/module/custom_tables/{scope}/tables/iac/plan

規劃 JSONL IaC 文件

用途

解析並驗證宣告式 JSONL 文件，和現行資源比對差異，再回傳逐行動作與計畫雜湊。

適用時機

每次套用前都先執行，讓人員或自動化流程檢查建立、更新、改名、刪除、漂移與警告。

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

範圍

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

回應結構

IacPlanResponse
欄位型別必填說明
actionsIacPlanAction[]否Per-line planned actions.
errorsIacLineError[]否Doc-level parse/validate errors.
plan_hashstring是sha256 fingerprint pinning apply to this reviewed plan (spec §6).
summaryIacPlanSummary是Counts per action type.

範例

規劃一張資料表與其自然鍵欄位

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "body": "{\"kind\":\"header\",\"version\":1,\"system\":\"catalog-demo\",\"description\":\"Catalog example\"}\n{\"kind\":\"table\",\"ref\":\"orders\",\"spec\":{\"name\":\"IaC orders\",\"description\":\"Orders managed from JSONL\",\"key\":\"order_no\"}}\n{\"kind\":\"column\",\"table\":\"orders\",\"ref\":\"order_no\",\"spec\":{\"name\":\"Order number\",\"type\":\"string\",\"required\":true}}"
}
回應200
{
  "plan_hash": "9a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef",
  "summary": {
    "create": 2,
    "adopt": 0,
    "move": 0,
    "update": 0,
    "noop": 0,
    "delete": 0,
    "orphaned": 0,
    "insert": 0,
    "skip": 0
  },
  "actions": [
    {
      "line": 2,
      "kind": "table",
      "ref": "orders",
      "action": "create",
      "adopted": false,
      "changes": [],
      "drifted_fields": [],
      "warnings": [],
      "errors": []
    },
    {
      "line": 3,
      "kind": "column",
      "ref": "orders.order_no",
      "action": "create",
      "adopted": false,
      "changes": [],
      "drifted_fields": [],
      "warnings": [],
      "errors": []
    }
  ],
  "errors": []
}

錯誤

狀態發生條件錯誤本文
400文件空白或格式錯誤，或超過位元組、行數、資料表或資料列上限。IaC 無條件可用，不存在 feature-disabled 分支。
{
  "detail": "line 2: invalid JSON: Expecting value"
}
400某一實體 JSONL 行的 `[`／`{` 巢狀超過 128 層。量測涵蓋整行（含 line envelope），字串字面值內的括號不計；比較是嚴格大於，因此 128 通過、129 中止。這個上限寫死在程式裡，不是 `CUSTOM_TABLE_IAC_MAX_*` 那組環境變數之一。
{
  "detail": "line 2: excessively nested JSON structure (max depth 128)"
}
POST
路由範本/private/module/custom_tables/{scope}/tables/iac/apply

套用 JSONL IaC 文件

用途

重新計算計畫、核對已審閱的指紋，再依文件順序執行可套用的各行。

適用時機

確認計畫仍是最新版本，且接受其中所有破壞性或漂移修正動作後才使用。

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

範圍

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

參數

欄位位置型別必填說明
plan_hashquerysha256否plan 回傳的 sha256 plan_hash。若不一致會回傳 409 plan_stale；請傳入此值來鎖定審閱過的計畫。
idempotency_keyquerystring否非同步票證流程可用的 24 小時防重複鍵；同步套用時會忽略。
workerqueryenum:legacy|batch|sqs|pubsub否只有資料量觸發非同步套用時，才會使用這個背景執行器。

範例

套用已審閱的資料表建立計畫

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "plan_hash": "9a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef",
    "worker": "legacy"
  },
  "body": "{\"kind\":\"header\",\"version\":1,\"system\":\"catalog-demo\",\"description\":\"Catalog example\"}\n{\"kind\":\"table\",\"ref\":\"orders\",\"spec\":{\"name\":\"IaC orders\",\"description\":\"Orders managed from JSONL\",\"key\":\"order_no\"}}\n{\"kind\":\"column\",\"table\":\"orders\",\"ref\":\"order_no\",\"spec\":{\"name\":\"Order number\",\"type\":\"string\",\"required\":true}}"
}
回應200
{
  "applied": {
    "create": 2,
    "adopt": 0,
    "move": 0,
    "update": 0,
    "noop": 0,
    "delete": 0,
    "orphaned": 0,
    "insert": 0,
    "skip": 0
  },
  "results": [
    {
      "line": 2,
      "kind": "table",
      "ref": "orders",
      "action": "create",
      "adopted": false,
      "changes": [],
      "drifted_fields": [],
      "warnings": [],
      "errors": [],
      "applied": true
    },
    {
      "line": 3,
      "kind": "column",
      "ref": "orders.order_no",
      "action": "create",
      "adopted": false,
      "changes": [],
      "drifted_fields": [],
      "warnings": [],
      "errors": [],
      "applied": true
    }
  ],
  "errors": []
}

錯誤

狀態發生條件錯誤本文
400JSONL 文件空白、格式錯誤或超過 parse-time cap；在比對 plan、dispatch 或 mutation 之前就會失敗。
{
  "detail": "line 2: invalid JSON: Expecting value"
}
404指定的聊天室、部門或公司 scope 不存在，或呼叫者無法存取。
{
  "detail": "Chatroom not found"
}
409審閱後文件或現行資源已有變更，導致重新計算的計畫雜湊不同。
{
  "detail": {
    "code": "plan_stale",
    "message": "The live system changed since this plan was computed; re-plan and retry.",
    "plan_hash": "9a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef"
  }
}
422重新計算的計畫含驗證錯誤，因此不會執行任何動作。
{
  "detail": [
    {
      "line": 3,
      "kind": "column",
      "ref": "orders.order_no",
      "phase": "validate",
      "detail": "duplicate ref 'orders.order_no' (already declared in this document)"
    }
  ]
}
GET
路由範本/private/module/custom_tables/{scope}/tables/iac/state

列出 IaC 管理資源狀態

用途

回傳單一命名空間內受管理的資料表、欄位、規則、觸發器、檢視、授權與用戶端存取清冊，並鎖定目前範圍。

適用時機

適合用來稽核資源歸屬、診斷孤立 ref，或確認先前 apply 納管了哪些資源。

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

範圍

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

參數

欄位位置型別必填說明
systemquerystring <= 100否來自 header.system 的狀態命名空間；省略或傳入空字串可查詢無文件命名空間的狀態。

回應結構

IacStateResponse
欄位型別必填說明
rowsIacStateRowResponse[]否Managed inventory for the queried system.
totalinteger是Number of rows.

範例

列出單一 system 的受管理資源

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "system": "catalog-demo"
  }
}
回應200
{
  "rows": [
    {
      "system": "catalog-demo",
      "resource_type": "table",
      "ref": "orders",
      "resource_id": "22222222-2222-4222-8222-222222222222",
      "table_id": null,
      "updated_at": "2026-07-19T02:20:00Z"
    },
    {
      "system": "catalog-demo",
      "resource_type": "column",
      "ref": "orders.order_no",
      "resource_id": "col_33333333_3333_4333_8333_333333333333",
      "table_id": "22222222-2222-4222-8222-222222222222",
      "updated_at": "2026-07-19T02:20:00Z"
    }
  ],
  "total": 2
}
GET
路由範本/private/module/custom_tables/{scope}/tables/iac/export

將自訂資料表匯出成可匯入的 JSONL

用途

從受管理的 system、明確指定的資料表集合或整個範圍，產生內容固定且已遮蔽秘密資訊的 IaC 文件。

適用時機

適合用於備份、審閱、移轉，或作為可再次匯入的宣告式文件起點。

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

範圍

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

參數

欄位位置型別必填說明
systemquerystring <= 100否要匯出的受管理 system 或標籤名稱；系統會合併狀態清冊與同名標籤中的資料表。
table_idsquerylist[uuid]否明確指定要匯出的資料表 UUID；多張資料表請重複使用 table_ids query key。
include_recordsqueryboolean否設為 true 時，替每張資料表加入最多 CUSTOM_TABLE_IAC_MAX_RECORDS 筆種子 record 行。

範例

匯出單一 system，但不包含資料列

請求
{
  "pathParams": {
    "chatroom_id": "11111111-1111-4111-8111-111111111111"
  },
  "query": {
    "system": "catalog-demo",
    "include_records": "false"
  }
}
回應200
"{\"kind\":\"header\",\"version\":1,\"system\":\"catalog-demo\",\"description\":\"\"}\n{\"kind\":\"table\",\"ref\":\"orders\",\"spec\":{\"name\":\"IaC orders\",\"description\":\"Orders managed from JSONL\",\"key\":\"order_no\"}}\n{\"kind\":\"column\",\"table\":\"orders\",\"ref\":\"order_no\",\"spec\":{\"name\":\"Order number\",\"type\":\"string\",\"required\":true}}\n"

錯誤

狀態發生條件錯誤本文
400指定的資料表無效、參照資料表無法解析，或匯出內容會超過設定上限。IaC 無條件可用，不存在 feature-disabled 分支。
{
  "detail": "table '99999999-9999-4999-8999-999999999999' not found in this scope"
}
Last updated on
公開回呼匯入資料