Databasspecifik funktionsreferens för Data API-byggare

Den här referensen beskriver funktioner, beteenden och krav som är specifika för en eller flera databasplattformar som stöds av Data API Builder (DAB). En jämförelsematris för funktioner mellan databaser finns i Funktionstillgänglighet.

Stöd för databasversion

DAB stöder följande databasplattformar. Lägsta versionskrav gäller för självhanterade distributioner. PaaS-databaser (Platform-as-a-Service) har inte något krav på lägsta version eftersom tjänsten hanterar versionen.

SQL Server och Azure SQL

SESSION_CONTEXT

För SQL Server och Azure SQL kan DAB sprida autentiserade användaranspråk till databasen genom att anropa sp_set_session_context innan varje fråga körs. Med den här mekanismen kan SQL-interna säkerhetsprinciper på radnivå och lagrade procedurer läsa anroparens identitet inifrån databasmotorn.

När set-session-context är aktiverat i DAB-konfigurationen skickar DAB alla autentiserade anspråk som nyckel/värde-par:

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;

Vanliga anspråk som skickas är roles, sub, oidoch alla anpassade anspråk som din identitetsprovider inkluderar i JWT.

Aktivera SESSION_CONTEXT

Ange --set-session-context true när du anropar dab init:

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

Eller ange egenskapen direkt i dab-config.json:

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

Använda SESSION_CONTEXT i SQL

När du har aktiverat set-session-contextkan dina SQL-objekt läsa anspråksvärdena:

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

En fullständig genomgång finns i Implementera säkerhet på radnivå med sessionskontext.

SESSION_CONTEXT och anslutningspooler

DAB återställer alla sessionskontextvärden i början av varje begäran. Men eftersom set-session-context tvingar per användare anslutningssemantik, undviks återanvändning av anslutningar mellan användare automatiskt när det här alternativet är aktiverat.

Varianter av anslutningssträngar

DAB använder Microsoft.Data.SqlClient för SQL Server och Azure SQL. Biblioteket stöder dessa anslutningssträngsformat.

Vanliga format:

Datatyper som inte stöds

Följande SQL Server- och Azure SQL-datatyper stöds inte av DAB:

Azure Cosmos DB för NoSQL

Schemakrav

Till skillnad från relationsdatabaser är Azure Cosmos DB for NoSQL schemaagnostisk. DAB kan inte introspekta en Cosmos DB-container för att generera GraphQL-typer. Du måste ange en GraphQL-schemafil (.gql) som definierar dokumentstrukturen.

Schemafilen använder Standard GraphQL Schema Definition Language (SDL) med två anpassade direktiv:

@model direktiv

Direktivet @model(name: "...") krävs för varje GraphQL-typ som du exponerar via DAB. Värdet name måste exakt matcha entitetsnamnet i DIN DAB-konfigurationsfil.

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

@authorize direktiv

Direktivet @authorize tillhandahåller åtkomstkontroll på fältnivå och typnivå för Cosmos DB GraphQL-frågor. Den accepterar en roles parameter som visar de roller som kan komma åt fältet eller typen.

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

Du kan också använda @authorize på typnivå:

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

En fullständig installationsguide finns i Konfigurera Data API Builder för Azure Cosmos DB för NoSQL.

REST API-otillgänglighet

DAB genererar inte REST-slutpunkter för Azure Cosmos DB för NoSQL. Azure Cosmos DB tillhandahåller ett omfattande internt REST API för dokumentåtgärder. Endast GraphQL-slutpunkter genereras. OpenAPI-dokument genereras inte för Cosmos DB-entiteter.

Om du vill komma åt data via REST använder du Rest-API:et för Azure Cosmos DB direkt.

Funktioner som inte stöds för Cosmos DB

Följande funktioner stöds inte för Azure Cosmos DB för NoSQL:

PostgreSQL

Lägsta version

PostgreSQL 11 eller senare krävs. DAB använder Npgsql som postgreSQL-drivrutin.

Datatyper som inte stöds

Följande PostgreSQL-datatyper stöds inte av DAB:

Lagrade procedurer

Lagrade procedurer stöds inte för PostgreSQL-entiteter. Använd tabeller och vyer i stället.

MySQL

Lägsta version

MySQL 8 eller senare krävs.

Datatyper som inte stöds

Följande MySQL-datatyper stöds inte av DAB:

Lagrade procedurer

Lagrade procedurer stöds inte för MySQL-entiteter. Använd tabeller i stället.

Azure Synapse Analytics (dedikerad SQL-pool)

Objekt som stöds

Dedikerad SQL-pool stöder tabeller, vyer och lagrade procedurer – samma som SQL Server och Azure SQL. Serverlös SQL-pool stöds inte.

Funktioner som inte stöds

Relaterat innehåll

• Funktionstillgänglighet
• Konfigurationsreferens för datakälla
• Implementera säkerhet på radnivå med sessionskontext
• Konfigurera Data API-byggare för Azure Cosmos DB för NoSQL
• Versions- och versionsprinciper