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

Новые возможности построителя api данных версии 2.0 (март 2026 г.)

Замечание

Версия 2.0 доступна в общедоступной предварительной версии. Некоторые функции пока не рекомендуется использовать в рабочей среде. Дополнительные сведения о доступности и стабильности функций см. в документации.

Построитель API данных 2.0 посвящен интеграции протокола контекста модели (MCP) и ИИ, упрощению проверки подлинности по умолчанию и более эффективной автоматизации конфигурации. Этот выпуск также обеспечивает более высокую наблюдаемость и более гибкое поведение REST и OpenAPI.

Введение: автоматическая настройка

Автоматическая настройка — это мощная функция, которая позволяет определять шаблоны, которые автоматически находят и предоставляют объекты базы данных в конфигурации. Такой подход может значительно сократить файл конфигурации, особенно если объекты и разрешения прогнозируются. Кроме того, повторно оцените и примените шаблоны при каждом запуске DAB, поэтому новые таблицы, соответствующие шаблону, autoentities автоматически добавляются в виде сущностей без изменений конфигурации вручную.

Замечание

В версии 2.0 dab auto-config поддерживает только таблицы в одной или нескольких базах данных Microsoft SQL. Если вам нужен другой источник данных или тип базы данных, можно определить сущности вручную.

Почему?

С помощью auto-configможно подключить всю схему базы данных в виде API DAB, не записывая один блок сущности вручную. Определите шаблоны один раз и DAB выполняет остальные действия.

Стоит отметить, что autoentities не является переходом DAB на API, основанный на схеме. Проблема с API, управляемыми схемой, заключается в том, что они раскрывают структуру схемы и накладывают нагрузку на базу данных, чтобы она принужденно соответствовала API вместо того, чтобы быть хорошо спроектированным хранилищем. Autoentities Решить эту проблему можно путем определения шаблонов, которые соответствуют схеме базы данных и автоматически создают подмножество сущностей из этих шаблонов. Кроме того, вы можете определить несколько autoentities уникальных шаблонов и разрешений, участвовать в MCP и многое другое без обновлений конфигурации вручную по мере развития базы данных.

Командная строка

dab auto-config my-def \
	--patterns.include "dbo.%" \
	--patterns.exclude "dbo.internal%" \
	--patterns.name "{schema}_{table}" \
	--permissions "anonymous:read"

dab auto-config my-def \
	--template.rest.enabled true \
	--template.graphql.enabled true \
	--template.cache.enabled true \
	--template.cache.ttl-seconds 30 \
	--template.cache.level L1L2

Итоговая конфигурация

{
	"autoentities": {
		"my-def": {
			"patterns": {
				"include": [ "dbo.%" ],
				"exclude": [ "dbo.internal%" ],
				"name": "{schema}_{table}"
			},
			"template": {
				"rest": { "enabled": true },
				"graphql": { "enabled": true },
				"cache": {
					"enabled": true,
					"ttl-seconds": 30,
					"level": "l1l2"
				}
			},
			"permissions": [
				{
					"role": "anonymous",
					"actions": [ "read" ]
				}
			]
		}
	}
}

Тестирование конфигурации

dab auto-config-simulate предварительно определяет, какие объекты базы данных соответствуют autoentities шаблонам перед фиксацией каких-либо изменений. Он подключается к базе данных, резолирует каждый шаблон и печатает соответствующие объекты. Теперь вы можете проверить, что шаблоны включения и исключения действительно создают ожидаемые вами сущности, прежде чем изменять их в рабочей конфигурации.

dab auto-config-simulate
Результирующий результат
AutoEntities Simulation Results

Filter: my-def
Matches: 3
	dbo_Products  →  dbo.Products
	dbo_Inventory →  dbo.Inventory
	dbo_Pricing   →  dbo.Pricing

Чтение документации

Введение: делегирование от имени пользователя (OBO)

DAB 2.0 добавляет аутентификацию от имени (OBO), иногда называемую сквозной аутентификацией, для баз данных Microsoft SQL с помощью Microsoft Entra ID. Если этот параметр включен, DAB обменивает входящий маркер пользователя на маркер SQL для передачи ниже по потоку, чтобы база данных выполняла аутентификацию, как если бы это был сам вызывающий пользователь.

Почему?

С помощью проверки подлинности OBO можно создавать API, где база данных SQL видит и применяет реальное удостоверение пользователя, которое может быть полезно для некоторых сценариев безопасности на уровне строк и аудита соответствия требованиям. Это поведение особенно ценно в сценариях MCP, когда становится неясно, кто именно действует; OBO обеспечивает прозрачную идентификацию пользователей.

Предварительные требования для работы с OBO

  1. Регистрация приложения Entra ID с соответствующими разрешениями API для запроса токенов для базы данных
  2. Вышестоящий поставщик удостоверений, который выдает JWT, принимаемые DAB (Entra ID или настраиваемый поставщик, который вы конфигурируете)
  3. База данных MSSQL, настроенная для приема токенов Microsoft Entra ID

