Referência de recursos específicos do banco de dados para o construtor de API de Dados

Essa referência aborda recursos, comportamentos e requisitos específicos para uma ou mais plataformas de banco de dados compatíveis com o DAB (Construtor de API de Dados). Para obter uma matriz de comparação de recursos entre bancos de dados, consulte a disponibilidade de recursos.

Suporte à versão do banco de dados

O DAB dá suporte às seguintes plataformas de banco de dados. Os requisitos mínimos de versão se aplicam a implantações autogerenciadas. Os bancos de dados PaaS (plataforma como serviço) não têm um requisito mínimo de versão porque o serviço gerencia a versão.

SQL Server e SQL do Azure

SESSION_CONTEXT

Para SQL Server e SQL do Azure, o DAB pode propagar declarações de usuário autenticadas para o banco de dados chamando sp_set_session_context antes de executar cada consulta. Esse mecanismo permite que políticas de segurança de nível de linha nativas do SQL e procedimentos armazenados leiam a identidade do chamador de dentro do mecanismo de banco de dados.

Quando set-session-context estiver habilitado na configuração do DAB, o DAB enviará todas as declarações autenticadas como pares chave-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;

As declarações comuns enviadas incluem roles, sube oidquaisquer declarações personalizadas que seu provedor de identidade inclua no JWT.

Habilitar SESSION_CONTEXT

Definir --set-session-context true ao chamar dab init:

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

Ou defina a propriedade diretamente em dab-config.json:

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

Usar SESSION_CONTEXT no SQL

Depois de habilitar set-session-context, seus objetos SQL podem ler os valores de declaração:

-- 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 obter um passo a passo completo, consulte Implementar segurança em nível de linha com contexto de sessão.

SESSION_CONTEXT e pool de conexões

O DAB redefine todos os valores de contexto de sessão no início de cada solicitação. No entanto, como set-session-context força a semântica de conexão por usuário, a reutilização da conexão entre usuários é evitada automaticamente quando essa opção está habilitada.

Variantes da cadeia de conexão

O DAB usa Microsoft.Data.SqlClient o SQL Server e o SQL do Azure. A biblioteca dá suporte a esses formatos de cadeia de conexão.

Formatos comuns:

Tipos de dados sem suporte

Os seguintes tipos de dados SQL Server e SQL do Azure não são compatíveis com o DAB:

Azure Cosmos DB for NoSQL

Requisito de esquema

Ao contrário dos bancos de dados relacionais, o Azure Cosmos DB para NoSQL é independente de esquema. O DAB não pode introspectar um contêiner do Cosmos DB para gerar tipos de GraphQL. Você deve fornecer um arquivo de esquema GraphQL (.gql) que defina sua estrutura de documentos.

O arquivo de esquema usa sdl (linguagem de definição de esquema) do GraphQL padrão com duas diretivas personalizadas:

Diretiva @model

A @model(name: "...") diretiva é necessária em todos os tipos de GraphQL que você expõe por meio do DAB. O name valor deve corresponder exatamente ao nome da entidade no arquivo de configuração do DAB.

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

Diretiva @authorize

A @authorize diretiva fornece controle de acesso em nível de campo e de tipo para consultas Do GraphQL do Cosmos DB. Ele aceita um roles parâmetro listando as funções que podem acessar o campo ou o tipo.

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

Você também pode aplicar @authorize no nível de tipo:

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

Para obter um guia de instalação completo, consulte Configurar o construtor de API de Dados para o Azure Cosmos DB para NoSQL.

Indisponibilidade da API REST

O DAB não gera pontos de extremidade REST para o Azure Cosmos DB para NoSQL. O Azure Cosmos DB fornece uma API REST nativa abrangente para operações de documento. Somente pontos de extremidade do GraphQL são gerados. Documentos OpenAPI não são gerados para entidades do Cosmos DB.

Para acessar dados pelo REST, use a API REST do Azure Cosmos DB diretamente.

Recursos sem suporte para o Cosmos DB

Não há suporte para os seguintes recursos para o Azure Cosmos DB para NoSQL:

PostgreSQL

Versão mínima

PostgreSQL 11 ou posterior é necessário. O DAB usa Npgsql como driver PostgreSQL.

Tipos de dados sem suporte

Os seguintes tipos de dados PostgreSQL não são compatíveis com o DAB:

Procedimentos armazenados

Não há suporte para procedimentos armazenados para entidades postgreSQL. Em vez disso, use tabelas e exibições.

MySQL

Versão mínima

MySQL 8 ou posterior é necessário.

Tipos de dados sem suporte

Os seguintes tipos de dados MySQL não são compatíveis com o DAB:

Procedimentos armazenados

Não há suporte para procedimentos armazenados para entidades MySQL. Em vez disso, use tabelas.

Azure Synapse Analytics (pool de SQL dedicado)

Objetos com suporte

O pool de SQL dedicado dá suporte a tabelas, exibições e procedimentos armazenados, o mesmo que o SQL Server e o SQL do Azure. Não há suporte para o pool de SQL sem servidor.

Recursos sem suporte

Conteúdo relacionado

• Disponibilidade de recursos
• Referência de configuração da fonte de dados
• Implementar segurança em nível de linha com contexto de sessão
• Configurar o construtor de API de Dados para o Azure Cosmos DB para NoSQL
• Políticas de versão e controle de versão