Databasspecifika funktioner för Data API Builder

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 att en lägsta version är kompatibel med Data API Builder (DAB).

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

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 få åtkomst till 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) som är tillgängligt 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. 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. SESSION_CONTEXT data är tillgängliga för databasen under databasanslutningen tills anslutningen stängs. Samma data kan också användas i en lagrad procedur.

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

Konfigurera SESSION_CONTEXT med options hjälp av egenskapen för data-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 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:

Mer information om anspråk finns i Microsoft Entra ID-referens för åtkomsttokenanspråk.

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 objekttypsdefinitionerna som representerar containerns datamodell. Data-API-byggare 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 ska den åtföljas av metadatavieweren begäranderubrik 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 på den översta typdefinitionen. Det här programmet begränsar åtkomsten till typen och dess fält uteslutande 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 mellan 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.