Referensi skema konfigurasi penyusun API Data

Penyusun API Data memerlukan setidaknya satu file konfigurasi untuk dijalankan. File berbasis JSON ini menentukan penyiapan API Anda, dari pengaturan lingkungan hingga definisi entitas. Ini dimulai dengan $schema properti, yang memungkinkan validasi skema untuk sisa file.

Properti tingkat atas

Property Description
$schema URI skema JSON untuk konfigurasi ini.
sumber data Objek yang berisi pengaturan konektivitas database.
file sumber data Array jalur file konfigurasi lainnya.
runtime Objek yang mengonfigurasi perilaku runtime.
entities Objek yang menentukan semua entitas yang diekspos melalui REST atau GraphQL.
autoentities Objek yang menentukan aturan berbasis pola yang secara otomatis mengekspos objek database yang cocok sebagai entitas (hanya MSSQL).
azure-key-vault Konfigurasi Azure Key Vault untuk manajemen rahasia.

Properti sumber data

Property Description
sumber data Objek yang berisi pengaturan konektivitas database.
data-source.database-type Jenis database yang digunakan dalam backend (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql).
data-source.connection-string String koneksi untuk jenis database yang dipilih.
sumber data.options Opsi khusus database dan pengaturan tingkat lanjut.
data-source.health Konfigurasi pemeriksaan kesehatan untuk sumber data.
file sumber data Array jalur file konfigurasi lainnya.

Properti runtime

Property Description
runtime Objek yang mengonfigurasi perilaku runtime.
runtime.pagination Pengaturan penomoran halaman untuk respons API.
runtime.rest Konfigurasi global REST API.
runtime.graphql Konfigurasi global GraphQL API.
runtime.cache Konfigurasi penembolokan respons global.
runtime.compression Konfigurasi kompresi respons HTTP.
runtime.mcp Konfigurasi global Protokol Konteks Model (MCP).
runtime.telemetri Konfigurasi telemetri, pengelogan, dan pemantauan.
runtime.health Konfigurasi pemeriksaan kesehatan global.

Properti entitas

Property Description
entities Objek yang menentukan semua entitas yang diekspos melalui REST atau GraphQL.
entities.entity-name.source Detail sumber database untuk entitas.
entities.entity-name.rest Konfigurasi REST API untuk entitas.
entities.entity-name.graphql Konfigurasi API GraphQL untuk entitas.
entities.entity-name.permissions Izin dan kontrol akses untuk entitas.
entities.entity-name.relationships Hubungan dengan entitas lain.
entities.entity-name.cache Konfigurasi penembolokan tingkat entitas.
entities.entity-name.health Konfigurasi pemeriksaan kesehatan tingkat entitas.
entities.entity-name.mcp Konfigurasi MCP tingkat entitas.
entities.entity-name.fields Metadata bidang, alias, dan sebutan kunci utama.
entities.entity-name.description Deskripsi entitas yang dapat dibaca manusia.

Schema

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

Setiap file konfigurasi dimulai dengan $schema properti, menentukan skema JSON untuk validasi.

Format

{
  "$schema": <string>
}

Example

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

Tip

Skema terbaru selalu tersedia di https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Versioning

File skema tersedia pada URL tertentu, memastikan Anda dapat menggunakan versi yang benar atau skema terbaru yang tersedia.

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

Ganti VERSION-suffix dengan versi yang Anda inginkan.

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

File sumber data

Parent Property Type Required Default
$root data-source-files larik string ❌ Tidak None

Penyusun API Data mendukung beberapa file konfigurasi, dengan satu ditunjuk sebagai pengaturan pengelolaan runtime file tingkat atas. Semua konfigurasi memiliki skema JSON yang sama, memungkinkan runtime pengaturan di setiap atau setiap file tanpa kesalahan. Membagi entitas untuk organisasi yang lebih baik.

Diagram beberapa file konfigurasi yang dirujuk sebagai array dalam satu file konfigurasi.

Format

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

Beberapa aturan konfigurasi

  • Setiap file konfigurasi harus menyertakan properti data-source.
  • Setiap file konfigurasi harus menyertakan entities properti (atau autoentities).
  • Konfigurasi tingkat atas harus mencakup runtime.
  • Konfigurasi anak dapat mencakup runtime, tetapi pembuat API Data mengabaikannya.
  • File konfigurasi anak dapat menyertakan file anak mereka sendiri.
  • File konfigurasi dapat diatur ke dalam subfolder.
  • Nama entitas harus unik di semua file konfigurasi.
  • Hubungan antar entitas dalam file konfigurasi yang berbeda tidak didukung.

