Einrichten des Daten-API-Generators für Azure Cosmos DB für NoSQL

Azure Cosmos DB für NoSQL ist eine schemaunabhängige Dokumentdatenbank. Im Gegensatz zu relationalen Datenbanken hat Azure Cosmos DB kein vordefiniertes Schema, das der Daten-API-Generator (DAB) automatisch ermitteln kann. In diesem Handbuch wird erläutert, wie Sie eine GraphQL-Schemadatei erstellen und DAB für die Arbeit mit Ihren Azure Cosmos DB-Containern konfigurieren.

Voraussetzungen

Azure Cosmos DB für NoSQL-Konto mit mindestens einer Datenbank und einem Container
CLI des Daten-API-Erstellers. Installieren der CLI

Grundlegendes zur Schemaanforderung

Da Azure Cosmos DB für NoSQL kein Schema erzwingt, kann DAB nicht automatisch GraphQL-Typen aus Ihren Daten generieren. Stattdessen müssen Sie eine GraphQL-Schemadatei bereitstellen, die Folgendes definiert:

Objekttypen , die die Dokumentstruktur Ihres Containers darstellen
Die @model Direktive, die GraphQL-Typen zu Entitätsnamen in Ihrer DAB-Konfiguration zuordnet
Die @authorize Direktive (optional), die den Zugriff auf Feldebene auf bestimmte Rollen beschränkt

Sie können das Schema mithilfe der folgenden Beispiele manuell erstellen oder aus vorhandenen Cosmos DB-Daten mit dem dab export Befehl generieren.

Erstellen einer GraphQL-Schemadatei

Erstellen Sie eine .gql Datei, die Ihr Datenmodell beschreibt. Die Schemadatei verwendet standardmäßige GraphQL Schema Definition Language (SDL) mit benutzerdefinierten Direktiven für DAB.

Beispiel für ein einfaches Schema

In diesem Beispiel wird ein Book Typ mit allgemeinen Feldern definiert, die in einem Büchercontainer enthalten sind:

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
  pages: Int
  Authors: [Author]
}

type Author @model(name: "Author") {
  id: ID
  firstName: String
  lastName: String
}

Generieren eines Schemas aus Cosmos DB-Daten

Wenn Sie bereits Daten in Ihren Containern haben, können Sie es beispielen, um ein Startschema zu erstellen. Dieser Befehl schreibt eine abgeleitete GraphQL-Schemadatei in das von Ihnen mit -o angegebene Ausgabeverzeichnis.

Bash
Eingabeaufforderung

dab export \
  --graphql \
  --generate \
  -o ./schema-out

dab export ^
  --graphql ^
  --generate ^
  -o .\schema-out

Standardmäßig verwendet das Sampling TopNExtractor.

Die unterstützten Samplingmodi sind TopNExtractor, EligibleDataSamplerund TimePartitionedSampler.

Hinweis

Der -o/--output Parameter ist erforderlich. Wenn Sie keinen Schemadateinamen angeben, generiert DAB schema.gql im Ausgabeverzeichnis.

Weitere Modi und Optionen finden Sie in der CLI-Referenz für dab export.

Die @model Richtlinie ist erforderlich. Er ordnet den GraphQL-Typ einem Entitätsnamen in Ihrer DAB-Konfigurationsdatei zu. Der name Parameter muss exakt mit dem Entitätsnamen übereinstimmen.

Hinweis

Das Authors: [Author] Feld stellt ein eingebettetes Array innerhalb des Book-Dokuments dar, keine Beziehung zu einem separaten Container. In Azure Cosmos DB für NoSQL sollten verwandte Daten in dasselbe Dokument eingebettet werden und nicht in separaten Containern gespeichert werden.

Schema mit Autorisierung

Verwenden Sie die @authorize Direktive, um den Zugriff auf bestimmte Felder einzuschränken. Diese Direktive akzeptiert einen roles Parameter, der angibt, welche Rollen auf das Feld zugreifen können.

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

In diesem Beispiel:

Auf das Feld title kann nur von Benutzern mit der Rolle authenticated oder metadataviewer zugegriffen werden.
Auf das internalNotes Feld kann nur für Benutzer mit der editor Rolle zugegriffen werden.
Felder ohne @authorize sind basierend auf Berechtigungen auf Entitätsebene zugänglich.

