Referencia de características específicas de la base de datos para Data API Builder

En esta referencia se tratan las características, los comportamientos y los requisitos específicos de una o varias plataformas de base de datos compatibles con Data API Builder (DAB). Para obtener una matriz de comparación de características entre bases de datos, consulte Disponibilidad de características.

Compatibilidad con la versión de la base de datos

DAB admite las siguientes plataformas de base de datos. Los requisitos mínimos de versión se aplican a las implementaciones autoadministrados. Las bases de datos de plataforma como servicio (PaaS) no tienen un requisito de versión mínimo porque el servicio administra la versión.

SQL Server y Azure SQL

SESSION_CONTEXT

Para SQL Server y Azure SQL, DAB puede propagar notificaciones de usuario autenticadas a la base de datos llamando sp_set_session_context a antes de ejecutar cada consulta. Este mecanismo permite que las directivas de seguridad de nivel de fila nativas de SQL y los procedimientos almacenados lean la identidad del autor de la llamada desde el motor de base de datos.

Cuando set-session-context está habilitado en la configuración de DAB, DAB envía todas las notificaciones autenticadas como pares clave-valor:

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;

Las notificaciones comunes enviadas incluyen roles, sub, oidy cualquier notificación personalizada que incluya el proveedor de identidades en el JWT.

Habilitar SESSION_CONTEXT

Establecer --set-session-context true al llamar a dab init:

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

O bien, establezca la propiedad directamente en dab-config.json:

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

Uso de SESSION_CONTEXT en SQL

Después de habilitar set-session-context, los objetos SQL pueden leer los valores de notificación:

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

Para ver un tutorial completo, consulte Implementación de la seguridad de nivel de fila con el contexto de sesión.

SESSION_CONTEXT y agrupación de conexiones

DAB restablece todos los valores de contexto de sesión al principio de cada solicitud. Sin embargo, dado que set-session-context fuerza la semántica de conexión por usuario, la reutilización de conexiones entre los usuarios se evita automáticamente cuando esta opción está habilitada.

Variantes de cadena de conexión

DAB usa Microsoft.Data.SqlClient para SQL Server y Azure SQL. La biblioteca admite estos formatos de cadena de conexión.

Formatos comunes:

Tipos de datos no admitidos

DAB no admite los siguientes tipos de datos de SQL Server y Azure SQL:

Azure Cosmos DB para NoSQL

Requisito de esquema

A diferencia de las bases de datos relacionales, Azure Cosmos DB para NoSQL es independiente del esquema. DAB no puede introspecar un contenedor de Cosmos DB para generar tipos graphQL. Debe proporcionar un archivo de esquema graphQL (.gql) que defina la estructura del documento.

El archivo de esquema usa el lenguaje de definición de esquema (SDL) de GraphQL estándar con dos directivas personalizadas:

directiva @model

La @model(name: "...") directiva es necesaria en cada tipo de GraphQL que exponga a través de DAB. El name valor debe coincidir exactamente con el nombre de la entidad en el archivo de configuración de DAB.

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

directiva @authorize

La @authorize directiva proporciona control de acceso de nivel de campo y de tipo para consultas GraphQL de Cosmos DB. Acepta un roles parámetro que enumera los roles que pueden tener acceso al campo o al tipo.

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

También puede aplicar @authorize en el nivel de tipo:

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

Para obtener una guía de configuración completa, consulte Configuración de Data API Builder para Azure Cosmos DB para NoSQL.

Falta de disponibilidad de la API REST

DAB no genera puntos de conexión REST para Azure Cosmos DB para NoSQL. Azure Cosmos DB proporciona una API REST nativa completa para las operaciones de documentos. Solo se generan puntos de conexión de GraphQL. Los documentos openAPI no se generan para las entidades de Cosmos DB.

Para acceder a los datos a través de REST, use directamente la API REST de Azure Cosmos DB .

Características no admitidas para Cosmos DB

No se admiten las siguientes características para Azure Cosmos DB para NoSQL:

PostgreSQL

Versión mínima

Se requiere PostgreSQL 11 o posterior. DAB usa Npgsql como controlador postgreSQL.

Tipos de datos no admitidos

DAB no admite los siguientes tipos de datos de PostgreSQL:

Procedimientos almacenados

Los procedimientos almacenados no se admiten para las entidades de PostgreSQL. En su lugar, use tablas y vistas.

MySQL

Versión mínima

Se requiere MySQL 8 o posterior.

Tipos de datos no admitidos

DAB no admite los siguientes tipos de datos mySQL:

Procedimientos almacenados

Los procedimientos almacenados no se admiten para las entidades MySQL. En su lugar, use tablas.

Azure Synapse Analytics (grupo de SQL dedicado)

Objetos compatibles

El grupo de SQL dedicado admite tablas, vistas y procedimientos almacenados, igual que SQL Server y Azure SQL. No se admite el grupo de SQL sin servidor.

Características no admitidas

Contenido relacionado

• Disponibilidad de características
• Referencia de configuración del origen de datos
• Implementación de la seguridad de nivel de fila con el contexto de sesión
• Configurar el generador de API de datos para Azure Cosmos DB para NoSQL
• Directivas de versiones y versiones