Требования к конфигурации

  • Требует data-source.database-type: "mssql"
  • Требует data-source.user-delegated-auth.database-audience
  • требуется отключить runtime.cache, когда настроена OBO.
  • требует env var DAB_OBO_CLIENT_ID с идентификатором клиента регистрации приложения OBO
  • требует env var DAB_OBO_TENANT_ID с идентификатором клиента регистрации приложения OBO
  • требует переменную среды DAB_OBO_CLIENT_SECRET с паролем клиента для регистрации приложения OBO

Командная строка

set DAB_OBO_CLIENT_ID=1234-abcd-5678-efgh
set DAB_OBO_TENANT_ID=abcd-1234-efgh-567
set DAB_OBO_CLIENT_SECRET=supersecretvalue

dab configure --data-source.database-type mssql
dab configure --runtime.cache.enabled false

dab configure --data-source.user-delegated-auth.enabled true
dab configure --data-source.user-delegated-auth.provider EntraId
dab configure --data-source.user-delegated-auth.database-audience "https://database.windows.net"

Итоговая конфигурация

{
	"data-source": {
		"database-type": "mssql",
		"connection-string": "@env('SQL_CONNECTION_STRING')",
		"user-delegated-auth": {
			"enabled": true,
			"provider": "EntraId",
			"database-audience": "https://database.windows.net"
		}
	},
	"runtime": {
		"cache": {
			"enabled": false
		}
	}
}

Замечание

Если OBO включен, DAB поддерживает отдельные пулы подключений SQL на пользователя, чтобы маркер доступа одного пользователя никогда не был повторно использован для запроса другого пользователя. Теперь, когда безопасность на уровне строк зависит от того, кто подключен, вы можете быть уверены, что повторное использование подключения между несколькими пользователями не предоставляет доступ, которого быть не должно.

Чтение документации

Представляем: Пользовательские инструменты MCP

Если custom-tool: true задано в сущности хранимой процедуры, DAB динамически регистрирует процедуру как именованное средство MCP, предоставляемое через стандартные tools/list и tools/call методы.

Почему?

Теперь вы можете предоставить целевые инструменты для агентов ИИ, которые поддерживаются вашими существующими хранимыми процедурами, без написания объединяющего кода. Средство отображается в списке инструментов MCP и принимает те же параметры, что и процедура.

Командная строка

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

Итоговая конфигурация

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

Чтение документации

Введение: новый Unauthenticated поставщик

DAB 2.0 представляет Unauthenticated в качестве нового поставщика проверки подлинности и устанавливает его по умолчанию для новых конфигураций. Если этот поставщик активен, все запросы выполняются как anonymous. DAB не инспектирует и не проверяет веб-токены JSON (JWT). Даже если другая служба перед DAB проходит проверку подлинности вызывающего объекта, DAB по-прежнему оценивает разрешения только как anonymous.

Почему?

Теперь, когда вы хотите, чтобы DAB оставался только anonymous, вам не нужно настраивать поставщика JWT для начала работы. Выполнение dab init создает рабочую конфигурацию без дополнительных параметров проверки подлинности.

Командная строка

dab init --database-type mssql --connection-string "Server=localhost;Database=mydb;"

Итоговая конфигурация

{
	"runtime": {
		"host": {
			"authentication": {
				"provider": "Unauthenticated"
			}
		}
	}
}

Это важно

Если Unauthenticated активен, authenticated и пользовательские роли, определенные в разрешениях сущностей, никогда не активируются. Если конфигурация содержит эти роли, DAB выдает предупреждение при запуске.

Чтение документации

Введение: наследование ролей

DAB 2.0 добавляет наследование ролей, поэтому вам не нужно повторять один блок разрешений для каждой роли. Цепочка наследования:

	named-role → authenticated → anonymous

Если authenticated не настроен явно для сущности, она наследует его от anonymous. Если именованная роль не настроена, она наследуется от authenticated, или от anonymous, если authenticated также отсутствует.

Почему?

При наследовании ролей можно определить разрешения один раз на anonymous, и каждая более широкая роль автоматически получает одинаковый доступ, без дублирования.

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

С помощью этой конфигурации anonymous, authenticated и любая ненастроенная именованная роль могут все читать Book.

Отображение эффективных разрешений с помощью интерфейса командной строки

В результате наследования ролей новый --show-effective-permissions параметр dab configure отображает разрешенные разрешения для каждой сущности. Если вы не уверены, что роль может выполнить после того, как правила наследования вступят в силу, выполните эту команду, чтобы получить ответ, вместо того чтобы разбираться в конфигурации вручную.

Командная строка

dab configure --show-effective-permissions
dab configure --show-effective-permissions --config my-config.json

Результирующий результат

