A Data API Builder konfigurációs sémájának referenciája

A Data API Builder futtatásához legalább egy konfigurációs fájlra van szükség. Ez a JSON-alapú fájl határozza meg az API beállítását a környezeti beállításoktól az entitásdefiníciókig. Egy tulajdonsággal $schema kezdődik, amely lehetővé teszi a fájl többi részének sémaérvényesítését.

Legfelső szintű tulajdonságok

Ingatlan Leírás
$schema A konfiguráció JSON-sémájának URI-ja.
adatforrás Adatbázis-kapcsolati beállításokat tartalmazó objektum.
adatforrásfájlok Egyéb konfigurációs fájl elérési útjainak tömbje.
runtime Futtatókörnyezeti viselkedést konfiguráló objektum.
entitások A REST vagy GraphQL használatával közzétett összes entitást meghatározó objektum.
autoentities Mintaalapú szabályokat meghatározó objektum, amely automatikusan elérhetővé teszi az egyező adatbázis-objektumokat entitásként (csak MSSQL).
azure-key-vault Azure Key Vault-konfiguráció titkos kódok kezeléséhez.

Adatforrás tulajdonságai

Ingatlan Leírás
adatforrás Adatbázis-kapcsolati beállításokat tartalmazó objektum.
data-source.database-type A háttérrendszerben használt adatbázistípus (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql).
data-source.connection-string A kijelölt adatbázistípus kapcsolati sztringje.
data-source.options Adatbázis-specifikus beállítások és speciális beállítások.
adatforrás.health Az adatforrás állapot-ellenőrzési konfigurációja.
adatforrásfájlok Egyéb konfigurációs fájl elérési útjainak tömbje.

Futtatókörnyezet tulajdonságai

Ingatlan Leírás
runtime Futtatókörnyezeti viselkedést konfiguráló objektum.
runtime.pagination Az API-válaszok lapozási beállításai.
runtime.rest A REST API globális konfigurációja.
runtime.graphql GraphQL API globális konfigurációja.
runtime.cache Globális válasz gyorsítótárazási konfigurációja.
runtime.compression HTTP-választömörítés konfigurálása.
runtime.mcp A Model Context Protocol (MCP) globális konfigurációja.
runtime.telemetria Telemetriai, naplózási és monitorozási konfiguráció.
runtime.health Globális állapot-ellenőrzési konfiguráció.

Entitások tulajdonságai

Ingatlan Leírás
entitások A REST vagy GraphQL használatával közzétett összes entitást meghatározó objektum.
entityes.entity-name.source Az entitás adatbázis-forrásadatai.
entityes.entity-name.rest AZ entitás REST API-konfigurációja.
entityes.entity-name.graphql GraphQL API-konfiguráció az entitáshoz.
entityes.entity-name.permissions Az entitás engedélyei és hozzáférés-vezérlése.
entityes.entity-name.relationships Kapcsolatok más entitásokkal.
entityes.entity-name.cache Entitásszintű gyorsítótárazási konfiguráció.
entityes.entity-name.health Entitásszintű állapot-ellenőrzési konfiguráció.
entityes.entity-name.mcp Entitásszintű MCP-konfiguráció.
entityes.entity-name.fields Mező metaadatai, aliasai és elsődleges kulcsjelölései.
entityes.entity-name.description Ember által olvasható entitás leírása.

Séma

Szülő Ingatlan Típus Szükséges Alapértelmezett
$root $schema karakterlánc ✔️ Igen Nincs

Minden konfigurációs fájl egy $schema tulajdonsággal kezdődik, amely megadja a JSON-sémát az ellenőrzéshez.

Formátum

{
  "$schema": <string>
}

Example

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json"
}

Jótanács

A legújabb séma mindig elérhető a következő címen https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json: .

Verziókezelés

A sémafájlok meghatározott URL-címeken érhetők el, így a megfelelő verziót vagy a legújabb rendelkezésre álló sémát használhatja.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

Cserélje le VERSION-suffix a kívánt verzióra.

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

Adatforrásfájlok

Szülő Ingatlan Típus Szükséges Alapértelmezett
$root data-source-files karakterlánc-tömb ❌ Nem Nincs

A Data API Builder több konfigurációs fájlt is támogat, és az egyiket a legfelső szintű fájlkezelési runtime beállítások közé sorolja. Minden konfiguráció ugyanazzal a JSON-sémával rendelkezik, így bármely fájlban hiba nélkül engedélyezhetők runtime a beállítások. Entitások felosztása a jobb szervezet érdekében.

Egy konfigurációs fájlban tömbként hivatkozott több konfigurációs fájl diagramja.

Formátum

{
  "data-source-files": [ "<string>" ]
}

Több konfigurációs szabály

  • Minden konfigurációs fájlnak tartalmaznia kell a tulajdonságot data-source .
  • Minden konfigurációs fájlnak tartalmaznia kell a tulajdonságot entities (vagy autoentities).
  • A legfelső szintű konfigurációnak tartalmaznia kell a következőt runtime: .
  • A gyermekkonfigurációk tartalmazhatnak runtime, de a Data API Builder figyelmen kívül hagyja.
  • A gyermekkonfigurációs fájlok tartalmazhatnak saját gyermekfájlokat.
  • A konfigurációs fájlok almappákba rendezhetők.
  • Az entitásneveknek minden konfigurációs fájlban egyedinek kell lenniük.
  • A különböző konfigurációs fájlok entitásai közötti kapcsolatok nem támogatottak.

Examples

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Automatikusságok

Szülő Ingatlan Típus Szükséges Alapértelmezett
$root autoentities objektum ❌ Nem Nincs

A autoentities szakasz olyan mintaalapú szabályokat határoz meg, amelyek automatikusan elérhetővé teszik az egyező adatbázis-objektumokat DAB-entitásokként az indításkor. Az objektum minden kulcsa egy elnevezett definíció, amely mintákat, sablonokat és engedélyeket tartalmaz.

Fontos

Az autoentitások jelenleg csak az MSSQL-adatforrásokat támogatják.

Ha autoentities jelen van, a entities szakaszra már nincs szükség. A konfigurációs séma lehetővé teszi vagy autoentitiesentities (vagy mindkettőt). Ha mindkettő jelen van, a explicit módon definiált entitások elsőbbséget élveznek az azonos nevű autoentitás-egyezésekkel szemben.

Formátum

{
  "autoentities": {
    "<definition-name>": {
      "patterns": {
        "include": [ "<string>" ],
        "exclude": [ "<string>" ],
        "name": "<string>"
      },
      "template": {
        "mcp": { "dml-tools": <boolean> },
        "rest": { "enabled": <boolean> },
        "graphql": { "enabled": <boolean> },
        "health": { "enabled": <boolean> },
        "cache": {
          "enabled": <boolean>,
          "ttl-seconds": <integer>,
          "level": "<string>"
        }
      },
      "permissions": [
        {
          "role": "<string>",
          "actions": [ { "action": "<string>" } ]
        }
      ]
    }
  }
}

Tulajdonságok

