Funzionalità specifiche del database per Generatore API dati

Articolo
04/13/2024

Generatore API dati consente a ogni database di avere le proprie funzionalità specifiche. Questo articolo illustra in dettaglio le funzionalità supportate per ogni database.

Supporto della versione del database

Molti database tradizionali richiedono una versione minima compatibile con Il generatore API dati (DAB).

	Versione minima supportata
SQL Server	2016
MySQL	8
PostgreSQL	11

Al contrario, i servizi di database cloud di Azure funzionano con DAB fuori casella senza richiedere una versione specifica.

	Versione minima supportata
SQL di Azure	n/d
Azure Cosmos DB for NoSQL	n/d
Azure Cosmos DB for PostgreSQL	n/d

Azure SQL e SQL Server

Esistono alcune proprietà specifiche che sono univoche per SQL, tra cui Azure SQL e SQL Server.

SESSION_CONTEXT

Azure SQL e SQL Server supportano l'uso della SESSION_CONTEXT funzione per accedere all'identità dell'utente corrente. Questa funzionalità è utile quando si vuole applicare il supporto nativo per la sicurezza a livello di riga (RLS) disponibile in Azure SQL e SQL Server.

Per Azure SQL e SQL Server, Generatore API dati può sfruttare il vantaggio di SESSION_CONTEXT inviare metadati specificati dall'utente al database sottostante. Tali metadati sono disponibili per generatore API dati a causa delle attestazioni presenti nel token di accesso. I dati inviati al database possono quindi essere usati per configurare un livello di sicurezza aggiuntivo ,ad esempio configurando i criteri di sicurezza, per impedire ulteriormente l'accesso ai dati nelle operazioni come SELECT, UPDATE, DELETE. I SESSION_CONTEXT dati sono disponibili per il database durante la connessione al database finché tale connessione non viene chiusa. Gli stessi dati possono essere usati anche all'interno di una stored procedure.

Per altre informazioni sull'impostazione SESSION_CONTEXT dei dati, vedere sp_set_session_context (Transact-SQL).

Configurare SESSION_CONTEXT l'uso optionsdata-source della proprietà della sezione nel file di configurazione. Per altre informazioni, vedere data-source Informazioni di riferimento sulla configurazione.

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

In alternativa, usare l'argomento --set-session-context con il dab init comando .

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

Tutte le attestazioni presenti nel token EasyAuth/JWT vengono inviate tramite il SESSION_CONTEXT database sottostante. Tutte le attestazioni presenti nel token vengono tradotte in coppie chiave-valore passate tramite SESSION_CONTEXT query. Queste attestazioni includono, ma non sono limitate a:

	Descrizione
`aud`	Destinatari
`iss`	Issuer
`iat`	Ora di emissione
`exp`	Scadenza
`azp`	Identificatore dell'applicazione
`azpacr`	Metodo di autenticazione del client
`name`	Oggetto
`uti`	Identificatore univoco del token

Per altre informazioni sulle attestazioni, vedere Microsoft Entra ID informazioni di riferimento sulle attestazioni del token di accesso.

Queste attestazioni vengono tradotte in una query SQL. Questo esempio troncato illustra come sp_set_session_context viene usato in questo contesto:

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;

È quindi possibile implementare la sicurezza a livello di riga usando i dati della sessione. Per altre informazioni, vedere Implementare la sicurezza a livello di riga con il contesto di sessione.

Azure Cosmos DB

Esistono alcune proprietà specifiche univoche per varie API in Azure Cosmos DB.

Schema nell'API per NoSQL

Azure Cosmos DB for NoSQL B è completamente indipendente dallo schema. Per usare Generatore API dati con l'API per NoSQL, è necessario creare un file di schema GraphQL che include le definizioni dei tipi di oggetto che rappresentano il modello di dati del contenitore. Il generatore api dati prevede inoltre che le definizioni e i campi del tipo di oggetto GraphQL includano la direttiva authorize dello schema GraphQL quando si vuole applicare l'accesso in lettura più restrittivo rispetto anonymousa .

Ad esempio, questo file di schema rappresenta un Book elemento all'interno di un contenitore. Questo elemento contiene, almeno, title e Authors proprietà.

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

Questo schema di esempio corrisponde alla configurazione dell'entità seguente nel file di configurazione DAB. Per altre informazioni, vedere entities Informazioni di riferimento sulla configurazione.

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

La @authorize direttiva con roles:["metadataviewer","authenticated"] limita l'accesso title al campo solo agli utenti con i ruoli metadataviewer e authenticated. Per i richiedenti autenticati, il ruolo authenticated di sistema viene assegnato automaticamente, eliminando la necessità di un'intestazione X-MS-API-ROLE .

Se la richiesta autenticata deve essere eseguita nel contesto di metadataviewer, deve essere accompagnata da un'intestazione di richiesta di tipo X-MS-API-ROLE impostata su metadataviewer. Tuttavia, se l'accesso anonimo è desiderato, è necessario omettere la direttiva autorizzata.

La @model direttiva viene utilizzata per stabilire una correlazione tra questo tipo di oggetto GraphQL e il nome di entità corrispondente nella configurazione di runtime. La direttiva viene formattata come: @model(name:"<Entity_Name>")

Come esempio più approfondito, la @authorize direttiva può essere applicata alla definizione di tipo di primo livello. Questa applicazione limita l'accesso al tipo e ai relativi campi esclusivamente ai ruoli specificati all'interno della direttiva.

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": [ "*" ]
      }
    ]
  }
}

Query tra contenitori nell'API per NoSQL

Le operazioni GraphQL tra contenitori non sono supportate. Il motore risponde con un messaggio di errore che indica, Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

È possibile risolvere questa limitazione aggiornando il modello di dati per archiviare le entità all'interno dello stesso contenitore in un formato incorporato. Per altre informazioni, vedere Modellazione dei dati in Azure Cosmos DB per NoSQL.

Condividi tramite