Veri API'si oluşturucu yapılandırma şeması başvurusu

Veri API'sini oluşturucunun çalışması için en az bir yapılandırma dosyası gerekir. Bu JSON tabanlı dosya, ortam ayarlarından varlık tanımlarına kadar API kurulumunuzu tanımlar. Dosyanın geri kalanı için şema doğrulamasını etkinleştiren bir $schema özellik ile başlar.

Üst düzey özellikler

Property Description
$schema Bu yapılandırma için JSON şemasının URI'sini.
veri kaynağı Veritabanı bağlantı ayarlarını içeren nesne.
veri kaynağı dosyaları Diğer yapılandırma dosyası yollarının dizisi.
runtime Çalışma zamanı davranışlarını yapılandıran nesne.
entities REST veya GraphQL aracılığıyla kullanıma sunulan tüm varlıkları tanımlayan nesne.
otomatik varlıklar Eşleşen veritabanı nesnelerini otomatik olarak varlık olarak kullanıma sunan desen tabanlı kuralları tanımlayan nesne (yalnızca MSSQL).
azure-key-vault Gizli dizi yönetimi için Azure Key Vault yapılandırması.

Veri kaynağı özellikleri

Property Description
veri kaynağı Veritabanı bağlantı ayarlarını içeren nesne.
data-source.database-type Arka uçta kullanılan veritabanı türü (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql).
data-source.connection-string Seçili veritabanı türü için bağlantı dizesi.
data-source.options Veritabanına özgü seçenekler ve gelişmiş ayarlar.
data-source.health Veri kaynağı için sistem durumu denetimi yapılandırması.
veri kaynağı dosyaları Diğer yapılandırma dosyası yollarının dizisi.

Çalışma zamanı özellikleri

Property Description
runtime Çalışma zamanı davranışlarını yapılandıran nesne.
runtime.pagination API yanıtları için sayfalandırma ayarları.
runtime.rest REST API genel yapılandırması.
runtime.graphql GraphQL API genel yapılandırması.
runtime.cache Genel yanıt önbelleğe alma yapılandırması.
runtime.compression HTTP yanıt sıkıştırma yapılandırması.
runtime.mcp Model Bağlam Protokolü (MCP) genel yapılandırması.
runtime.telemetry Telemetri, günlüğe kaydetme ve izleme yapılandırması.
runtime.health Genel sistem durumu denetimi yapılandırması.

Varlık özellikleri

Property Description
entities REST veya GraphQL aracılığıyla kullanıma sunulan tüm varlıkları tanımlayan nesne.
entities.entity-name.source Varlık için veritabanı kaynağı ayrıntıları.
entities.entity-name.rest Varlık için REST API yapılandırması.
entities.entity-name.graphql Varlık için GraphQL API yapılandırması.
entities.entity-name.permissions Varlık için izinler ve erişim denetimi.
entities.entity-name.relationships Diğer varlıklarla ilişkiler.
entities.entity-name.cache Varlık düzeyinde önbelleğe alma yapılandırması.
entities.entity-name.health Varlık düzeyinde sistem durumu denetimi yapılandırması.
entities.entity-name.mcp Varlık düzeyinde MCP yapılandırması.
entities.entity-name.fields Alan meta verileri, diğer adlar ve birincil anahtar atamaları.
entities.entity-name.description İnsan tarafından okunabilen varlık açıklaması.

Schema

Parent Property Type Required Default
$root $schema string ✔️ Evet None

Her yapılandırma dosyası bir $schema özellik ile başlar ve doğrulama için JSON şemasını belirtir.

Format

{
  "$schema": <string>
}

Example

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

Tip

En son şema her zaman adresinde https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.jsonkullanılabilir.

Versioning

Şema dosyaları, doğru sürümü veya en son kullanılabilir şemayı kullanabilmenizi sağlayan belirli URL'lerde kullanılabilir.

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

VERSION-suffix istediğiniz sürümle değiştirin.

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

Veri kaynağı dosyaları

Parent Property Type Required Default
$root data-source-files dize dizisi ❌ Hayır None

Veri API oluşturucusu, birden çok yapılandırma dosyasını destekler ve bunlardan biri en üst düzey dosya yönetim runtime ayarları olarak belirlenir. Tüm yapılandırmalar aynı JSON şemasını paylaşır ve runtime hata olmadan herhangi bir dosyada veya her dosyada ayarlara izin verir. Daha iyi bir kuruluş için varlıkları bölün.

Tek bir yapılandırma dosyasında dizi olarak başvurulan birden çok yapılandırma dosyasının diyagramı.

Format

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

Birden çok yapılandırma kuralı

  • Her yapılandırma dosyası data-source özelliğini içermelidir.
  • Her yapılandırma dosyası (veya autoentities) özelliğini içermelidirentities.
  • Üst düzey yapılandırma içermelidir runtime.
  • Alt yapılandırmalar içerebilir runtime, ancak Veri API oluşturucusu bunu yoksayar.
  • Alt yapılandırma dosyaları kendi alt dosyalarını içerebilir.
  • Yapılandırma dosyaları alt klasörler halinde düzenlenebilir.
  • Varlık adları tüm yapılandırma dosyalarında benzersiz olmalıdır.
  • Farklı yapılandırma dosyalarındaki varlıklar arasındaki ilişkiler desteklenmez.

