Entities

数据库实体的配置设置。

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Format overview

{
  "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>": <string | number | boolean>,
          "<parameter-name>": <string | number | boolean>
        }
      },
      "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>
          }
        }
      ]
    }
  }
}

源（实体名称实体）

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

Nested properties

• key-fields 仅当 type 为 view. 该值表示主键。

** parameters 仅当 type 为 stored-procedure. 可以省略可选参数。

支持的参数数据类型：

1. string— 包括 ANSI 和 Unicode;也用于 JSON/Date/DateTime 类型
2. number— 包括整型和小数
3. boolean—true 或 false

Format

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

权限（实体名称实体）

一个字符串，指定权限应用到的角色的名称。

Format

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

Example

此示例定义仅read对实体具有权限User的角色custom-role。

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

Usage examples

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())

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

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

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

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

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

Nested properties

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

Policy notes

• 策略支持 OData 运算符，例如 eq。
• 策略支持使用 and 和 or.
• 仅支持作：create、read、update和 delete。 （不 execute）
• 策略筛选结果，但不阻止数据库中的查询执行。
• 字段必须使用字段别名（如果已映射）。

类型（GraphQL 实体名称实体）

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

Format

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

Nested properties

Example

Configuration

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

GraphQL query

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

GraphQL response

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

Example: operation

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

映射（实体名称实体）

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

Format

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

Examples

Database Table

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

Configuration

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

缓存（实体名称实体）

启用和配置实体的缓存。

Nested properties

Format

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

Example

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

关系（实体名称实体）

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

Nested properties

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

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 schema

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 schema

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

Command line

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 schema

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

Command line

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 schema

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

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

Command line

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"

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

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

Nested properties

Format

{
  "entities": {
    "{entity-name}": {
      "health": {
        "enabled": true,
        "first": 5,
        "threshold-ms": 2000
      }
    }
  }
}

Example

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