Entity: Book
	Role: anonymous        | Actions: Read
	Role: authenticated    | Actions: Read (inherited from: anonymous)
	Unconfigured roles inherit from: anonymous

Entity: Order
	Role: admin            | Actions: Create, Read, Update, Delete
	Role: anonymous        | Actions: Read
	Role: authenticated    | Actions: Read (inherited from: anonymous)
	Unconfigured roles inherit from: authenticated

Чтение документации

Введение: расширенные пути REST

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

Почему?

Теперь вы можете группировать связанные сущности в префиксе общего пути, что делает REST API более естественным образом упорядоченным без какой-либо конфигурации маршрутизатора. Этот подход может оказаться полезным для мультитенантных сценариев, в которых сегмент идентификатора клиента может сегментировать конечные точки с тем же именем, например /api/shopping-cart/item и /api/invoice/items, что ранее требовало уникальных имен сущностей.

Командная строка

dab add ShoppingCartItem \
  --source dbo.ShoppingCartItem \
  --rest.path "shopping-cart/item"

dab add InvoiceItem \
  --source dbo.InvoiceItem \
  --rest.path "invoice/item"

Итоговая конфигурация

{
	"entities": {
		"ShoppingCartItem": {
			"source": "dbo.ShoppingCartItem",
			"rest": { "path": "shopping-cart/item" }
		},
		"InvoiceItem": {
			"source": "dbo.InvoiceItem",
			"rest": { "path": "invoice/item" }
		}
	}
}

Результирующий путь

https://{server-name}/api/shopping-cart/item
https://{server-name}/api/invoice/item

Чтение документации

Введение: openAPI с поддержкой разрешений

В документе OpenAPI теперь отображаются только методы и поля HTTP, доступные на основе разрешений. Новый путь /openapi/{role} для конкретной роли позволяет точно увидеть, что может сделать данная роль.

Почему?

С учетом разрешений в OpenAPI ваш документ становится надежным контрактом. Клиенты и потребители API видят только то, что разрешено вызывать, а не полную внутреннюю поверхность.

Доступные пути

/openapi
/openapi/anonymous
/openapi/authenticated
/openapi/{custom-role}

Это важно

/openapi/{role} доступен только в режиме разработки , чтобы предотвратить перечисление ролей в рабочей среде.

Чтение документации

Параметры OpenTelemetry по умолчанию в dab init

Новые конфигурации, сгенерированные с помощью dab init, теперь включают раздел OpenTelemetry по умолчанию, предварительно настроенный для использования стандартных переменных среды OpenTelemetry (OTEL).

Почему?

Теперь, когда вы развертываете DAB в контейнере или приложении Aspire, инфраструктура для наблюдаемости уже готова. Вы просто задаете переменные среды— изменения конфигурации вручную не требуются.

{
	"telemetry": {
		"open-telemetry": {
			"enabled": true,
			"endpoint": "@env('OTEL_EXPORTER_OTLP_ENDPOINT')",
			"headers": "@env('OTEL_EXPORTER_OTLP_HEADERS')",
			"service-name": "@env('OTEL_SERVICE_NAME')"
		}
	}
}

Если переменные среды не заданы, DAB запускается нормально и пропускает настройку экспортера OpenTelemetry Protocol (OTLP). Неустраненные @env(...) значения допускаются при запуске.

Чтение документации

Введение: сжатие ответов HTTP

DAB 2.0 добавляет сжатие HTTP-ответа для ответов REST и GraphQL. Теперь вы можете уменьшить размер полезных данных по проводу с помощью одного параметра конфигурации, что особенно полезно для больших результирующих наборов или сред с низкой пропускной способностью.

Поддерживаемые уровни: optimal, fastest, none.

Командная строка

dab configure --runtime.compression.level "optimal"

Итоговая конфигурация

{
	"runtime": {
		"compression": {
			"level": "optimal"
		}
	}
}

Чтение документации

Без PUT ключей и PATCH для автоматически созданных ключей

DAB 2.0 разрешает PUT и PATCH запросы без ключа в URL, когда база данных автоматически создает все опущенные ключевые столбцы. При бесключевых upsert можно вставить новую строку с ключом, созданным сервером, используя ту же семантику upsert, к которой вы привыкли, — не нужно предварительно создавать или предоставлять ключ самостоятельно.

Чтение документации

Трассировка OpenTelemetry для выполнения MCP

Выполнение инструмента MCP теперь включено в трассировки OpenTelemetry и происходит вместе с трафиком REST и GraphQL. Теперь вы можете отслеживать и сопоставлять средства агента ИИ так же, как отслеживать запросы API, используя те же панели мониторинга, те же идентификаторы трассировки и те же средства. Это работает автоматически при настройке OpenTelemetry. Поскольку dab init теперь создает раздел телеметрии по умолчанию, новые приложения обладают готовой к использованию наблюдаемостью для всех трех типов конечных точек.

Чтение документации

  • Last updated on