Referência de funcionalidades específicas da base de dados para o Data API builder

Esta referência abrange funcionalidades, comportamentos e requisitos específicos de uma ou mais plataformas de bases de dados suportadas pelo Data API builder (DAB). Para uma matriz de comparação de funcionalidades entre bases de dados, consulte Disponibilidade de funcionalidades.

Suporte à versão do banco de dados

O DAB suporta as seguintes plataformas de bases de dados. Os requisitos mínimos de versão aplicam-se a implementações autogeridas. As bases de dados Platform-as-a-Service (PaaS) não têm um requisito mínimo de versão porque o serviço gere essa versão.

SQL Server e Azure SQL

SESSION_CONTEXT

Para SQL Server e Azure SQL, o DAB pode propagar reivindicações autenticadas do utilizador para a base de dados chamando sp_set_session_context antes de executar cada consulta. Este mecanismo permite que políticas de segurança nativas SQL ao nível de linha e procedimentos armazenados leiam a identidade do chamador a partir do motor da base de dados.

Quando set-session-context está ativado na configuração DAB, o DAB envia todas as reivindicaçõ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 reclamações comuns enviadas incluem roles, sub, oid, e quaisquer reivindicações personalizadas que o seu fornecedor de identidade inclua no JWT.

Ativar 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 definir 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 em SQL

Depois de ativar set-session-context, os seus objetos SQL podem ler os valores das reivindicações:

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

SESSION_CONTEXT e pooling de ligações

O DAB reinicia todos os valores do contexto da sessão no início de cada pedido. No entanto, como set-session-context força a semântica de ligação por utilizador, a reutilização de ligação entre utilizadores é evitada automaticamente quando esta opção está ativada.

Variantes de cordas de ligação

O DAB usa Microsoft.Data.SqlClient SQL Server e Azure SQL. A biblioteca suporta estes formatos de string de ligação.

Formatos comuns:

Tipos de dados não suportados

Os seguintes tipos de dados SQL Server e Azure SQL não são suportados pelo DAB:

Azure Cosmos DB for NoSQL

Requisito de esquema

Ao contrário das bases de dados relacionais, o Azure Cosmos DB para NoSQL é independente do esquema. O DAB não pode introspeção de um contentor Cosmos DB para gerar tipos GraphQL. Deve fornecer um ficheiro de esquema GraphQL (.gql) que defina a estrutura do seu documento.

O ficheiro de esquema utiliza a Linguagem de Definição de Esquemas (SDL) padrão GraphQL com duas diretivas personalizadas:

@model diretiva

A @model(name: "...") diretiva é exigida em todos os tipos de GraphQL que expões através do DAB. O name valor deve corresponder exatamente ao nome da entidade no seu ficheiro de configuração DAB.

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

@authorize diretiva

A @authorize diretiva fornece controlo de acesso ao nível de campo e de tipo para consultas Cosmos DB GraphQL. Aceita um roles parâmetro que lista os papéis que podem aceder ao campo ou tipo.

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

Também pode candidatar-se @authorize ao nível do tipo:

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

Para um guia completo de configuração, consulte Configurar o construtor de API de dados para Azure Cosmos DB para NoSQL.

Indisponibilidade da API REST

O DAB não gera endpoints REST para Azure Cosmos DB para NoSQL. O Azure Cosmos DB fornece uma API nativa REST abrangente para operações de documentos. Apenas os endpoints GraphQL são gerados. Os documentos OpenAPI não são gerados para entidades do Cosmos DB.

Para aceder a dados através do REST, use diretamente a API REST da base de dados do Azure Cosmos .

Funcionalidades não suportadas para o Cosmos DB

As seguintes funcionalidades não são suportadas para o Azure Cosmos DB para NoSQL:

PostgreSQL

Versão mínima

PostgreSQL 11 ou posterior é obrigatório. O DAB utiliza Npgsql como driver PostgreSQL.

Tipos de dados não suportados

Os seguintes tipos de dados PostgreSQL não são suportados pelo DAB:

Procedimentos armazenados

Procedimentos armazenados não são suportados para entidades PostgreSQL. Usa tabelas e vistas em vez disso.

MySQL

Versão mínima

MySQL 8 ou posterior é obrigatório.

Tipos de dados não suportados

Os seguintes tipos de dados MySQL não são suportados pelo DAB:

Procedimentos armazenados

Os procedimentos armazenados não são suportados para entidades MySQL. Usa tabelas em vez disso.

Azure Synapse Analytics (Dedicated SQL pool)

Objetos suportados

O pool SQL dedicado suporta tabelas, vistas e procedimentos armazenados — tal como o SQL Server e o Azure SQL. O pool SQL serverless não é suportado.

Funcionalidades não suportadas

Conteúdo relacionado

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