Entities

資料庫實體的組態設定。

Health

Property	Description
`entities.entity-name.health.enabled`	啟用實體（包含 REST 與 GraphQL 端點）的健康檢查
`entities.entity-name.health.first`	健康檢查查詢中回傳的列數（範圍：1-500）
`entities.entity-name.health.threshold-ms`	健康檢查查詢的最大持續時間（毫秒）（最小：1）

Description

Property	Description
`entities.entity-name.description`	人類可讀的實體描述

欄位

Property	Description
`entities.entity-name.fields[].name`	資料庫欄位名稱（必填）
`entities.entity-name.fields[].alias`	API 暴露名稱（取代映射）
`entities.entity-name.fields[].description`	人類可讀的田野描述
`entities.entity-name.fields[].primary-key`	將欄位標記為主鍵（取代鍵欄位）

Source

Property	Description
`entities.entity-name.source.type`	物件類型： `table`、、 `view`或 `stored-procedure`
`entities.entity-name.source.object`	資料庫物件的名稱
`entities.entity-name.source.object-description`	資料庫物件的可讀描述
`entities.entity-name.source.parameters`	預存程式或函式的參數
`entities.entity-name.source.key-fields`	視圖（已棄用）的主要~~鍵欄位列表~~
`entities.entity-name.mappings`	~~將 API 欄位名稱映射到資料庫欄位~~ （已棄用）

REST

Property	Description
`entities.entity-name.rest.enabled`	啟用此實體的 REST
`entities.entity-name.rest.path`	REST 端點的自定義路由
`entities.entity-name.rest.methods`	允許的 REST 方法：`get`、、`postput`、、 `patchdelete`

GraphQL

Property	Description
`entities.entity-name.graphql.type`	使用 `singular` 和輸入名稱或物件 `plural`
`entities.entity-name.graphql.operation`	作業類型： `query` 或 `mutation`
`entities.entity-name.graphql.enabled`	啟用此實體的 GraphQL

Permissions

Property	Description
`entities.entity-name.permissions[].role`	角色名稱字串
`entities.entity-name.permissions[].actions`	一或多個：`create`、、`readupdate`、`delete`、`execute`

Relationships

Property	Description
`entities.entity-name.relationships.relationship-name.cardinality`	`one` 或 `many`
`entities.entity-name.relationships.relationship-name.target.entity`	目標實體的名稱
`entities.entity-name.relationships.relationship-name.source.fields`	關聯性中使用此實體的欄位
`entities.entity-name.relationships.relationship-name.target.fields`	來自目標實體的欄位
`entities.entity-name.relationships.relationship-name.linking.object`	聯結物件，用於多對多關聯性
`entities.entity-name.relationships.relationship-name.linking.source.fields`	來自聯結中所用來源實體的欄位
`entities.entity-name.relationships.relationship-name.linking.target.fields`	來自聯結中所用目標實體的欄位

Cache

Property	Description
`entities.entity-name.cache.enabled`	啟用實體的回應快取
`entities.entity-name.cache.ttl-seconds`	快取存留時間以秒為單位
`entities.entity-name.cache.level`	快取等級： `L1` （僅記憶體內）或 `L1L2` （記憶體內+分散式）

MCP

Property	Description
`entities.entity-name.mcp`	控制實體模型情境協定（MCP）參與的物件
`entities.entity-name.mcp.dml-tools`	啟用或停用實體的資料操作語言（DML）工具
`entities.entity-name.mcp.custom-tool`	將儲存程序註冊為命名的 MCP 工具（僅限儲存程序實體）

格式概觀

{
  "entities": {
    "{entity-name}": {
      "description": <string>,
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      },
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ],
      "mappings": { // DEPRECATED: use fields[].alias
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": <string>,
          "source.fields": [<string>],
          "target.fields": [<string>],
          "linking.object": <string>,
          "linking.source.fields": [<string>],
          "linking.target.fields": [<string>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ],
      "cache": {
        "enabled": <boolean>,
        "ttl-seconds": <integer>,
        "level": "L1" | "L1L2" // default: "L1L2"
      },
      "mcp": {
        "dml-tools": <boolean>,       // default: true
        "custom-tool": <boolean>      // stored-procedure only; default: false
      }
    }
  }
}

