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`, `post`, `putpatchdelete`

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`, `read`, `updatedeleteexecute`

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`	Объект join, используемый для связей "многие ко многим"
`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	Type	Required	Default
`entities.{entity-name}`	`source`	object	✔️ Да	None

Сведения об источнике базы данных сущности.

Вложенные свойства

Parent	Property	Type	Required	Default
`entities.{entity-name}.source`	`object`	string	✔️ Да	None
`entities.{entity-name}.source`	`type`	перечисление (`table`, , `viewstored-procedure`)	✔️ Да	None
`entities.{entity-name}.source`	`key-fields`	массив строк	✔️ Да*	None
`entities.{entity-name}.source`	`parameters`	object	✔️ Да**	None

key-fields требуется только в том случае, если type это view. Значение представляет первичные ключи.

** parameters требуется только в том случае, если 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	Type	Required	Default
`entities.permissions`	`role`	string	✔️ Да	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())

Действия (сущности entity-name в строковом массиве разрешений)

Parent	Property	Type	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
        }
      ]
    }
  }
}

Действия (сущности entity-name для разрешения массива объектов)

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions`	`actions`	массив строк	✔️ Да	None

Массив объектов, содержащий сведения о том, какие операции разрешены для связанной роли.

Note

Для хранимых процедур действие подстановочного знака (*) расширяется только до execute. Для таблиц и представлений он расширяется до create, read, updateи delete.

Вложенные свойства

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions.actions[]`	`action`	string	✔️ Да	None
`entities.{entity-name}.permissions.actions[]`	`fields`	object	❌ Нет	None
`entities.{entity-name}.permissions.actions[]`	`policy`	object	❌ Нет	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	string	✔️ Да	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	Type	Required	Default
`entities.{entity-name}.graphql`	`type`	object	❌ Нет	{entity-name}

Задает соглашение об именовании сущности в схеме GraphQL.

Format

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

Вложенные свойства

Parent	Property	Required	Type	Default
`entities.{entity-name}.graphql.type`	`singular`	❌ Нет	string	None
`entities.{entity-name}.graphql.type`	`plural`	❌ Нет	string	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	Type	Required	Default
`entities.{entity-name}.graphql`	`operation`	строка перечисления	❌ Нет	mutation

Указывает, отображается ли stored-procedure операция под Query или Mutation.

Note

Если {entity-name}.type задано значение stored-procedure, создается автоматически новый тип executeXXX GraphQL. Это 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	Type	Required	Default
`entities.{entity-name}.graphql`	`enabled`	boolean	❌ Нет	True

Позволяет разработчикам выборочно включать сущности в схему GraphQL.

Format

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

REST (сущности с именем сущностей)

Parent	Property	Type	Required	Default
`entities.{entity-name}.rest`	`enabled`	boolean	❌ Нет	True
`entities.rest`	`path`	string	❌ Нет	`/{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	Type	Required	Default
`entities.{entity-name}`	`mappings`	object	❌ Нет	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	Type	Required	Default
`entities.{entity-name}`	`cache`	object	❌ Нет	None

Включает и настраивает кэширование для сущности.

Вложенные свойства

Parent	Property	Type	Required	Default
`entities.{entity-name}.cache`	`enabled`	boolean	❌ Нет	False
`entities.{entity-name}.cache`	`ttl-seconds`	integer	❌ Нет	-

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	Type	Required	Default
`entities.{entity-name}`	`relationships`	object	❌ Нет	None

Настраивает, как сущности GraphQL связаны с другими предоставляемыми сущностями. Дополнительные сведения см. в разделе связи построителя данных.

Note

Свойство relationship-name для каждой связи должно быть уникальным для всех связей для этой сущности.

Вложенные свойства

Эти свойства используются в разных сочетаниях в зависимости от кратности связей.

Parent	Property	Type	Required	Default
`entities.{entity-name}.relationships`	`cardinality`	string	✔️ Да	None
`entities.{entity-name}.relationships`	`target.entity`	string	✔️ Да	None
`entities.{entity-name}.relationships`	`target.fields`	массив строк	❌ Нет	None
`entities.{entity-name}.relationships`	`source.fields`	массив строк	❌ Нет	None
`entities.{entity-name}.relationships`	`linking.object`	string	❌ Нет	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	Type	Required	Default
`entities.{entity-name}`	`health`	object	❌ Нет	None

Включает и настраивает проверки работоспособности сущности.

Вложенные свойства

Parent	Property	Type	Required	Default
`entities.{entity-name}.health`	`enabled`	boolean	❌ Нет	`true`
`entities.{entity-name}.health`	`first`	integer	❌ Нет	`100`
`entities.{entity-name}.health`	`threshold-ms`	integer	❌ Нет	`1000`

Example

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

Note

Значение first должно быть меньше или равно параметру runtime.pagination.max-page-size . Меньшие значения помогают быстрее выполнять проверки работоспособности.

Important

Хранимые процедуры автоматически исключаются из проверок работоспособности сущностей, так как они требуют параметров и не могут быть детерминированными.

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-09-24

Поделиться через

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Обзор формата

Источник (сущности с именем сущности)

Вложенные свойства

Format

Разрешения (сущности с именем сущности)

Format

Example

Примеры использования

Действия (сущности entity-name в строковом массиве разрешений)

Format

Example

Альтернативный формат (только строка, если type=stored-procedure)

Example

Действия (сущности entity-name для разрешения массива объектов)

Вложенные свойства

Format

Example

Заметки о политике

Тип (сущности-имя сущности GraphQL)

Format

Вложенные свойства

Example

Операция (сущности-имена сущностей GraphQL)

Format

Пример: операция

Включено (сущности с именем сущности GraphQL)

Format

REST (сущности с именем сущностей)

Format

Сопоставления (сущности с именем сущности)

Format

Examples

Кэш (сущности с именем сущностей)

Вложенные свойства

Format

Example

Связи (сущности с именем сущности)

Вложенные свойства

Format

Пример: кратность "один к одному"

Пример: кратность "один ко многим"

Пример: кратность "многие ко одному"

Пример: кратность "многие ко многим"

Работоспособности (сущности с именем сущностей)

Вложенные свойства

Example

Обратная связь

Дополнительные ресурсы

Альтернативный формат (только строка, если `type=stored-procedure`)