Informazioni di riferimento sulle funzionalità specifiche del database per Il generatore di API dati

Questo riferimento illustra funzionalità, comportamenti e requisiti specifici di una o più piattaforme di database supportate dal generatore di API dati (DAB). Per una matrice di confronto delle funzionalità tra database, vedere Disponibilità delle funzionalità.

Supporto della versione del database

DAB supporta le piattaforme di database seguenti. I requisiti minimi di versione si applicano alle distribuzioni autogestito. I database PaaS (Platform-as-a-Service) non hanno un requisito di versione minima perché il servizio gestisce la versione.

SQL Server e SQL di Azure

SESSION_CONTEXT

Per SQL Server e AZURE SQL, DAB può propagare le attestazioni utente autenticate al database chiamando sp_set_session_context prima di eseguire ogni query. Questo meccanismo consente ai criteri di sicurezza a livello di riga nativi di SQL e alle stored procedure di leggere l'identità del chiamante dall'interno del motore di database.

Quando set-session-context è abilitata nella configurazione DAB, DAB invia tutte le attestazioni autenticate come coppie chiave-valore:

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;

Le attestazioni comuni inviate includono roles, sub, oide tutte le attestazioni personalizzate incluse nel token JWT.

Abilitare SESSION_CONTEXT

Impostare --set-session-context true quando si chiama dab init:

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

In alternativa, impostare la proprietà direttamente in dab-config.json:

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

Usare SESSION_CONTEXT in SQL

Dopo aver abilitato set-session-context, gli oggetti SQL possono leggere i valori dell'attestazione:

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

Per una procedura dettagliata completa, vedere Implementare la sicurezza a livello di riga con il contesto della sessione.

SESSION_CONTEXT e pool di connessioni

DAB reimposta tutti i valori di contesto della sessione all'inizio di ogni richiesta. Tuttavia, poiché set-session-context forza la semantica di connessione per utente, il riutilizzo della connessione tra gli utenti viene evitato automaticamente quando questa opzione è abilitata.

Varianti delle stringhe di connessione

DAB usa Microsoft.Data.SqlClient per SQL Server e Azure SQL. La libreria supporta questi formati di stringa di connessione.

Formati comuni:

Tipi di dati non supportati

I tipi di dati SQL Server e SQL di Azure seguenti non sono supportati da DAB:

Azure Cosmos DB per il NoSQL

Requisito dello schema

A differenza dei database relazionali, Azure Cosmos DB per NoSQL è indipendente dallo schema. DAB non può introspettire un contenitore Cosmos DB per generare tipi GraphQL. È necessario specificare un file di schema GraphQL (.gql) che definisce la struttura del documento.

Il file di schema usa il linguaggio SDL (GraphQL Schema Definition Language) standard con due direttive personalizzate:

@model direttiva

La @model(name: "...") direttiva è necessaria per ogni tipo GraphQL esposto tramite DAB. Il name valore deve corrispondere esattamente al nome dell'entità nel file di configurazione DAB.

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

@authorize direttiva

La @authorize direttiva fornisce il controllo di accesso a livello di campo e a livello di tipo per le query GraphQL di Cosmos DB. Accetta un roles parametro che elenca i ruoli che possono accedere al campo o al tipo.

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

È anche possibile applicare @authorize a livello di tipo:

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

Per una guida completa alla configurazione, vedere Configurare Generatore API dati per Azure Cosmos DB per NoSQL.

Indisponibilità dell'API REST

DAB non genera endpoint REST per Azure Cosmos DB per NoSQL. Azure Cosmos DB offre un'API REST nativa completa per le operazioni sui documenti. Vengono generati solo gli endpoint GraphQL. I documenti OpenAPI non vengono generati per le entità cosmos DB.

Per accedere ai dati tramite REST, usare direttamente l'API REST di Azure Cosmos DB .

Funzionalità non supportate per Cosmos DB

Le funzionalità seguenti non sono supportate per Azure Cosmos DB per NoSQL:

PostgreSQL

Versione minima

È necessario PostgreSQL 11 o versione successiva. DAB usa Npgsql come driver PostgreSQL.

Tipi di dati non supportati

I tipi di dati PostgreSQL seguenti non sono supportati da DAB:

Procedure memorizzate

Le stored procedure non sono supportate per le entità PostgreSQL. Usare invece tabelle e viste.

MySQL

Versione minima

MySQL 8 o versione successiva è obbligatorio.

Tipi di dati non supportati

I tipi di dati MySQL seguenti non sono supportati da DAB:

Procedure memorizzate

Le stored procedure non sono supportate per le entità MySQL. Usare invece le tabelle.

Azure Synapse Analytics (pool SQL dedicato)

Oggetti supportati

Il pool SQL dedicato supporta tabelle, viste e stored procedure, come SQL Server e Azure SQL. Il pool SQL serverless non è supportato.

Funzionalità non supportate

Contenuti correlati

• Disponibilità delle funzionalità
• Informazioni di riferimento sulla configurazione dell'origine dati
• Implementare la sicurezza a livello di riga con il contesto della sessione
• Configura il Data API Builder per Azure Cosmos DB per NoSQL
• Criteri di rilascio e controllo delle versioni