Dokumentacja funkcji specyficznych dla bazy danych dla konstruktora interfejsu API danych

Ta dokumentacja obejmuje funkcje, zachowania i wymagania specyficzne dla co najmniej jednej platformy bazy danych obsługiwanej przez konstruktora interfejsu API danych (DAB). Aby zapoznać się z macierzą porównania funkcji między bazami danych, zobacz Dostępność funkcji.

Obsługa wersji bazy danych

Język DAB obsługuje następujące platformy baz danych. Minimalne wymagania dotyczące wersji dotyczą wdrożeń zarządzanych samodzielnie. Bazy danych Typu platforma jako usługa (PaaS) nie mają wymagań dotyczących minimalnej wersji, ponieważ usługa zarządza wersją.

SQL Server i Azure SQL

SESSION_CONTEXT

W przypadku programu SQL Server i usługi Azure SQL usługa DAB może propagować uwierzytelnione oświadczenia użytkowników do bazy danych, wywołując wywołanie sp_set_session_context przed wykonaniem każdego zapytania. Ten mechanizm umożliwia natywnym dla języka SQL zasad zabezpieczeń na poziomie wiersza i procedur składowanych odczytywanie tożsamości obiektu wywołującego z aparatu bazy danych.

Po set-session-context włączeniu w konfiguracji języka DAB usługa DAB wysyła wszystkie uwierzytelnione oświadczenia jako pary klucz-wartość:

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;

Typowe wysyłane oświadczenia obejmują roles, sub, oidi wszelkie niestandardowe oświadczenia, które dostawca tożsamości zawiera w zestawie JWT.

Włączanie SESSION_CONTEXT

Ustaw --set-session-context true podczas wywoływania elementu dab init:

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

Możesz też ustawić właściwość bezpośrednio w pliku dab-config.json:

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

Używanie SESSION_CONTEXT w programie SQL

Po włączeniu set-session-contextobiektów SQL można odczytać wartości oświadczenia:

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

Aby zapoznać się z pełnym przewodnikiem, zobacz Implementowanie zabezpieczeń na poziomie wiersza z kontekstem sesji.

SESSION_CONTEXT i buforowanie połączeń

DaB resetuje wszystkie wartości kontekstu sesji na początku każdego żądania. Jednak ze względu na to, że set-session-context wymusza semantyka połączeń dla użytkownika, ponowne użycie połączenia między użytkownikami jest unikane automatycznie po włączeniu tej opcji.

Warianty parametrów połączenia

Język DAB jest używany Microsoft.Data.SqlClient dla programu SQL Server i usługi Azure SQL. Biblioteka obsługuje te formaty parametrów połączenia.

Typowe formaty:

Nieobsługiwane typy danych

Następujące typy danych SQL Server i Azure SQL nie są obsługiwane przez język DAB:

Azure Cosmos DB for NoSQL

Wymaganie dotyczące schematu

W przeciwieństwie do relacyjnych baz danych usługa Azure Cosmos DB for NoSQL jest niezależna od schematu. Język DAB nie może introspekować kontenera usługi Cosmos DB w celu wygenerowania typów GraphQL. Musisz podać plik schematu GraphQL (.gql), który definiuje strukturę dokumentu.

Plik schematu używa standardowego języka programowania GraphQL Schema Definition Language (SDL) z dwiema dyrektywami niestandardowymi:

@model dyrektywa

Dyrektywa jest wymagana @model(name: "...") w każdym typie GraphQL udostępnianym za pośrednictwem języka DAB. Wartość musi być dokładnie zgodna name z nazwą jednostki w pliku konfiguracji daB.

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

@authorize dyrektywa

Dyrektywa @authorize zapewnia kontrolę dostępu na poziomie pola i na poziomie typu dla zapytań GraphQL usługi Cosmos DB. Akceptuje roles on parametr zawierający listę ról, które mogą uzyskiwać dostęp do pola lub typu.

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

Można również zastosować na @authorize poziomie typu:

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

Aby uzyskać pełny przewodnik konfiguracji, zobacz Konfigurowanie konstruktora interfejsu API danych dla usługi Azure Cosmos DB for NoSQL.

Niedostępność interfejsu API REST

Język DAB nie generuje punktów końcowych REST dla usługi Azure Cosmos DB for NoSQL. Usługa Azure Cosmos DB udostępnia kompleksowy natywny interfejs API REST na potrzeby operacji dokumentów. Generowane są tylko punkty końcowe GraphQL. Dokumenty Interfejsu OpenAPI nie są generowane dla jednostek usługi Cosmos DB.

Aby uzyskać dostęp do danych za pośrednictwem interfejsu REST, użyj bezpośrednio interfejsu API REST usługi Azure Cosmos DB .

Nieobsługiwane funkcje dla usługi Cosmos DB

Następujące funkcje nie są obsługiwane w przypadku usługi Azure Cosmos DB for NoSQL:

PostgreSQL

Minimalna wersja

Wymagany jest program PostgreSQL 11 lub nowszy. Język DAB używa Npgsql jako sterownika PostgreSQL.

Nieobsługiwane typy danych

Następujące typy danych PostgreSQL nie są obsługiwane przez język DAB:

Procedury przechowywane

Procedury składowane nie są obsługiwane w przypadku jednostek PostgreSQL. Zamiast tego użyj tabel i widoków.

MySQL

Minimalna wersja

Wymagany jest program MySQL 8 lub nowszy.

Nieobsługiwane typy danych

Następujące typy danych MySQL nie są obsługiwane przez język DAB:

Procedury przechowywane

Procedury składowane nie są obsługiwane w przypadku jednostek MySQL. Zamiast tego użyj tabel.

Azure Synapse Analytics (Dedykowana pula SQL)

Obsługiwane obiekty

Dedykowana pula SQL obsługuje tabele, widoki i procedury składowane — takie same jak sql Server i Azure SQL. Bezserwerowa pula SQL nie jest obsługiwana.

Nieobsługiwane funkcje

Treści powiązane

• Dostępność funkcji
• Dokumentacja konfiguracji źródła danych
• Implementowanie zabezpieczeń na poziomie wiersza z kontekstem sesji
• Konfigurowanie konstruktora interfejsu API danych dla usługi Azure Cosmos DB dla noSQL
• Zasady wydawania i przechowywania wersji