Datenbankspezifische Features für Data API Builder

Artikel
04/13/2024

Der Daten-API-Generator ermöglicht jeder Datenbank ihre eigenen spezifischen Features. In diesem Artikel werden die Features erläutert, die für jede Datenbank unterstützt werden.

Datenbankversionsunterstützung

Viele herkömmliche Datenbanken erfordern eine Mindestversion, um mit data API Builder (DAB) kompatibel zu sein.

	Unterstützte Mindestversion
SQL Server	2016
MySQL	8
PostgreSQL	11

Umgekehrt arbeiten Azure-Clouddatenbankdienste sofort mit DAB, ohne dass eine bestimmte Version erforderlich ist.

	Unterstützte Mindestversion
Azure SQL	–
Azure Cosmos DB for NoSQL	–
Azure Cosmos DB for PostgreSQL	–

Azure SQL und SQL Server

Es gibt einige spezifische Eigenschaften, die für SQL eindeutig sind, einschließlich Azure SQL und SQL Server.

SESSION_CONTEXT

Azure SQL und SQL Server unterstützen die Verwendung der SESSION_CONTEXT Funktion für den Zugriff auf die Identität des aktuellen Benutzers. Dieses Feature ist nützlich, wenn Sie die native Unterstützung für die Sicherheit auf Zeilenebene (RLS) anwenden möchten, die in Azure SQL und SQL Server verfügbar ist.

Für Azure SQL und SQL Server kann der Daten-API-Generator die Vorteile SESSION_CONTEXT nutzen, um vom Benutzer angegebene Metadaten an die zugrunde liegende Datenbank zu senden. Solche Metadaten stehen dem Daten-API-Generator aufgrund der im Zugriffstoken vorhandenen Ansprüche zur Verfügung. Die an die Datenbank gesendeten Daten können dann verwendet werden, um eine zusätzliche Sicherheitsstufe zu konfigurieren (z. B. durch Konfigurieren von Sicherheitsrichtlinien), um den Zugriff auf Daten in Vorgängen wie SELECT, UPDATE, DELETE weiter zu verhindern. Die SESSION_CONTEXT Daten stehen der Datenbank während der Datenbankverbindung zur Verfügung, bis diese Verbindung geschlossen wird. Dieselben Daten können auch in einer gespeicherten Prozedur verwendet werden.

Weitere Informationen zum Festlegen SESSION_CONTEXT von Daten finden Sie unter sp_set_session_context (Transact-SQL).

Konfigurieren Sie SESSION_CONTEXT mithilfe der options -Eigenschaft des data-source Abschnitts in der Konfigurationsdatei. Weitere Informationen finden Sie unter data-source Konfigurationsreferenz.

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

Alternativ können Sie das --set-session-context Argument mit dem dab init Befehl verwenden.

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

Alle im EasyAuth/JWT-Token vorhandenen Ansprüche werden über die an die SESSION_CONTEXT zugrunde liegende Datenbank gesendet. Alle im Token vorhandenen Ansprüche werden in Schlüssel-Wert-Paare übersetzt, die über SESSION_CONTEXT die Abfrage übergeben werden. Diese Ansprüche umfassen, sind aber nicht beschränkt auf:

	BESCHREIBUNG
`aud`	Zielgruppe
`iss`	Issuer (Aussteller)
`iat`	Ausgestellt um
`exp`	Ablaufzeit
`azp`	Anwendungsbezeichner
`azpacr`	Authentifizierungsmethode des Clients
`name`	Subject
`uti`	Eindeutiger Tokenbezeichner

Weitere Informationen zu Ansprüchen finden Sie unter Microsoft Entra ID Referenz zu Zugriffstokenansprüchen.

Diese Ansprüche werden in eine SQL-Abfrage übersetzt. Dieses abgeschnittene Beispiel veranschaulicht, wie sp_set_session_context in diesem Kontext verwendet wird:

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;

Anschließend können Sie die Sicherheit auf Zeilenebene (RLS) mithilfe der Sitzungsdaten implementieren. Weitere Informationen finden Sie unter Implementieren von Sicherheit auf Zeilenebene mit Sitzungskontext.

Azure Cosmos DB

Es gibt einige spezifische Eigenschaften, die für verschiedene APIs in Azure Cosmos DB eindeutig sind.

Schema in der API für NoSQL

Azure Cosmos DB for NoSQL ist schemaunabhängig. Um den Daten-API-Generator mit der API für NoSQL zu verwenden, müssen Sie eine GraphQL Schemadatei erstellen, die die Objekttypdefinitionen enthält, die das Datenmodell Ihres Containers darstellen. Der Daten-API-Generator erwartet auch, dass Ihre GraphQL Objekttypdefinitionen und -felder die GraphQL Schemadirektive authorize enthalten, wenn Sie einen restriktiveren Lesezugriff als anonymouserzwingen möchten.

Diese Schemadatei stellt beispielsweise ein Book Element in einem Container dar. Dieses Element enthält mindestens title Eigenschaften und Authors .

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

Dieses Beispielschema entspricht der folgenden Entitätskonfiguration in der DAB-Konfigurationsdatei. Weitere Informationen finden Sie unter entities Konfigurationsreferenz.

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

Die @authorize -Direktive mit roles:["metadataviewer","authenticated"] beschränkt den Zugriff auf das title Feld nur auf Benutzer mit den Rollen metadataviewer und authenticated. Authentifizierten Anforderern wird die Systemrolle authenticated automatisch zugewiesen, sodass kein X-MS-API-ROLE Header mehr erforderlich ist.

Wenn die authentifizierte Anforderung im Kontext von metadataviewerausgeführt werden muss, sollte sie mit einem Anforderungsheader vom Typ X-MS-API-ROLE begleitet werden, der auf metadataviewerfestgelegt ist. Wenn jedoch anonymer Zugriff gewünscht ist, müssen Sie die autorisierte Anweisung weglassen.

Die @model -Direktive wird verwendet, um eine Korrelation zwischen diesem GraphQL Objekttyp und dem entsprechenden Entitätsnamen in der Laufzeitkonfiguration herzustellen. Die Direktive ist wie folgt formatiert:@model(name:"<Entity_Name>")

Als tieferes Beispiel kann die @authorize Direktive auf die Typdefinition der obersten Ebene angewendet werden. Diese Anwendung schränkt den Zugriff auf den Typ und seine Felder ausschließlich auf die in der Direktive angegebenen Rollen ein.

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

Containerübergreifende Abfragen in der API für NoSQL

GraphQL Vorgänge über Container hinweg werden nicht unterstützt. Das Modul antwortet mit einer Fehlermeldung, die folgendes besagt: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Sie können diese Einschränkung umgehen, indem Sie Ihr Datenmodell aktualisieren, um Entitäten innerhalb desselben Containers in einem eingebetteten Format zu speichern. Weitere Informationen finden Sie unter Datenmodellierung in Azure Cosmos DB for NoSQL.

Freigeben über