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）

Source

Property	Description
`entities.entity-name.source.type`	物件類型： `table`、、 `view`或 `stored-procedure`
`entities.entity-name.source.object`	資料庫物件的名稱
`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}": {
      "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>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // primary keys for the view
        "parameters": { // only for stored-procedure
          "<parameter-name>": <default-value>,
          "<parameter-name>": <default-value>
        }
      },
      "mappings": {
        "<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>
          }
        }
      ]
    }
  }
}

來源（實體名稱實體）

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

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

巢狀屬性

Parent	Property	類型	Required	Default
`entities.{entity-name}.source`	`object`	字串	✔️ 是的	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只有在是 type時才view需要。值表示主鍵。

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

Tip

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

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for option stored-procedure parameters
          "<parameter-name-1>": <default-value>
          "<parameter-name-2>": <default-value>
        }
      }
    }
  }
}

權限（實體名稱實體）

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

字串，指定許可權套用至的角色名稱。

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

此範例會定義只有custom-role實體許可權read的角色User。

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

使用範例

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");
// To read the response content:
// var content = await response.Content.ReadAsStringAsync();

const response = await fetch('https://localhost:5001/api/User', {
  headers: {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});
// To read the response body as JSON:
// const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
# To print the response JSON:
print(response.json())

動作（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 運算子，例如 eq。
原則支援使用 and 和 or的複合述詞。
只支援動作： create、 read、 update和 delete。（不是 execute）
原則會篩選結果，但不會防止資料庫中的查詢執行。
如果對應，欄位必須使用欄位別名。

類型（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 （預設值為單一值）

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 端點。

Format

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

對應（實體名稱實體）

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`	整數	❌ 否	-

Format

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

Note

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

Example

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

關聯性（實體名稱實體）

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

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-05

共用方式為

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

格式概觀

來源（實體名稱實體）

巢狀屬性

Format

權限（實體名稱實體）

Format

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

Examples

快取 （實體名稱實體）

巢狀屬性

Format

Example

關聯性 （實體名稱實體）

巢狀屬性

Format

範例：一對一基數

範例：一對多基數

範例：多對一基數

範例：多對多基數

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

巢狀屬性

Example

意見反應

其他資源

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

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

類型（GraphQL 實體名稱實體）

作業（GraphQL 實體名稱實體）

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

對應（實體名稱實體）

快取（實體名稱實體）

關聯性（實體名稱實體）

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