Ingatlan Típus Szükséges Alapértelmezett Leírás
patterns objektum ✔️ Igen Nincs Definiálja a belefoglalási, kizárási és elnevezési szabályokat.
patterns.include karakterlánc-tömb ❌ Nem ["%.%"] A belefoglalandó objektumok MSSQL-mintái LIKE .
patterns.exclude karakterlánc-tömb ❌ Nem null Kizárandó objektumok MSSQL-mintái LIKE .
patterns.name karakterlánc ❌ Nem "{schema}_{object}" Interpolációs minta és {schema}{object}.
template objektum ❌ Nem Nincs Az összes egyeztetett entitásra alkalmazott alapértelmezett konfiguráció.
template.mcp objektum ❌ Nem Nincs McP-beállítások egyező entitásokhoz.
template.mcp.dml-tools Boolean ❌ Nem true Engedélyezze az MCP-adatmanipulációs nyelv (DML) eszközeit.
template.rest objektum ❌ Nem Nincs A egyeztetett entitások REST-beállításai.
template.rest.enabled Boolean ❌ Nem true REST-végpontok engedélyezése.
template.graphql objektum ❌ Nem Nincs A megfeleltethető entitások GraphQL-beállításai.
template.graphql.enabled Boolean ❌ Nem true Engedélyezze a GraphQL-t.
template.health objektum ❌ Nem Nincs Egyeztetett entitások állapot-ellenőrzési beállításai.
template.health.enabled Boolean ❌ Nem true Állapot-ellenőrzések engedélyezése.
template.cache objektum ❌ Nem Nincs A megfeleltethető entitások gyorsítótár-beállításai.
template.cache.enabled Boolean ❌ Nem false Válasz gyorsítótárazásának engedélyezése.
template.cache.ttl-seconds egész szám ❌ Nem null Gyorsítótár élettartam másodpercben.
template.cache.level karakterlánc ❌ Nem "L1L2" Gyorsítótárszint.
permissions tömb ❌ Nem Nincs Az összes egyező entitásra vonatkozó engedélyek.

Example

{
  "autoentities": {
    "my-def": {
      "patterns": {
        "include": [ "dbo.%" ],
        "exclude": [ "dbo.internal%" ],
        "name": "{schema}_{object}"
      },
      "template": {
        "rest": { "enabled": true },
        "graphql": { "enabled": true },
        "cache": { "enabled": true, "ttl-seconds": 30, "level": "l1l2" }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

Ezzel a konfigurációval a dbo séma összes táblája és nézete (kivéve az egyezőket dbo.internal%) automatikusan DAB-entitásként lesz közzétéve. Minden entitás neve a {schema}_{object} mintával történik (például dbo_Products), a REST és a GraphQL engedélyezve van, gyorsítótárazást használ 30 másodperces élettartammal (TTL), és hozzáférést biztosít read a anonymous szerepkörhöz.

Jótanács

A dab auto-config parancssori felületről létrehozhat autoentitásdefiníciókat, és dab auto-config-simulate megtekintheti, hogy mely objektumok egyeznek meg a módosítások véglegesítése előtt. További információ: a 2.0-s verzió újdonságai.

Azure Key Vault

Szülő Ingatlan Típus Szükséges Alapértelmezett
$root azure-key-vault objektum ❌ Nem Nincs

Konfigurálja az Azure Key Vault-integrációt a titkos kódok kezeléséhez. Ha jelen van, a endpoint tulajdonságra szükség van.

Beágyazott tulajdonságok

Szülő Ingatlan Típus Szükséges Alapértelmezett
azure-key-vault endpoint karakterlánc ✔️ Igen Nincs
azure-key-vault retry-policy objektum ❌ Nem Nincs
Szülő Ingatlan Típus Szükséges Alapértelmezett
azure-key-vault.retry-policy mode enum (fixed | exponential) ❌ Nem "exponential"
azure-key-vault.retry-policy max-count egész szám ❌ Nem 3
azure-key-vault.retry-policy delay-seconds egész szám ❌ Nem 1
azure-key-vault.retry-policy max-delay-seconds egész szám ❌ Nem 60
azure-key-vault.retry-policy network-timeout-seconds egész szám ❌ Nem 60

Az Azure Key Vaultban tárolt titkos kulcsok hivatkozásához használja a függvényt a @akv() konfigurációs értékekben. A Data API Builder ezeket a hivatkozásokat indításkor a konfigurált végpont használatával oldja fel.

Formátum

{
  "azure-key-vault": {
    "endpoint": "<string>",
    "retry-policy": {
      "mode": <"exponential"> (default) | <"fixed">,
      "max-count": <integer; default: 3>,
      "delay-seconds": <integer; default: 1>,
      "max-delay-seconds": <integer; default: 60>,
      "network-timeout-seconds": <integer; default: 60>
    }
  }
}

Example

{
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 120,
      "network-timeout-seconds": 90
    }
  },
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('sql-connection-string')"
  }
}
  • Last updated on