來源（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`source`	物件	✔️ 是的	None

實體的資料庫來源詳細數據。

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.source`	`object`	字串	✔️ 是的	None
`entities.{entity-name}.source`	`object-description`	字串	❌ 否	None
`entities.{entity-name}.source`	`type`	enum （`table`，， `viewstored-procedure`）	✔️ 是的	None
`entities.{entity-name}.source`	`key-fields`	字串陣列	❌ 不*	None
`entities.{entity-name}.source`	`parameters`	陣列或物件	❌ 不**	None

* key-fields只有在且typeview陣列未被使用時fields才需要。值表示主鍵。

警告

此 key-fields 屬性在 DAB 2.0 版本中被淘汰。改用 fields 的 primary-key: true 陣列。這個架構強制執行這點 fields ，不能 key-fields 共存於同一實體上。

** parameters僅在 is type 時stored-procedure才需要，且僅適用於具有預設值的參數。參數的資料型態是推斷出來的。沒有預設值的參數可以省略。

object-description 是底層資料庫物件的可選且可讀的描述。此價值在 MCP 工具發現時會浮現，幫助 AI 代理理解實體的目的。

Tip

如果對象屬於 dbo 架構，則指定架構是選擇性的。此外，如有需要，可以使用物件名稱周圍的方括弧（例如 dbo.Users vs. [dbo].[Users]。

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      }
    }
  }
}

參數陣列格式

在 DAB 2.0 預覽版中， parameters 支援結構化陣列格式，並擁有更豐富的元資料。每個參數都是一個具有以下屬性的物件：

Property	類型	Required	Description
`name`	字串	✔️ 是的	參數名稱（不含 `@` 前綴）
`required`	boolean	❌ 否	參數是必需的（`true`）還是可選的（`false`）
`default`	any	❌ 否	當參數未被提供時使用的預設值
`description`	字串	❌ 否	參數的人類可讀描述

範例（陣列格式—偏好）

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "default": null,
            "description": "The unique identifier of the book"
          }
        ]
      }
    }
  }
}

警告

例如的parameters{ "id": 0 }字典格式在 DAB 2.0 中已被棄用。請使用上述陣列格式。舊格式仍被接受以符合向下相容，但未來版本將被移除。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

權限（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.permissions`	`role`	字串	✔️ 是的	None

指定適用權限的角色名稱。請使用你身份提供者中定義的系統角色（Anonymous， Authenticated）或自訂角色。

Tip

關於角色評估、系統角色及標頭的 X-MS-API-ROLE 詳細資訊，請參閱授權概述。

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"Anonymous" | "Authenticated" | "custom-role">,
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

角色繼承

DAB 2.0 引入了實體權限的角色繼承。當角色未為實體明確設定時，該角色會透過以下鏈條繼承更廣泛角色的權限：

named-role → authenticated → anonymous

如果 authenticated 未設定為某個實體，則會繼承自 anonymous。
若未設定命名角色，則繼承自 authenticated，若 anonymous 也缺席則繼承 authenticated 。

這表示你可以一次定義 anonymous 權限，所有更廣泛的角色都能自動獲得相同的存取權限，無需重複。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

Example

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

在此配置下， anonymous，， authenticated及任何未設定的命名角色皆可讀取 Book。用來 dab configure --show-effective-permissions 查看繼承後每個實體已解決的權限。

動作（string-array Permissions 實體名稱實體）

Parent	Property	類型	Required	Default
`entities.permissions`	`actions`	oneOf [string， array]	✔️ 是的	None

字串數位，詳細說明相關聯角色允許的作業。

Action	SQL 作業
`*`	所有動作
`create`	插入一或多個數據列
`read`	選取一或多個數據列
`update`	修改一或多個數據列
`delete`	刪除一或多個數據列
`execute`	執行預存程式

* GraphQL 目前僅支援多個作業。

