Databasspecifika funktioner för Data API Builder

Artikel
04/13/2024

Med Data API Builder kan varje databas ha sina egna specifika funktioner. Den här artikeln beskriver de funktioner som stöds för varje databas.

Stöd för databasversion

Många traditionella databaser kräver en lägsta version för att vara kompatibel med Data API Builder (DAB).

	Lägsta version som stöds
SQL Server	2016
MySQL	8
PostgreSQL	11

Omvänt fungerar Azures molndatabastjänster med DAB direkt utan att kräva en specifik version.

	Lägsta version som stöds
Azure SQL	saknas
Azure Cosmos DB för NoSQL	saknas
Azure Cosmos DB for PostgreSQL	saknas

Azure SQL och SQL Server

Det finns några specifika egenskaper som är unika för SQL, inklusive både Azure SQL och SQL Server.

SESSION_CONTEXT

Azure SQL och SQL Server stöder användningen av SESSION_CONTEXT funktionen för att komma åt den aktuella användarens identitet. Den här funktionen är användbar när du vill använda det inbyggda stödet för säkerhet på radnivå (RLS) i Azure SQL och SQL Server.

För Azure SQL och SQL Server kan Data API Builder dra nytta av SESSION_CONTEXT för att skicka användardefinierade metadata till den underliggande databasen. Sådana metadata är tillgängliga för Data API Builder på grund av de anspråk som finns i åtkomsttoken. De data som skickas till databasen kan sedan användas för att konfigurera en extra säkerhetsnivå (till exempel genom att konfigurera säkerhetsprinciper) för att ytterligare förhindra åtkomst till data i åtgärder som SELECT, UPDATE, DELETE. Data SESSION_CONTEXT är tillgängliga för databasen under databasanslutningen tills anslutningen har stängts. Samma data kan också användas i en lagrad procedur.

Mer information om hur du anger SESSION_CONTEXT data finns isp_set_session_context (Transact-SQL).

Konfigurera SESSION_CONTEXT med egenskapen för optionsdata-source avsnittet i konfigurationsfilen. Mer information finns i data-source konfigurationsreferens.

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

Du kan också använda --set-session-context argumentet med dab init kommandot .

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

Alla anspråk som finns i EasyAuth/JWT-token skickas via SESSION_CONTEXT till den underliggande databasen. Alla anspråk som finns i token översätts till nyckel/värde-par som skickas via SESSION_CONTEXT fråga. Dessa anspråk omfattar, men är inte begränsade till:

	Description
`aud`	Målgrupp
`iss`	Utfärdare
`iat`	Utfärdat på
`exp`	Förfallotid
`azp`	Programidentifierare
`azpacr`	Autentiseringsmetod för klienten
`name`	Ämne
`uti`	Unik tokenidentifierare

Mer information om anspråk finns i Microsoft Entra ID anspråksreferens för åtkomsttoken.

Dessa anspråk översätts till en SQL-fråga. Det här trunkerade exemplet illustrerar hur sp_set_session_context används i den här kontexten:

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;

Du kan sedan implementera säkerhet på radnivå (RLS) med hjälp av sessionsdata. Mer information finns i Implementera säkerhet på radnivå med sessionskontext.

Azure Cosmos DB

Det finns några specifika egenskaper som är unika för olika API:er i Azure Cosmos DB.

Schema i API för NoSQL

Azure Cosmos DB för NoSQL är schemaagnostisk. För att kunna använda Data API Builder med API:et för NoSQL måste du skapa en GraphQL-schemafil som innehåller objekttypsdefinitioner som representerar containerns datamodell. Data API Builder förväntar sig också att graphQL-objekttypsdefinitioner och -fält ska inkludera GraphQL-schemadirektivet authorize när du vill framtvinga mer restriktiv läsåtkomst än anonymous.

Den här schemafilen representerar till exempel ett Book objekt i en container. Det här objektet innehåller minst title och Authors egenskaper.

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

Det här exempelschemat motsvarar följande entitetskonfiguration i DAB-konfigurationsfilen. Mer information finns i entities konfigurationsreferens.

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

Direktivet @authorize med roles:["metadataviewer","authenticated"] begränsar åtkomsten till fältet title till endast användare med rollerna metadataviewer och authenticated. För autentiserade begäranden tilldelas systemrollen authenticated automatiskt, vilket eliminerar behovet av ett X-MS-API-ROLE huvud.

Om den autentiserade begäran måste köras i kontexten för , bör den åtföljas av metadataviewerett begärandehuvud av typen X-MS-API-ROLE inställd på metadataviewer. Men om anonym åtkomst önskas måste du utelämna det auktoriserade direktivet.

Direktivet @model används för att upprätta en korrelation mellan den här GraphQL-objekttypen och motsvarande entitetsnamn i körningskonfigurationen. Direktivet är formaterat som: @model(name:"<Entity_Name>")

Som ett djupare exempel @authorize kan direktivet tillämpas i definitionen av den översta nivån. Det här programmet begränsar åtkomsten till typen och dess fält exklusivt till de roller som anges i direktivet.

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

Frågor mellan containrar i API för NoSQL

GraphQL-åtgärder för containrar stöds inte. Motorn svarar med ett felmeddelande om att Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Du kan kringgå den här begränsningen genom att uppdatera datamodellen för att lagra entiteter i samma container i ett inbäddat format. Mer information finns i datamodellering i Azure Cosmos DB för NoSQL.

Dela via