Sie können auch auf Typebene anwenden @authorize , um den Zugriff auf den gesamten Typ einzuschränken:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["editor", "auditor"]) {
  id: ID
  title: String
  confidentialData: String
}

Von Bedeutung

Die @authorize Direktive funktioniert zusätzlich zu berechtigungen auf Entitätsebene, die in der Laufzeitkonfiguration definiert sind. Sowohl die Direktive als auch die @authorize Entitätsberechtigungen müssen den Zugriff zulassen, damit eine Anforderung erfolgreich ausgeführt werden kann.

Wenn z. B. ein Feld @authorize(roles: ["editor"])hat, aber die Entität keinen Berechtigungseintrag für die editor Rolle hat, wird der Zugriff auf dieses Feld verweigert.

Warnung

@authorize(policy: "...") wird in diesem Schemafluss nicht unterstützt. Verwenden Sie @authorize(roles: [...]).

Konfigurieren der DAB-Laufzeit

Nachdem Sie Ihre Schemadatei erstellt haben, konfigurieren Sie DAB für die Verwendung mit Ihrem Azure Cosmos DB-Konto.

Initialisieren der Konfiguration

Verwenden Sie den Befehl dab init, um eine Konfigurationsdatei für Azure Cosmos DB zu erstellen:

Bash
Eingabeaufforderung

dab init \
  --database-type cosmosdb_nosql \
  --cosmosdb_nosql-database <your-database-name> \
  --graphql-schema schema.gql \
  --connection-string "<your-connection-string>"

dab init ^
  --database-type cosmosdb_nosql ^
  --cosmosdb_nosql-database <your-database-name> ^
  --graphql-schema schema.gql ^
  --connection-string "<your-connection-string>"

Ersetzen Sie <your-database-name> durch den Namen Ihrer Azure Cosmos DB-Datenbank und <your-connection-string> durch Ihre Verbindungszeichenfolge.

Optionalerweise können Sie --cosmosdb_nosql-container <your-container-name> als einen Standardcontainer in der Datenquellenkonfiguration festlegen.

Tipp

Verwenden Sie für Produktionsumgebungen Umgebungsvariablen für Verbindungszeichenfolgen, anstatt sie zu hartcodieren:

dab init \
    --database-type cosmosdb_nosql \
    --cosmosdb_nosql-database <your-database-name> \
    --graphql-schema schema.gql \
    --connection-string "@env('COSMOSDB_CONNECTION_STRING')"

Hinzufügen von Entitäten

Fügen Sie Entitäten hinzu, die Ihren Containern entsprechen. Der Entitätsname muss mit dem @model(name: "...") Wert in Ihrem Schema übereinstimmen:

Bash
Eingabeaufforderung

dab add Book \
  --source Book \
  --permissions "anonymous:read"

dab add Book ^
  --source Book ^
  --permissions "anonymous:read"

Der --source Parameter akzeptiert entweder <container-name> oder <database-name>.<container-name>. Verwenden Sie das zweiteilige Format, wenn Sie sowohl zu Datenbank als auch container explizit sein möchten.

Beispielkonfigurationsdatei

Nach der Initialisierung sollte die Konfigurationsdatei dem folgenden Beispiel ähneln:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.2.11/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "Library",
      "schema": "schema.gql"
    },
    "connection-string": "@env('COSMOSDB_CONNECTION_STRING')"
  },
  "entities": {
    "Book": {
      "source": "Book",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "metadataviewer",
          "actions": ["read"]
        }
      ]
    }
  }
}

Hinweis

Der schema Pfad in der Konfigurationsdatei ist relativ zum Speicherort der DAB-Konfigurationsdatei. Stellen Sie sicher, dass sich Ihre GraphQL-Schemadatei im richtigen Verzeichnis befindet.

Diese $schema URL verweist auf eine bestimmte DAB-Version. Verwenden Sie die Schema-URL, die Ihrer DAB-Version entspricht.

Rollenbasierter Feldzugriff

Berücksichtigen Sie bei der Verwendung der Anweisung @authorize zusammen mit Rollen, wie Rollen zugewiesen werden:

Szenario	Rollenzuweisung	Zugriff auf `@authorize` Felder
Anonyme Anforderung	Keine Rollen zugewiesen	Verweigert
Authentifizierte Anforderung	Die `authenticated` Systemrolle wird automatisch zugewiesen.	Zulässig, wenn die Rolle übereinstimmt
Benutzerdefinierte Rollenanforderung	Die `X-MS-API-ROLE` Headerzeile mit dem Rollennamen einschließen	Zulässig, wenn die Rolle übereinstimmt