Note

針對預存程式，通配符（*）動作只會展開至 execute 動作。針對資料表和檢視表，它會展開至 create、read、update和 delete。

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

替代格式（僅限字串，當 `type=stored-procedure`）

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

動作（object-array Permissions 實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}.permissions`	`actions`	字串陣列	✔️ 是的	None

對象陣語，詳細說明相關聯角色允許的作業。

Note

針對預存程式，通配符（*）動作只會擴充為 execute。針對資料表/檢視表，它會展開至 create、read、update和 delete。

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.permissions.actions[]`	`action`	字串	✔️ 是的	None
`entities.{entity-name}.permissions.actions[]`	`fields`	物件	❌ 否	None
`entities.{entity-name}.permissions.actions[]`	`policy`	物件	❌ 否	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	字串	✔️ 是的	None

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }

Example

這會授readauditor與實體的許可權User，並具有字段和原則限制。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

政策說明

資料庫政策會使用 OData 風格的謂詞來過濾查詢結果。用於 @item.<field> 參考實體欄位並 @claims.<type> 注入已認證的使用者聲明。

層面	詳細資訊
語法	OData 謂詞（`eq`， `ne`， `and`， `or`， `gt`，） `lt`
欄位參考	`@item.<field>` （如適用，請使用映射名稱）
權利要求參考	`@claims.<claimType>`
支援的動作	`read`、`update`、`delete`
不支援	`create`、`execute`

Tip

如需完整的資料庫政策指引，包括理賠替換與故障排除，請參閱「配置資料庫政策」。

類型（GraphQL 實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}.graphql`	`type`	物件	❌ 否	{entity-name}

設定 GraphQL 架構內實體的命名慣例。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

巢狀屬性

Parent	Property	Required	類型	Default
`entities.{entity-name}.graphql.type`	`singular`	✔️ 是*	字串	None
`entities.{entity-name}.graphql.type`	`plural`	❌ 否	字串	N/A （預設值為單一值）

* singular 當 type 被指定為物件時，是必須的。當 type 是普通弦時，該弦作為單數名稱。

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

GraphQL 查詢

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

GraphQL 回應

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

作業（GraphQL 實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}.graphql`	`operation`	列舉字串	❌ 否	mutation

指定作業出現在 stored-procedure 或Query底下Mutation。

Note

當設定為 {entity-name}.type時stored-procedure，會自動建立新的 GraphQL 類型executeXXX。這個 operation 屬性會控制此類型放置於 GraphQL 架構的位置。沒有功能影響，只是架構衛生。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

範例：操作

當 operation 設定為 query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

當 operation 設定為 mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

已開啟（GraphQL 實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}.graphql`	`enabled`	boolean	❌ 否	True

可讓開發人員選擇性地在 GraphQL 架構中包含實體。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST （實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}.rest`	`enabled`	boolean	❌ 否	True
`entities.rest`	`path`	字串	❌ 否	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	字串陣列	❌ 不*	`POST`

* 屬性 methods 僅適用於 stored-procedure 端點。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

Format

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "{entity-name}">
      }
    }
  }
}

描述（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`description`	字串	❌ 否	None

一個可選的人類可讀描述。此值會在產生的 API 文件中呈現，並以註解形式出現在 GraphQL 架構中。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

Format

{
  "entities": {
    "{entity-name}": {
      "description": "<string>"
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "description": "Represents a book in the catalog with title, author, and pricing information.",
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

欄位（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`fields`	陣列	❌ 否	None

定義個別資料庫欄位的元資料，包括別名、描述及主要鍵指定。陣fields列會根據屬性和屬性mappings，將兩者aliassource.key-fieldsprimary-key 都替換成一個統一的結構。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.fields[]`	`name`	字串	✔️ 是的	None
`entities.{entity-name}.fields[]`	`alias`	字串	❌ 否	None
`entities.{entity-name}.fields[]`	`description`	字串	❌ 否	None
`entities.{entity-name}.fields[]`	`primary-key`	boolean	❌ 否	`false`

Format

{
  "entities": {
    "{entity-name}": {
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "fields": [
        {
          "name": "id",
          "description": "Unique book identifier",
          "primary-key": true
        },
        {
          "name": "sku_title",
          "alias": "title",
          "description": "The display title of the book"
        },
        {
          "name": "sku_status",
          "alias": "status"
        }
      ]
    }
  }
}

在此範例中， id 被指定為主鍵（取代了對 source.key-fields的需求），而 sku_title 和 sku_status 則被別 title 稱為和 status （取代了對的需求 mappings）。

Important

這個架構強制執行不能 fields 與 mappings 同一實體共存或 source.key-fields 存在於同一實體上。遷移到 fields 並移除已棄用的屬性。

對應（實體名稱實體）

警告

此 mappings 屬性在 DAB 2.0 版本中被淘汰。改用帶有屬性的fieldsalias陣列。這個架構強制執行這點 fields ，不能 mappings 共存於同一實體上。

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`mappings`	物件	❌ 否	None

啟用資料庫物件欄位的自定義別名或公開的名稱。

Important

針對已啟用 GraphQL 的實體，已設定的公開名稱必須符合 GraphQL 名稱需求。

Format

{
  "entities": {
    "{entity-name}": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Examples

資料庫表格

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

{
  "entities": {
    "Books": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

快取（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`cache`	物件	❌ 否	None

啟用及設定實體的快取。

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.cache`	`enabled`	boolean	❌ 否	False
`entities.{entity-name}.cache`	`ttl-seconds`	整數	❌ 否	-
`entities.{entity-name}.cache`	`level`	enum （`L1` \| `L1L2`）	❌ 否	`L1L2`

Format

{
  "entities": {
    "{entity-name}": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>,
        "level": <"L1" | "L1L2"> (default: "L1L2")
      }
    }
  }
}

屬性控制 level 使用哪些快取層級：

價值	Description
`L1`	僅存內快取。最快，但不會跨實例共享。
`L1L2`	記憶體內快取加上分散式（Redis）快取。跨跨規模化的實例共享。 Default.

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

Note

未指定時， ttl-seconds 會繼承底下 runtime.cache設定的全域值。

Example

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30,
        "level": "L1"
      }
    }
  }
}

關聯性（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`relationships`	物件	❌ 否	None

設定 GraphQL 實體與其他公開實體的相關方式。如需詳細資訊，請參閱資料 API 產生器關聯性分解。

Note

relationship-name每個關聯性的屬性在實體的所有關聯性中都必須是唯一的。

巢狀屬性

根據關聯性基數，這些屬性會在不同的組合中使用。

Parent	Property	類型	Required	Default
`entities.{entity-name}.relationships`	`cardinality`	字串	✔️ 是的	None
`entities.{entity-name}.relationships`	`target.entity`	字串	✔️ 是的	None
`entities.{entity-name}.relationships`	`target.fields`	字串陣列	❌ 否	None
`entities.{entity-name}.relationships`	`source.fields`	字串陣列	❌ 否	None
`entities.{entity-name}.relationships`	`linking.object`	字串	❌ 否	None
`entities.{entity-name}.relationships`	`linking.source.fields`	字串陣列	❌ 否	None
`entities.{entity-name}.relationships`	`linking.target.fields`	字串陣列	❌ 否	None

Format

