Databasespecifieke functies voor Data API Builder

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

Ondersteuning voor databaseversies

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

	Minimaal ondersteunde versie
SQL Server	2016
MySQL	8
PostgreSQL	11

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

	Minimaal ondersteunde versie
Azure SQL	n/a
Azure Cosmos DB voor NoSQL	n/a
Azure Cosmos DB for PostgreSQL	n/a

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 SESSION_CONTEXT om door de gebruiker opgegeven metagegevens naar de onderliggende database te verzenden. Dergelijke metagegevens zijn beschikbaar voor Data API Builder op grond 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 in bewerkingen zoals SELECT, UPDATE, DELETE verder te voorkomen. De SESSION_CONTEXT gegevens zijn beschikbaar voor de database tijdens de databaseverbinding totdat deze verbinding is 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 data-source de configuratiereferentie voor meer informatie.

{
  ...
  "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 verzonden via de SESSION_CONTEXT onderliggende database. Alle claims die aanwezig zijn in het token, worden omgezet in sleutel-waardeparen die worden doorgegeven via SESSION_CONTEXT de query. Deze claims omvatten, maar zijn niet beperkt tot:

	Description
aud	Audience
iss	Issuer
iat	Issued at
exp	Expiration time
azp	Application identifier
azpacr	Verificatiemethode van de client
name	Subject
uti	Unieke token-id

Zie de referentie voor microsoft Entra ID-toegangstokenclaims 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 voor NoSQL

Azure Cosmos DB for 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 uw GraphQL-objecttypedefinities en -velden de GraphQL-schemarichtlijn authorize bevatten wanneer u meer beperkende leestoegang wilt afdwingen dan anonymous.

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

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 entities de configuratiereferentie voor meer informatie.

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

De @authorize richtlijn 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 er geen header meer nodig is X-MS-API-ROLE .

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

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

Als dieper voorbeeld kan de @authorize richtlijn worden toegepast op de definitie van het type op het hoogste niveau. Deze toepassing beperkt de toegang tot het type en de bijbehorende velden uitsluitend tot de rollen die in de richtlijn 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 tussen containers in API voor NoSQL

GraphQL-bewerkingen tussen containers worden niet ondersteund. De engine reageert met een foutbericht met de mededeling: 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 op te slaan in een ingesloten indeling. Zie gegevensmodellering in Azure Cosmos DB voor NoSQL voor meer informatie.