Entities

数据库实体的配置设置。

Health

Description

Fields

Source

REST

GraphQL

Permissions

Relationships

Cache

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
      }
    }
  }
}

源（实体名称实体）

实体的数据库源详细信息。

嵌套属性

* key-fields仅在使用数组且type未使用数组时才viewfields是必需的。 该值表示主键。

** parameters仅当为type具有默认值的参数时才stored-procedure需要 。 推断参数的数据类型。 可以省略不带默认值的参数。

object-description 是基础数据库对象的可选可读说明。 此值在 MCP 工具发现过程中浮出水面，帮助 AI 代理了解实体的目的。

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 支持具有更丰富的元数据的结构化数组格式。 每个参数都是具有以下属性的对象：

示例（数组格式 - 首选）

{
  "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"
          }
        ]
      }
    }
  }
}

权限（实体名称实体）

指定权限应用于的角色名称。 使用标识提供者中定义的系统角色（Anonymous、 Authenticated）或自定义角色。

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或不存在anonymousauthenticated。

这意味着你可以定义权限 anonymous 一次，并且每个更广泛的角色会自动获得相同的访问权限，无需重复。

Example

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

使用此配置，anonymousauthenticated以及任何未配置的命名角色都可以读取Book。 用于 dab configure --show-effective-permissions 在应用继承后查看每个实体的解析权限。

作（字符串数组权限实体名称实体）

一个字符串数组，详细说明关联角色允许的作。

* GraphQL 目前仅支持多个作。

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
        }
      ]
    }
  }
}

作（对象数组权限实体名称实体）

一个对象数组，详细说明了关联角色允许的作。

嵌套属性

Format

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

Example

这会授予read对auditorUser实体的权限，并具有字段和策略限制。

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

策略说明

数据库策略使用 OData 样式谓词筛选查询结果。 用于 @item.<field> 引用实体字段并 @claims.<type> 注入经过身份验证的用户声明。

类型（GraphQL 实体名称实体）

设置 GraphQL 架构中实体的命名约定。

Format

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

嵌套属性

* 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 实体名称实体）

指定作是否stored-procedure显示在作的下方Query。Mutation

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 实体名称实体）

允许开发人员选择性地将实体包含在 GraphQL 架构中。

Format

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

REST （实体名称实体）

* 该 methods 属性仅适用于 stored-procedure 终结点。

Format

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

说明（实体名称实体）

实体的可选可读说明。 此值显示在生成的 API 文档中，并在 GraphQL 架构中作为注释显示。

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"
      }
    }
  }
}

字段（实体名称实体）

定义各个数据库字段的元数据，包括别名、说明和主键指定。 数组 fields 在单个统一结构中替换 mappings （通过 alias 属性）和 source.key-fields （通过 primary-key 属性）。

嵌套属性

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_titlesku_status别名为title和status（替换需要）。mappings

映射（实体名称实体）

为数据库对象字段启用自定义别名或公开的名称。

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"
      }
    }
  }
}

缓存（实体名称实体）

启用和配置实体的缓存。

嵌套属性

Format

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

该 level 属性控制使用哪些缓存层：

Example

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

关系（实体名称实体）

配置 GraphQL 实体与其他公开实体的关系。 有关详细信息，请参阅 数据 API 生成器关系细分。

嵌套属性

这些属性在不同的组合中使用，具体取决于关系基数。

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>"]
        }
      }
    }
  }
}

示例：一对一基数

每个 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"

示例：一对多基数

A 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 条目。

{
  "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"

运行状况（实体名称实体）

启用和配置实体的运行状况检查。

嵌套属性

Example

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

MCP （实体名称实体）

控制实体的 MCP 参与。 全局启用 MCP 时，实体默认参与。 使用此属性可以选择退出或为存储过程实体启用自定义 MCP 工具。

对象格式

使用对象格式进行精细控制：

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

自定义工具（仅存储过程）

对于存储过程实体，设置为custom-tooltrue将过程注册为命名 MCP 工具：

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

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