Nastavení tvůrce rozhraní Data API pro Azure Cosmos DB pro NoSQL

Azure Cosmos DB pro NoSQL je databáze dokumentů nezávislá na schématu. Na rozdíl od relačních databází nemá služba Azure Cosmos DB předdefinované schéma, které může tvůrce rozhraní DATA API (DAB) automaticky introspektovat. Tento průvodce vysvětluje, jak vytvořit soubor schématu GraphQL a nakonfigurovat JAZYK DAB pro práci s kontejnery Azure Cosmos DB.

Předpoklady

Azure Cosmos DB pro účet NoSQL s alespoň jednou databází a kontejnerem
Rozhraní příkazového řádku pro tvorbu API dat. Instalace rozhraní příkazového řádku

Vysvětlení požadavku na schéma

Protože Azure Cosmos DB for NoSQL nevynucuje schéma, DAB nemůže automaticky generovat typy GraphQL z vašich dat. Místo toho musíte zadat soubor schématu GraphQL, který definuje:

Typy objektů , které představují strukturu dokumentů kontejneru
Direktiva@model, která mapuje typy GraphQL na názvy entit v konfiguraci DAB
Direktiva @authorize (volitelné), která omezuje přístup na úrovni pole na konkrétní role

Schéma můžete vytvořit pomocí následujících příkladů nebo ho dab export vygenerovat z existujících dat Cosmos DB pomocí příkazu.

Vytvoření souboru schématu GraphQL

Vytvořte .gql soubor, který popisuje datový model. Soubor schématu používá standardní jazyk SDL (GraphQL Schema Definition Language) s vlastními direktivami pro DAB.

Příklad základního schématu

Tento příklad definuje Book typ s běžnými poli nalezenými v kontejneru knih:

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
}

Generování schématu z dat Cosmos DB

Pokud už máte data v kontejnerech, můžete je ukázkovat a vytvořit počáteční schéma. Tento příkaz zapíše odvozený soubor schématu GraphQL do výstupního adresáře, který zadáte pomocí -o.

Bash
Příkazový řádek

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

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

Ve výchozím nastavení se vzorkování používá TopNExtractor.

Podporované režimy vzorkování jsou TopNExtractor, EligibleDataSamplera TimePartitionedSampler.

Poznámka:

Parametr -o/--output je povinný. Pokud nezadáte název souboru schématu, DAB vygeneruje schema.gql ve výstupním adresáři.

Další režimy a možnosti najdete v referenčních informacích k dab exportrozhraní příkazového řádku .

Direktiva @model je povinná. Přiřazuje typ GraphQL k názvu entity v konfiguračním souboru DAB. Parametr name musí přesně odpovídat názvu entity.

Poznámka:

Pole Authors: [Author] představuje vložené pole v dokumentu knihy, nikoli relaci k samostatnému kontejneru. V Azure Cosmos DB pro NoSQL by se související data měla vkládat do stejného dokumentu, a ne ukládat do samostatných kontejnerů.

Schéma s autorizací

Pokud chcete omezit přístup k určitým polím, použijte direktivu @authorize . Tato direktiva přijímá roles parametr, který určuje, které role mají přístup k poli.

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

V tomto příkladu:

Pole title je přístupné jenom uživatelům s rolí authenticated nebo metadataviewer rolí.
Pole internalNotes je přístupné jenom uživatelům s editor rolí.
Pole bez @authorize jsou přístupná na základě oprávnění na úrovni entity.

Můžete také použít @authorize na úrovni typu, abyste omezili přístup k celému typu:

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

Důležité

Direktiva @authorize funguje kromě oprávnění na úrovni entity definovaných v konfiguraci modulu runtime. @authorize Oprávnění jak direktivy, tak entity, musí umožňovat přístup, aby byl požadavek úspěšně realizován.

Pokud například pole obsahuje @authorize(roles: ["editor"]), ale entita nemá pro danou editor roli žádnou položku oprávnění, přístup k ho se odepře.

Výstraha

@authorize(policy: "...") není podporováno v tomto schématu toku. Použijte @authorize(roles: [...]).

Konfigurace prostředí runtime DAB

Po vytvoření souboru schématu nakonfigurujte JAZYK DAB tak, aby ho používal s vaším účtem Azure Cosmos DB.

Inicializujte konfiguraci

Pomocí příkazu dab init vytvořte konfigurační soubor pro Azure Cosmos DB:

Bash
Příkazový řádek

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>"

Nahraďte <your-database-name> názvem databáze Azure Cosmos DB a <your-connection-string> připojovacím řetězcem.

Volitelně můžete zahrnout --cosmosdb_nosql-container <your-container-name> k nastavení výchozího kontejneru v konfiguraci zdroje dat.

Návod

V produkčním prostředí místo pevného zakódování použijte proměnné prostředí pro připojovací řetězce.

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

Přidání entit

Přidejte entity, které odpovídají vašim kontejnerům. Název entity musí odpovídat hodnotě @model(name: "...") ve schématu:

Bash
Příkazový řádek

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

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

Parametr --source přijímá buď <container-name> nebo <database-name>.<container-name>. Formát dvou částí použijte, pokud chcete být explicitní pro databázi i kontejner.

Příklad konfiguračního souboru

Po inicializaci by konfigurační soubor měl vypadat podobně jako v následujícím příkladu:

{
  "$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"]
        }
      ]
    }
  }
}

Poznámka:

schema Cesta v konfiguračním souboru je relativní vzhledem k umístění konfiguračního souboru DAB. Ujistěte se, že je soubor schématu GraphQL ve správném adresáři.

Tato $schema adresa URL odkazuje na konkrétní verzi DAB. Použijte adresu URL schématu, která odpovídá vaší verzi DAB.

Přístup k polím na základě role

Při použití direktivy @authorize s rolemi zvažte, jak se role přiřazují:

Scénář	Přiřazení rolí	Přístup k polím `@authorize`
Anonymní požadavek	Žádné přiřazené role	Zamítnuto
Ověřený požadavek	Role `authenticated` systému je automaticky přiřazena.	Povoleno, pokud se role shoduje
Žádost o vlastní roli	`X-MS-API-ROLE` Zahrnutí záhlaví s názvem role	Povoleno, pokud se role shoduje

Tato tabulka se vztahuje na pole nebo typy, které explicitně obsahují @authorize. Pro pole bez @authorizeoprávnění na úrovni entity určují přístup.

U ověřených požadavků, které potřebují vlastní roli, odešlete hlavičku X-MS-API-ROLE :

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

Dotazy napříč kontejnery

Operace GraphQL napříč kontejnery se v Azure Cosmos DB pro NoSQL nepodporují.

Pokud se pokusíte nakonfigurovat vztahy mezi entitami v různých kontejnerech pomocí dab add nebo dab update, ověření CLI selže.

Chybová zpráva rozhraní příkazového řádku je: Adding/updating Relationships is currently not supported in CosmosDB.

Podrobnosti o konfiguraci relací (podporované pro jiné databáze) najdete v tématu Konfigurace relací.

Obcházet omezení mezi kontejnery

Pokud chcete toto omezení obejít, zvažte restrukturalizaci datového modelu tak, aby používal vložené dokumenty v rámci jednoho kontejneru. Tento přístup je často efektivnější pro službu Azure Cosmos DB a je v souladu s osvědčenými postupy modelování dat NoSQL.

Například místo samostatných Book a Author kontejnerů s relacemi:

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

Další informace o strategiích modelování dat najdete v tématu Modelování dat ve službě Azure Cosmos DB.

Dostupnost rozhraní REST API

Tvůrce rozhraní DATA API nevygeneruje koncové body REST pro Azure Cosmos DB pro NoSQL, protože Azure Cosmos DB už poskytuje komplexní nativní rozhraní REST API pro operace dokumentů.

Pokud používáte DAB se službou Azure Cosmos DB for NoSQL, DAB zveřejňuje pouze koncové body GraphQL a nevygeneruje OpenAPI. Pokud chcete získat přístup k datům přes REST, použijte přímo rozhraní Azure Cosmos DB REST API.

Běžné problémy s konfigurací

Soubor schématu nebyl nalezen.

Chyba: GraphQL schema file not found
Řešení: Ujistěte se, že schema cesta v konfiguraci je relativní vzhledem k umístění konfiguračního souboru.

Neshoda názvů entit

Chyba: Entity '<name>' not found in schema
Řešení: Ověřte, že název entity v konfiguraci přesně odpovídá direktivě @model(name: "...") . V názvech se rozlišují malá a velká písmena.

Neoprávněný přístup k polím

Chyba: Chyba autorizace GraphQL (například pokud není povolená role)
Řešení: Zkontrolujte, zda jak role, tak oprávnění entit umožňují přístup pro požadující roli.

Další krok

Rychlý start: Použití tvůrce rozhraní Data API s NoSQL

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-01

Nastavení tvůrce rozhraní Data API pro Azure Cosmos DB pro NoSQL

Předpoklady

Vysvětlení požadavku na schéma

Vytvoření souboru schématu GraphQL

Příklad základního schématu

Generování schématu z dat Cosmos DB

Schéma s autorizací

Konfigurace prostředí runtime DAB

Inicializujte konfiguraci

Přidání entit

Příklad konfiguračního souboru

Přístup k polím na základě role

Dotazy napříč kontejnery

Obcházet omezení mezi kontejnery

Dostupnost rozhraní REST API

Běžné problémy s konfigurací

Další krok

Související obsah

Váš názor

Další materiály