{
  "entities": {
    "{entity-name}": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Relationship	Cardinality	Example
one-to-many	`many`	一個類別實體可以與許多 todo 實體相關聯
many-to-one	`one`	許多 Todo 實體可能與一個類別實體相關
many-to-many	`many`	一個 Todo 實體可以與許多使用者實體相關聯，而一個用戶實體可以與許多 todo 實體相關聯

範例：一對一基數

每個都 Profile 與一個 User完全相關，而且每個都有 User 一個完全相同的相關 Profile。

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

GraphQL 結構描述

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

範例：一對多基數

Category可以有一或多個相關的Book實體，而每個Book實體可以有一個相關的 Category。

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

GraphQL 結構描述

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

命令列

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

範例：多對一基數

許多 Book 實體可以有一個相關的 Category，而 Category 可以有一或多個相關的 Book 專案。

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

GraphQL 結構描述

type Book
{
  id: Int!
  ...
  category: Category
}

命令列

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

範例：多對多基數

許多 Book 實體可以有許多相關 Author 實體，而許多 Author 實體可以有許多相關 Book 專案。

Note

這種關係可以透過第三個資料表實現 dbo.books_authors，我們將其稱為 連結物件。

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

GraphQL 結構描述

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

命令列

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

健康情況（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`health`	物件	❌ 否	None

啟用及設定實體的健康情況檢查。

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.health`	`enabled`	boolean	❌ 否	`true`
`entities.{entity-name}.health`	`first`	整數	❌ 否	`100`
`entities.{entity-name}.health`	`threshold-ms`	整數	❌ 否	`1000`

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Note

該 first 值必須小於或等於設定值 runtime.pagination.max-page-size 。較小的數值有助於健康檢查更快完成。

Important

儲存程序會自動排除在實體健康檢查之外，因為它們需要參數，且可能不是確定性的。

MCP（實體名稱實體）

Parent	Property	類型	Required	Default
`entities.{entity-name}`	`mcp`	物件	❌ 否	省略時預設啟用

控制實體的MCP參與。當 MCP 全域啟用時，實體會自動參與。使用此特性來選擇退出或啟用儲存程序實體的自訂 MCP 工具。

Note

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。欲了解更多資訊，請參閱 2.0 版本的新內容。

物件格式

使用物件格式進行細緻控制：

Parent	Property	類型	Required	Default
`entities.{entity-name}.mcp`	`dml-tools`	boolean	❌ 否	`true`
`entities.{entity-name}.mcp`	`custom-tool`	boolean	❌ 否	`false`

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

自訂工具（僅限儲存程序）

對於儲存的程序實體，設定 custom-tool 為以 true 註冊程序為命名的 MCP 工具：

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Important

此 custom-tool 屬性僅適用於儲存程序實體。將它放在資料表或檢視實體上會導致設定錯誤。

CLI 範例

dab add Book --source books --permissions "anonymous:*" --mcp.dml-tools true

dab add GetBookById --source dbo.get_book_by_id --source.type stored-procedure --permissions "anonymous:execute" --mcp.custom-tool true

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-01

共用方式為

Entities

Health

Description

欄位​​

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

格式概觀

來源（實體名稱實體）

巢狀屬性

Format

參數陣列格式

範例（陣列格式—偏好）

權限（實體名稱實體）

Format

Example

角色繼承

Example

動作（string-array Permissions 實體名稱實體）

Format

Example

替代格式（僅限字串，當 type=stored-procedure）

Example

動作 （object-array Permissions 實體名稱實體）

巢狀屬性

Format

Example

政策說明

類型 （GraphQL 實體名稱實體）

Format

巢狀屬性

Example

作業 （GraphQL 實體名稱實體）

Format

範例：操作

已開啟 （GraphQL 實體名稱實體）

Format

REST （實體名稱實體）

Format

描述（實體名稱實體）

Format

Example

欄位（實體名稱實體）

巢狀屬性

Format

Example

對應 （實體名稱實體）

Format

Examples

快取 （實體名稱實體）

巢狀屬性

Format

Example

關聯性 （實體名稱實體）

巢狀屬性

Format

範例：一對一基數

範例：一對多基數

範例：多對一基數

範例：多對多基數

健康情況 （實體名稱實體）

巢狀屬性

Example

MCP（實體名稱實體）

物件格式

自訂工具（僅限儲存程序）

CLI 範例

意見反應

其他資源

欄位

替代格式（僅限字串，當 `type=stored-procedure`）

動作（object-array Permissions 實體名稱實體）

類型（GraphQL 實體名稱實體）

作業（GraphQL 實體名稱實體）

已開啟（GraphQL 實體名稱實體）

對應（實體名稱實體）

快取（實體名稱實體）

關聯性（實體名稱實體）

健康情況（實體名稱實體）