Diese Tabelle gilt für Felder oder Typen, die @authorize explizit enthalten sind. Für Felder ohne @authorize bestimmen Berechtigungen auf Entitätsebene den Zugriff.

Senden Sie für authentifizierte Anforderungen, die eine benutzerdefinierte Rolle benötigen, den X-MS-API-ROLE Header:

GET /graphql HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your-jwt-token>
X-MS-API-ROLE: metadataviewer

Containerübergreifende Abfragen

GraphQL-Vorgänge über Container hinweg werden in Azure Cosmos DB für NoSQL nicht unterstützt.

Wenn Sie versuchen, Beziehungen zwischen Entitäten in verschiedenen Containern mithilfe dab add oder dab updatezu konfigurieren, schlägt die CLI-Überprüfung fehl.

Die CLI-Fehlermeldung lautet: Adding/updating Relationships is currently not supported in CosmosDB.

Details zur Beziehungskonfiguration (unterstützt für andere Datenbanken) finden Sie unter "Beziehungen"-Konfiguration.

Umgehen von containerübergreifenden Einschränkungen

Um diese Einschränkung zu umgehen, sollten Sie das Datenmodell neu gestalten, um eingebettete Dokumente in einem einzigen Container zu verwenden. Dieser Ansatz ist häufig effizienter für Azure Cosmos DB und richtet sich an bewährte Methoden zur NoSQL-Datenmodellierung.

Statt beispielsweise separate Book- und Author-Container mit Beziehungen zu nutzen.

// Embedded model in a single container
{
  "id": "book-1",
  "title": "Introduction to DAB",
  "authors": [
    {
      "firstName": "Jane",
      "lastName": "Developer"
    }
  ]
}

Weitere Informationen zu Datenmodellierungsstrategien finden Sie unter Datenmodellierung in Azure Cosmos DB.

REST-API-Verfügbarkeit

Der Daten-API-Generator generiert keine REST-Endpunkte für Azure Cosmos DB für NoSQL, da Azure Cosmos DB bereits eine umfassende native REST-API für Dokumentvorgänge bereitstellt.

Wenn Sie DAB mit Azure Cosmos DB für NoSQL verwenden, macht DAB nur GraphQL-Endpunkte verfügbar und generiert openAPI nicht. Um über REST auf Ihre Daten zuzugreifen, verwenden Sie die Azure Cosmos DB REST-API direkt.

Allgemeine Konfigurationsprobleme

Schemadatei nicht gefunden

Fehler: GraphQL schema file not found
Lösung: Stellen Sie sicher, dass der schema Pfad in Ihrer Konfiguration relativ zum Speicherort der Konfigurationsdatei ist.

Nichtübereinstimmung des Entitätsnamens

Fehler: Entity '<name>' not found in schema
Lösung: Überprüfen Sie, ob der Entitätsname in Ihrer Konfiguration genau mit der @model(name: "...") Direktive übereinstimmt. Bei Namen wird die Groß-/Kleinschreibung beachtet.

Nicht autorisierter Feldzugriff

Fehler: GraphQL-Autorisierungsfehler (z. B. wenn die Rolle nicht zulässig ist)
Lösung: Überprüfen Sie, ob sowohl Rollen als auch @authorize Entitätsberechtigungen den Zugriff auf die anfordernde Rolle ermöglichen.

Nächster Schritt

Quickstart: Verwenden des Daten-API-Generators mit NoSQL

Feedback

War diese Seite hilfreich?

Last updated on 2026-04-01

Freigeben über

Einrichten des Daten-API-Generators für Azure Cosmos DB für NoSQL

Voraussetzungen

Grundlegendes zur Schemaanforderung

Erstellen einer GraphQL-Schemadatei

Beispiel für ein einfaches Schema

Generieren eines Schemas aus Cosmos DB-Daten

Schema mit Autorisierung

Konfigurieren der DAB-Laufzeit

Initialisieren der Konfiguration

Hinzufügen von Entitäten

Beispielkonfigurationsdatei

Rollenbasierter Feldzugriff

Containerübergreifende Abfragen

Umgehen von containerübergreifenden Einschränkungen

REST-API-Verfügbarkeit

Allgemeine Konfigurationsprobleme

Nächster Schritt

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen