Databasespecifieke functies voor Data API Builder

Artikel
04/13/2024

Met Data API Builder kan elke database zijn eigen specifieke functies hebben. In dit artikel worden de functies beschreven die voor elke database worden ondersteund.

Ondersteuning voor databaseversies

Voor veel traditionele databases is een minimale versie vereist om compatibel te zijn met Data API Builder (DAB).

	Minimaal ondersteunde versie
SQL Server	2016
MySQL	8
PostgreSQL	11

Azure-clouddatabaseservices werken daarentegen standaard met DAB zonder dat hiervoor een specifieke versie is vereist.

	Minimaal ondersteunde versie
Azure SQL	n.v.t.
Azure Cosmos DB voor NoSQL	n.v.t.
Azure Cosmos DB for PostgreSQL	n.v.t.

Azure SQL en SQL Server

Er zijn enkele specifieke eigenschappen die uniek zijn voor SQL, waaronder zowel Azure SQL als SQL Server.

SESSION_CONTEXT

Azure SQL en SQL Server ondersteunen het gebruik van de SESSION_CONTEXT functie voor toegang tot de identiteit van de huidige gebruiker. Deze functie is handig als u de systeemeigen ondersteuning voor beveiliging op rijniveau (RLS) wilt toepassen die beschikbaar is in Azure SQL en SQL Server.

Voor Azure SQL en SQL Server kan Data API Builder profiteren van het verzenden van SESSION_CONTEXT door de gebruiker opgegeven metagegevens naar de onderliggende database. Dergelijke metagegevens zijn beschikbaar voor Data API Builder op basis van de claims die aanwezig zijn in het toegangstoken. De gegevens die naar de database worden verzonden, kunnen vervolgens worden gebruikt om een extra beveiligingsniveau te configureren (bijvoorbeeld door beveiligingsbeleid te configureren) om de toegang tot gegevens verder te voorkomen in bewerkingen zoals SELECT, UPDATE, DELETE. De SESSION_CONTEXT gegevens zijn beschikbaar voor de database tijdens de databaseverbinding totdat die verbinding wordt gesloten. Dezelfde gegevens kunnen ook worden gebruikt in een opgeslagen procedure.

Zie (Transact-SQL) voor meer informatie over het instellen SESSION_CONTEXT van gegevenssp_set_session_context.

Configureer SESSION_CONTEXT met behulp van de options eigenschap van de data-source sectie in het configuratiebestand. Zie configuratiereferentie voor meer informatiedata-source.

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

U kunt ook het --set-session-context argument gebruiken met de dab init opdracht .

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

Alle claims die aanwezig zijn in het EasyAuth/JWT-token, worden via de SESSION_CONTEXT verzonden naar de onderliggende database. Alle claims die aanwezig zijn in het token, worden omgezet in sleutel-waardeparen die via SESSION_CONTEXT een query worden doorgegeven. Deze claims omvatten, maar zijn niet beperkt tot:

	Description
`aud`	Doelgroep
`iss`	Verlener
`iat`	Uitgegeven om
`exp`	Verlooptijd
`azp`	Toepassings-id
`azpacr`	Verificatiemethode van de client
`name`	Onderwerp
`uti`	Unieke token-id

Zie naslaginformatie over toegangstokenclaims Microsoft Entra ID voor meer informatie over claims.

Deze claims worden omgezet in een SQL-query. In dit afgekapte voorbeeld ziet u hoe sp_set_session_context in deze context wordt gebruikt:

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;

Vervolgens kunt u beveiliging op rijniveau (RLS) implementeren met behulp van de sessiegegevens. Zie Beveiliging op rijniveau implementeren met sessiecontext voor meer informatie.

Azure Cosmos DB

Er zijn enkele specifieke eigenschappen die uniek zijn voor verschillende API's in Azure Cosmos DB.

Schema in API for NoSQL

Azure Cosmos DB voor NoSQL is schemaneutraal. Als u Data API Builder wilt gebruiken met de API voor NoSQL, moet u een GraphQL-schemabestand maken dat de objecttypedefinities bevat die het gegevensmodel van uw container vertegenwoordigen. Data API Builder verwacht ook dat definities en velden van het GraphQL-objecttype de GraphQL-schema-instructie authorize bevatten als u meer beperkende leestoegang wilt afdwingen dan anonymous.

Dit schemabestand vertegenwoordigt bijvoorbeeld een Book item in een container. Dit item bevat minimaal title eigenschappen en Authors .

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

Dit voorbeeldschema komt overeen met de volgende entiteitsconfiguratie in het DAB-configuratiebestand. Zie configuratiereferentie voor meer informatieentities.

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

De @authorize -instructie met roles:["metadataviewer","authenticated"] beperkt de toegang tot het title veld tot alleen gebruikers met de rollen metadataviewer en authenticated. Voor geverifieerde aanvragers wordt de systeemrol authenticated automatisch toegewezen, waardoor een header niet meer nodig X-MS-API-ROLE is.

Als de geverifieerde aanvraag moet worden uitgevoerd in de context van , moet deze vergezeld gaan van metadataviewereen aanvraagheader van het type X-MS-API-ROLE dat is ingesteld op metadataviewer. Als anonieme toegang echter gewenst is, moet u de geautoriseerde instructie weglaten.

De @model instructie wordt gebruikt om een correlatie tot stand te brengen tussen dit GraphQL-objecttype en de bijbehorende entiteitsnaam in de runtime-configuratie. De instructie is opgemaakt als: @model(name:"<Entity_Name>")

Als een dieper voorbeeld kan de @authorize instructie worden toegepast op de typedefinitie op het hoogste niveau. Deze toepassing beperkt de toegang tot het type en de bijbehorende velden uitsluitend tot de rollen die in de instructie zijn opgegeven.

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

Query's voor meerdere containers in API for NoSQL

GraphQL-bewerkingen in containers worden niet ondersteund. De engine reageert met een foutbericht waarin staat: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

U kunt deze beperking omzeilen door uw gegevensmodel bij te werken om entiteiten in dezelfde container in een ingesloten indeling op te slaan. Zie Gegevensmodellering in Azure Cosmos DB for NoSQL voor meer informatie.

Delen via