Examples

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

Otomatik varlıklar

Parent Property Type Required Default
$root autoentities nesne ❌ Hayır None

bölümü, autoentities başlangıçta eşleşen veritabanı nesnelerini otomatik olarak DAB varlıkları olarak kullanıma sunan desen tabanlı kuralları tanımlar. Nesnedeki her anahtar desenler, şablon ve izinler içeren adlandırılmış bir tanımdır.

Önemli

Otomatik varlıklar şu anda yalnızca MSSQL veri kaynaklarını desteklemektedir.

Mevcut olduğunda autoentities , entities bölüm artık gerekli değildir. Yapılandırma şeması veya autoentities (ya entities da her ikisi) izin verir. Her ikisi de varsa, açıkça tanımlanmış varlıklar aynı ada sahip otomatik varlıklar eşleşmelerine göre önceliklidir.

Format

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

Özellikler

Property Type Required Default Description
patterns nesne ✔️ Evet None Ekleme, dışlama ve adlandırma kurallarını tanımlar.
patterns.include dize dizisi ❌ Hayır ["%.%"] Eklenecek nesneler için MSSQL LIKE desenleri.
patterns.exclude dize dizisi ❌ Hayır null Dışlanması gereken nesneler için MSSQL LIKE desenleri.
patterns.name string ❌ Hayır "{schema}_{object}" ve {object}kullanarak {schema} ilişkilendirme düzeni.
template nesne ❌ Hayır None Tüm eşleşen varlıklara uygulanan varsayılan yapılandırma.
template.mcp nesne ❌ Hayır None Eşleşen varlıklar için MCP ayarları.
template.mcp.dml-tools Boolean ❌ Hayır true MCP veri işleme dili (DML) araçlarını etkinleştirin.
template.rest nesne ❌ Hayır None Eşleşen varlıklar için REST ayarları.
template.rest.enabled Boolean ❌ Hayır true REST uç noktalarını etkinleştirin.
template.graphql nesne ❌ Hayır None Eşleşen varlıklar için GraphQL ayarları.
template.graphql.enabled Boolean ❌ Hayır true GraphQL'i etkinleştirin.
template.health nesne ❌ Hayır None Eşleşen varlıklar için sistem durumu denetimi ayarları.
template.health.enabled Boolean ❌ Hayır true Sağlık kontrollerini etkinleştirin.
template.cache nesne ❌ Hayır None Eşleşen varlıklar için önbellek ayarları.
template.cache.enabled Boolean ❌ Hayır false Yanıt önbelleğe almayı etkinleştirin.
template.cache.ttl-seconds tamsayı ❌ Hayır null Yaşam süresini saniyeler içinde önbelleğe alın.
template.cache.level string ❌ Hayır "L1L2" Önbellek düzeyi.
permissions array ❌ Hayır None Eşleşen tüm varlıklara uygulanan izinler.

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

Bu yapılandırmayla, şemadaki dbo her tablo ve görünüm (eşleşenler dbo.internal%hariç) otomatik olarak bir DAB varlığı olarak kullanıma sunulur. Her varlık deseni kullanılarak {schema}_{object} adlandırılır (örneğin, dbo_Products), REST ve GraphQL etkindir, 30 saniyelik yaşam süresi (TTL) ile önbelleğe almayı kullanır ve role erişim anonymous verirread.

Tip

CLI'dan otomatik varlık tanımları oluşturmak ve dab auto-config-simulate değişiklikleri işlemeden önce hangi nesnelerin eşleşip eşleşmediği önizlemek için kullanındab auto-config. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

Azure Key Vault

Parent Property Type Required Default
$root azure-key-vault nesne ❌ Hayır None

Gizli dizileri yönetmek için Azure Key Vault tümleştirmesini yapılandırılır. Mevcut olduğunda özelliği endpoint gereklidir.

İç içe özellikler

Parent Property Type Required Default
azure-key-vault endpoint string ✔️ Evet None
azure-key-vault retry-policy nesne ❌ Hayır None
Parent Property Type Required Default
azure-key-vault.retry-policy mode sabit listesi (fixed | exponential) ❌ Hayır "exponential"
azure-key-vault.retry-policy max-count tamsayı ❌ Hayır 3
azure-key-vault.retry-policy delay-seconds tamsayı ❌ Hayır 1
azure-key-vault.retry-policy max-delay-seconds tamsayı ❌ Hayır 60
azure-key-vault.retry-policy network-timeout-seconds tamsayı ❌ Hayır 60

Azure Key Vault'ta depolanan gizli dizilere başvurmak için yapılandırma değerlerinizde işlevini kullanın @akv() . Veri API'si oluşturucusu, yapılandırılan uç noktayı kullanarak başlangıçta bu başvuruları çözümler.

Format

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