Referenční informace o funkcích specifických pro databázi pro tvůrce rozhraní Data API

Tento odkaz popisuje funkce, chování a požadavky specifické pro jednu nebo více databázových platforem podporovaných tvůrcem rozhraní DATA API (DAB). Srovnávací matici funkcí napříč databázemi najdete v tématu Dostupnost funkcí.

Podpora verzí databáze

DAB podporuje následující databázové platformy. Minimální požadavky na verzi platí pro samoobslužná nasazení. Databáze PaaS (Platforma jako služba) nemají minimální požadavek na verzi, protože tato služba spravuje verzi.

Databázová platforma Zkratka Minimální verze Poznámky
SQL Server Řada SQL 2016
Azure SQL Řada SQL Není k dispozici (PaaS)
Microsoft Fabric SQL Řada SQL Není k dispozici (PaaS)
Azure Cosmos DB for NoSQL Cosmos DB Není k dispozici (PaaS) Pouze GraphQL; žádné koncové body REST
PostgreSQL PGSQL 11
MySQL MySQL 8
Azure Synapse Analytics (vyhrazený SQL fond) SQLDW Není k dispozici (PaaS) Bezserverový fond SQL se nepodporuje.

Důležité

Ověřte, že místní vývojová databáze i všechny nasazené databáze splňují požadavek na minimální verzi. DAB se připojuje pomocí stejného ovladače v obou prostředích. Starší verze v obou umístěních způsobuje chyby za běhu.

SQL Server a Azure SQL

SESSION_CONTEXT

V případě SQL Serveru a Azure SQL může DAB rozšířit ověřené deklarace identity uživatelů do databáze voláním sp_set_session_context před spuštěním každého dotazu. Tento mechanismus umožňuje sql nativním zásadám zabezpečení na úrovni řádků a uloženým procedurám číst identitu volajícího z databázového stroje.

Když set-session-context je v konfiguraci DAB povolená, DAB odešle všechny ověřené deklarace identity jako páry klíč-hodnota:

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;

Mezi odesílané běžné deklarace identity patří roles, suboida všechny vlastní deklarace identity, které vaše zprostředkovatel identity zahrnuje v JWT.

Povolení SESSION_CONTEXT

Nastavit --set-session-context true při volání dab init:

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

Nebo vlastnost nastavte přímo v dab-config.json:

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

Výstraha

Povolení set-session-context zakáže ukládání odpovědí do mezipaměti pro tento zdroj dat. Vzhledem k tomu, že každý požadavek nastavuje jedinečné hodnoty relace, nesmí být odpovědi uložené v mezipaměti z relace jednoho uživatele obsluhovány do jiné.

Použití SESSION_CONTEXT v SQL

Po povolení set-session-contextmohou vaše objekty SQL číst hodnoty deklarací identity:

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

Úplný návod najdete v tématu Implementace zabezpečení na úrovni řádků s kontextem relace.

SESSION_CONTEXT a sdružování připojení

DAB resetuje všechny kontextové hodnoty relace na začátku každého požadavku. Vzhledem k tomu, že set-session-context vynutí sémantiku připojení pro jednotlivé uživatele, zabrání se opakované použití připojení mezi uživateli automaticky, když je tato možnost povolená.

Varianty připojovacích řetězců

DAB používá Microsoft.Data.SqlClient pro SQL Server a Azure SQL. Knihovna podporuje tyto formáty připojovacího řetězce.

Běžné formáty:

Metoda ověřování Model připojovacího řetězce
Přihlášení SQL Server=tcp:<server>.database.windows.net;Database=<db>;User ID=<user>;Password=<pwd>;
Spravovaná identita Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;
uživatelsky přiřazená spravovaná identita Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;User ID=<client-id>;
Výchozí přihlašovací údaje Azure Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Default;

Návod

Ukládat připojovací řetězce do proměnných prostředí a odkazovat na ně pomocí @env('SQL_CONNECTION_STRING'). Pro produkční nasazení uložte připojovací řetězec ve službě Azure Key Vault a odkazujte na něj .@akv()

Nepodporované datové typy

DAB nepodporuje následující datové typy SQL Serveru a Azure SQL:

Datový typ Reason
geography Geoprostorový typ; serializace není podporována
geometry Planární prostorový typ; serializace není podporována
hierarchyid Hierarchický datový typ; serializace není podporována
json Nativní typ JSON (aktuálně ve verzi Preview)
rowversion Typ správy verzí řádků; nezahrnut do odpovědí rozhraní API
sql_variant Sloupce s proměnným typem; Odvození typu není podporováno.
vector Typ vektoru (aktuálně ve verzi Preview)
xml Typ XML; serializace není podporována

Azure Cosmos DB for NoSQL

