Справочник по функциям конкретной базы данных для построителя API данных

В этой справке рассматриваются функции, поведение и требования, относящиеся к одной или нескольким платформам баз данных, поддерживаемым построителем API данных (DAB). Матрица сравнения функций между базами данных см. в разделе "Доступность компонентов".

Поддержка версий базы данных

DAB поддерживает следующие платформы баз данных. Минимальные требования к версии применяются к автономным развертываниям. Базы данных PaaS для платформы как службы не имеют минимального требования к версии, так как служба управляет версией.

SQL Server и Azure SQL

SESSION_CONTEXT

Для SQL Server и SQL Azure DAB может распространять утверждения пользователей, прошедшие проверку подлинности, в базу данных путем вызова sp_set_session_context перед выполнением каждого запроса. Этот механизм позволяет политикам безопасности уровня строк SQL и хранимым процедурам считывать удостоверение вызывающего объекта из ядра СУБД.

Если set-session-context этот параметр включен в конфигурации DAB, DAB отправляет все утверждения, прошедшие проверку подлинности, как пары "ключ-значение":

EXEC sp_set_session_context 'roles', 'editor', @read_only = 0;
EXEC sp_set_session_context 'oid', 'a1b2c3d4-...', @read_only = 0;
-- Your query executes after claims are set
SELECT * FROM dbo.Documents;

Распространенные отправленные утверждения включают roles, suboidи любые пользовательские утверждения, которые поставщик удостоверений включает в JWT.

Включение SESSION_CONTEXT

Задать --set-session-context true при вызове dab init:

dab init \
  --database-type mssql \
  --connection-string "@env('SQL_CONNECTION_STRING')" \
  --set-session-context true

Или задайте свойство непосредственно в dab-config.json:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  }
}

Использование SESSION_CONTEXT в SQL

После включения set-session-contextобъекты SQL могут считывать значения утверждений:

-- Read a claim in a stored procedure
DECLARE @role NVARCHAR(256) = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

-- Use a claim in a row-level security predicate function
CREATE FUNCTION dbo.RlsPredicate(@claimRole NVARCHAR(256))
RETURNS TABLE
WITH SCHEMABINDING
AS RETURN SELECT 1 AS result
WHERE @claimRole = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

Полное пошаговое руководство см. в разделе "Реализация безопасности на уровне строк с помощью контекста сеанса".

SESSION_CONTEXT и пул подключений

DAB сбрасывает все значения контекста сеанса в начале каждого запроса. Тем не менее, так как set-session-context принудительно применяется семантика подключения для каждого пользователя, повторное использование подключения между пользователями будет избегаться автоматически при включении этого параметра.

Варианты строки подключения

DAB используется Microsoft.Data.SqlClient для SQL Server и SQL Azure. Библиотека поддерживает эти форматы строк подключения.

Распространенные форматы:

Неподдерживаемые типы данных

Следующие типы данных SQL Server и SQL Azure не поддерживаются DAB:

Azure Cosmos DB для NoSQL

Требование схемы

В отличие от реляционных баз данных, Azure Cosmos DB для NoSQL не зависит от схемы. DAB не может интроспектировать контейнер Cosmos DB для создания типов GraphQL. Необходимо указать файл схемы GraphQL ,.gqlкоторый определяет структуру документа.

Файл схемы использует стандартный язык определения схемы GraphQL (SDL) с двумя настраиваемыми директивами:

@model директива

Директива @model(name: "...") требуется для каждого типа GraphQL, который вы предоставляете с помощью DAB. Значение name должно точно соответствовать имени сущности в файле конфигурации DAB.

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
}

@authorize директива

Директива @authorize предоставляет управление доступом на уровне поля и уровня типа для запросов GraphQL Cosmos DB. Он принимает roles параметр с описанием ролей, которые могут получить доступ к полю или типу.

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "librarian"])
  internalNotes: String @authorize(roles: ["editor"])
}

Вы также можете применить на @authorize уровне типа:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["auditor"]) {
  id: ID
  summary: String
}

Полное руководство по настройке см. в руководстве по настройке построителя API данных для Azure Cosmos DB для NoSQL.

Недоступность REST API

DAB не создает конечные точки REST для Azure Cosmos DB для NoSQL. Azure Cosmos DB предоставляет полный собственный REST API для операций с документами. Создаются только конечные точки GraphQL. Документы OpenAPI не создаются для сущностей Cosmos DB.

Чтобы получить доступ к данным через REST, используйте REST API Azure Cosmos DB напрямую.

Неподдерживаемые функции для Cosmos DB

Следующие функции не поддерживаются для Azure Cosmos DB для NoSQL:

PostgreSQL

Минимальная версия

Требуется PostgreSQL 11 или более поздней версии. DAB используется Npgsql в качестве драйвера PostgreSQL.

Неподдерживаемые типы данных

Следующие типы данных PostgreSQL не поддерживаются DAB:

Хранимые процедуры

Хранимые процедуры не поддерживаются для сущностей PostgreSQL. Вместо этого используйте таблицы и представления.

MySQL

Минимальная версия

Требуется MySQL 8 или более поздней версии.

Неподдерживаемые типы данных

Следующие типы данных MySQL не поддерживаются DAB:

Хранимые процедуры

Хранимые процедуры не поддерживаются для сущностей MySQL. Вместо этого используйте таблицы.

Azure Synapse Analytics (выделенный пул SQL)

Поддерживаемые объекты

Выделенный пул SQL поддерживает таблицы, представления и хранимые процедуры, аналогичные SQL Server и Azure SQL. Бессерверный пул SQL не поддерживается.

Неподдерживаемые функции

Связанный контент

• Доступность компонентов
• Справочник по конфигурации источника данных
• Реализация безопасности на уровне строк с контекстом сеанса
• Настройте конструктор API данных для Azure Cosmos DB для NoSQL
• Политики выпуска и управления версиями