Examples

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

Entitas otomatis

Parent Property Type Required Default
$root autoentities objek ❌ Tidak None

Bagian menentukan autoentities aturan berbasis pola yang secara otomatis mengekspos objek database yang cocok sebagai entitas DAB saat startup. Setiap kunci dalam objek adalah definisi bernama yang berisi pola, templat, dan izin.

Penting

Autoentities saat ini hanya mendukung sumber data MSSQL .

Saat autoentities ada, bagian entities tidak lagi diperlukan. Skema konfigurasi memungkinkan atau autoentitiesentities (atau keduanya). Jika keduanya ada, entitas yang ditentukan secara eksplisit lebih diutamakan daripada kecocokan autoentities dengan nama yang sama.

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

Karakteristik

Property Type Required Default Description
patterns objek ✔️ Ya None Mendefinisikan termasuk, mengecualikan, dan mencantumkan aturan penamaan.
patterns.include larik string ❌ Tidak ["%.%"] Pola MSSQL LIKE untuk disertakan objek.
patterns.exclude larik string ❌ Tidak null Pola MSSQL LIKE untuk objek yang akan dikecualikan.
patterns.name string ❌ Tidak "{schema}_{object}" Pola interpolasi menggunakan {schema} dan {object}.
template objek ❌ Tidak None Konfigurasi default diterapkan ke semua entitas yang cocok.
template.mcp objek ❌ Tidak None Pengaturan MCP untuk entitas yang cocok.
template.mcp.dml-tools Boolean ❌ Tidak true Aktifkan alat bahasa manipulasi data (DML) MCP.
template.rest objek ❌ Tidak None Pengaturan REST untuk entitas yang cocok.
template.rest.enabled Boolean ❌ Tidak true Aktifkan titik akhir REST.
template.graphql objek ❌ Tidak None Pengaturan GraphQL untuk entitas yang cocok.
template.graphql.enabled Boolean ❌ Tidak true Aktifkan GraphQL.
template.health objek ❌ Tidak None Pengaturan pemeriksaan kesehatan untuk entitas yang cocok.
template.health.enabled Boolean ❌ Tidak true Aktifkan pemeriksaan kesehatan.
template.cache objek ❌ Tidak None Pengaturan cache untuk entitas yang cocok.
template.cache.enabled Boolean ❌ Tidak false Aktifkan penembolokan respons.
template.cache.ttl-seconds bilangan bulat ❌ Tidak null Cache time-to-live dalam hitungan detik.
template.cache.level string ❌ Tidak "L1L2" Tingkat cache.
permissions array ❌ Tidak None Izin diterapkan ke semua entitas yang cocok.

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

Dengan konfigurasi ini, setiap tabel dan tampilan dalam dbo skema (kecuali yang cocok dbo.internal%) secara otomatis diekspos sebagai entitas DAB. Setiap entitas diberi nama menggunakan {schema}_{object} pola (misalnya, dbo_Products), mengaktifkan REST dan GraphQL, menggunakan penembolokan dengan time-to-live (TTL) 30 detik, dan memberikan read akses ke peran tersebut anonymous .

Tip

Gunakan dab auto-config untuk membuat definisi autoentities dari CLI, dan dab auto-config-simulate untuk mempratinjau objek mana yang cocok sebelum melakukan perubahan. Untuk informasi selengkapnya, lihat apa yang baru di versi 2.0.

Azure Key Vault

Parent Property Type Required Default
$root azure-key-vault objek ❌ Tidak None

Mengonfigurasi integrasi Azure Key Vault untuk mengelola rahasia. Saat ada, endpoint properti diperlukan.

Properti berlapis

Parent Property Type Required Default
azure-key-vault endpoint string ✔️ Ya None
azure-key-vault retry-policy objek ❌ Tidak None
Parent Property Type Required Default
azure-key-vault.retry-policy mode enum (fixed | exponential) ❌ Tidak "exponential"
azure-key-vault.retry-policy max-count bilangan bulat ❌ Tidak 3
azure-key-vault.retry-policy delay-seconds bilangan bulat ❌ Tidak 1
azure-key-vault.retry-policy max-delay-seconds bilangan bulat ❌ Tidak 60
azure-key-vault.retry-policy network-timeout-seconds bilangan bulat ❌ Tidak 60

Untuk mereferensikan rahasia yang disimpan di Azure Key Vault, gunakan @akv() fungsi dalam nilai konfigurasi Anda. Penyusun API Data menyelesaikan referensi ini saat startup menggunakan titik akhir yang dikonfigurasi.

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