Požadavek na schéma

Na rozdíl od relačních databází je služba Azure Cosmos DB for NoSQL nezávislá na schématu. DAB nemůže introspektovat kontejner Cosmos DB pro generování typů GraphQL. Musíte zadat soubor schématu GraphQL (.gql), který definuje strukturu dokumentu.

Soubor schématu používá standardní jazyk SDL (GraphQL Schema Definition Language) se dvěma vlastními direktivami:

Direktiva Povinné Description
@model Ano Mapuje typ GraphQL na název entity DAB.
@authorize Ne Omezuje přístup k polím nebo typům na konkrétní role.

@model směrnice

Direktiva @model(name: "...") se vyžaduje pro každý typ GraphQL, který zveřejňujete prostřednictvím JAZYKA DAB. Hodnota name musí přesně odpovídat názvu entity v konfiguračním souboru DAB.

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

@authorize směrnice

Direktiva @authorize poskytuje řízení přístupu na úrovni polí a typů pro dotazy GraphQL služby Cosmos DB. Přijímá parametr se seznamem roles rolí, které mají přístup k poli nebo typu.

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

Můžete také použít @authorize na úrovni typu:

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

Důležité

Direktiva @authorizese přidá k oprávněním na úrovni entity. Direktiva i blok oprávnění entity musí umožňovat, aby žádost o přístup mohla proběhnout úspěšně. Pokud pole obsahuje @authorize(roles: ["editor"]) , ale entita nemá pro žádnou položku editoroprávnění, žádost se odmítne.

Poznámka:

@authorize(policy: "...") není podporováno. Používejte @authorize(roles: [...]) pouze.

Kompletní průvodce nastavením najdete v tématu Nastavení tvůrce rozhraní DATA API pro Azure Cosmos DB for NoSQL.

Nedostupnost rozhraní REST API

DAB negeneruje koncové body REST pro Azure Cosmos DB for NoSQL. Azure Cosmos DB poskytuje komplexní nativní rozhraní REST API pro operace dokumentů. Vygenerují se pouze koncové body GraphQL. Dokumenty OpenAPI se negenerují pro entity Cosmos DB.

Pokud chcete získat přístup k datům přes REST, použijte přímo rozhraní REST API služby Azure Cosmos DB .

Nepodporované funkce pro Cosmos DB

Azure Cosmos DB for NoSQL nepodporuje následující funkce:

funkce Poznámky
Koncové body REST Místo toho použijte nativní rozhraní REST API služby Cosmos DB.
Zásady databáze Predikáty zásad vyžadují sémantiku relačních dotazů.
Uložené procedury Nepodporuje se jako entity DAB.
Relationships Relace mezi kontejnery se nepodporují.
Řazení ($orderby) Nepodporuje se v dotazech GraphQL
Aggregation Nepodporováno
Více mutací Nepodporováno
Kontext relace Funkce specifická pro SQL

PostgreSQL

Minimální verze

Vyžaduje se PostgreSQL 11 nebo novější. JAZYK DAB používá Npgsql jako ovladač PostgreSQL.

Nepodporované datové typy

DaB nepodporuje následující datové typy PostgreSQL:

Datový typ Poznámky
bytea Binární řetězec; serializace není podporována
date Použít timestamp nebo timestamptz
smalldatetime Nejedná se o nativní typ PostgreSQL
datetime2 Není nativní; obvykle zvládá timestamp
timestamptz Časové razítko s časovým pásmem; nepodporováno
time Čas dne bez data
localtime Systémový čas založený na hodinách

Uložené procedury

U entit PostgreSQL se uložené procedury nepodporují. Místo toho používejte tabulky a zobrazení.

MySQL

Minimální verze

Vyžaduje se MySQL 8 nebo novější.

Nepodporované datové typy

DaB nepodporuje následující datové typy MySQL:

Datový typ Poznámky
UUID Univerzální jedinečné identifikátory
DATE Kalendářní data
SMALLDATETIME Méně přesné úložiště data a času
DATETIME2 Není nativní; Použít datetime
DATETIMEOFFSET Data a časy s časovým pásmem
TIME Čas dne bez data
LOCALTIME Aktuální čas založený na systémových hodinách

Uložené procedury

Uložené procedury nejsou podporované pro entity MySQL. Místo toho používejte tabulky.

Azure Synapse Analytics (vyhrazený SQL fond)

Podporované objekty

Vyhrazený fond SQL podporuje tabulky, zobrazení a uložené procedury – stejné jako SQL Server a Azure SQL. Bezserverový fond SQL se nepodporuje.

Nepodporované funkce

funkce Poznámky
Více mutací Nepodporováno

Související obsah

  • Last updated on