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

Artículo
04/13/2024

Data API Builder permite que cada base de datos tenga sus propias características específicas. En este artículo se detallan las características que se admiten para cada base de datos.

Compatibilidad con la versión de la base de datos

Muchas bases de datos tradicionales requieren que una versión mínima sea compatible con Data API Builder (DAB).

	Versión mínima admitida
SQL Server	2016
MySQL	8
PostgreSQL	11

Por el contrario, los servicios de base de datos en la nube de Azure funcionan con DAB de fábrica sin necesidad de una versión específica.

	Versión mínima admitida
SQL de Azure	N/D
Azure Cosmos DB para NoSQL	N/D
Azure Cosmos DB para PostgreSQL	N/D

Azure SQL y SQL Server

Hay algunas propiedades específicas que son exclusivas de SQL, incluidos Azure SQL y SQL Server.

SESSION_CONTEXT

Azure SQL y SQL Server admiten el uso de la SESSION_CONTEXT función para acceder a la identidad del usuario actual. Esta característica es útil cuando desea aplicar la compatibilidad nativa con la seguridad de nivel de fila (RLS) disponible en Azure SQL y SQL Server.

Para Azure SQL y SQL Server, Data API Builder puede aprovechar las ventajas de SESSION_CONTEXT enviar metadatos especificados por el usuario a la base de datos subyacente. Estos metadatos están disponibles para data API Builder en virtud de las notificaciones presentes en el token de acceso. Los datos enviados a la base de datos se pueden usar para configurar un nivel adicional de seguridad (por ejemplo, mediante la configuración de directivas de seguridad) para evitar aún más el acceso a los datos en operaciones como SELECT, UPDATE, DELETE. Los SESSION_CONTEXT datos están disponibles para la base de datos durante la conexión de la base de datos hasta que se cierra esa conexión. También se pueden usar los mismos datos dentro de un procedimiento almacenado.

Para obtener más información sobre cómo establecer SESSION_CONTEXT datos, vea sp_set_session_context (Transact-SQL).

Configure SESSION_CONTEXT mediante la options propiedad de la data-source sección del archivo de configuración. Para obtener más información, consulte data-source la referencia de configuración.

{
  ...
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": true
    },
    "connection-string": "<connection-string>"
  },
  ...
}

Como alternativa, use el --set-session-context argumento con el dab init comando .

dab init --database-type mssql --set-session-context true

Todas las notificaciones presentes en el token easyAuth/JWT se envían a través SESSION_CONTEXT de a la base de datos subyacente. Todas las notificaciones presentes en el token se traducen en pares clave-valor pasados a través de la SESSION_CONTEXT consulta. Estas notificaciones incluyen, pero no se limitan a:

	Descripción
`aud`	Público
`iss`	Emisor
`iat`	Emitido a las
`exp`	Fecha de expiración
`azp`	Identificador de aplicación
`azpacr`	Método de autenticación del cliente
`name`	Asunto
`uti`	Identificador de token único

Para obtener más información sobre las notificaciones, consulte Microsoft Entra ID referencia de notificaciones de token de acceso.

Estas notificaciones se traducen en una consulta SQL. En este ejemplo truncado se muestra cómo sp_set_session_context se usa en este contexto:

EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
EXEC sp_set_session_context 'iss', 'https://login.microsoftonline.com/<TenantID>/v2.0', @read_only = 1;
EXEC sp_set_session_context 'iat', '1637043209', @read_only = 1;
...
EXEC sp_set_session_context 'azp', 'a903e2e6-fd13-4502-8cae-9e09f86b7a6c', @read_only = 1;
EXEC sp_set_session_context 'azpacr', 1, @read_only = 1;
..
EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;

Después, puede implementar la seguridad de nivel de fila (RLS) mediante los datos de sesión. Para obtener más información, consulte Implementación de la seguridad de nivel de fila con el contexto de sesión.

Azure Cosmos DB

Hay algunas propiedades específicas que son exclusivas de varias API en Azure Cosmos DB.

Esquema en LA API para NoSQL

Azure Cosmos DB for NoSQL es independiente del esquema. Para usar Data API Builder con la API para NoSQL, debe crear un archivo de esquema graphQL que incluya las definiciones de tipo de objeto que representan el modelo de datos del contenedor. Data API Builder también espera que las definiciones y los campos del tipo de objeto graphQL incluyan la directiva authorize de esquema GraphQL cuando quiera aplicar un acceso de lectura más restrictivo que anonymous.

Por ejemplo, este archivo de esquema representa un Book elemento dentro de un contenedor. Este elemento contiene, como mínimo, title propiedades y Authors .

type Book @model(name:"Book"){
  id: ID
  title: String @authorize(roles:["metadataviewer","authenticated"])
  Authors: [Author]
}

Este esquema de ejemplo corresponde a la siguiente configuración de entidad en el archivo de configuración DAB. Para obtener más información, consulte entities la referencia de configuración.

{
  ...
  "Book": {
    "source": "Book",
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "read" ]
      },
      {
        "role": "metadataviewer",
        "actions": [ "read" ]
      }
    ]
  }
  ...
}

La @authorize directiva con roles:["metadataviewer","authenticated"] restringe el acceso al title campo solo a los usuarios con los roles metadataviewer y authenticated. En el caso de los solicitantes autenticados, el rol authenticated del sistema se asigna automáticamente, lo que elimina la necesidad de un X-MS-API-ROLE encabezado.

Si la solicitud autenticada debe ejecutarse en el contexto de metadataviewer, debe ir acompañada de un encabezado de solicitud de tipo X-MS-API-ROLE establecido metadatavieweren . Sin embargo, si se desea el acceso anónimo, debe omitir la directiva autorizada.

La @model directiva se utiliza para establecer una correlación entre este tipo de objeto GraphQL y el nombre de entidad correspondiente en la configuración en tiempo de ejecución. La directiva tiene el formato siguiente: @model(name:"<Entity_Name>")

Como ejemplo más profundo, la @authorize directiva se puede aplicar en la definición de tipo de nivel superior. Esta aplicación restringe el acceso al tipo y sus campos exclusivamente a los roles especificados en la directiva .

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

{
  "Book": {
    "source": "Series",
    "permissions": [
      {
        "role": "authenticated",
        "actions": [ "read" ]
      },
      {
        "role": "editor",
        "actions": [ "*" ]
      }
    ]
  }
}

Consultas entre contenedores en la API para NoSQL

No se admiten las operaciones de GraphQL entre contenedores. El motor responde con un mensaje de error que indica: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Puede solucionar esta limitación actualizando el modelo de datos para almacenar entidades dentro del mismo contenedor en un formato incrustado. Para más información, consulte Modelado de datos en Azure Cosmos DB para NoSQL.

Compartir a través de