Entities

Pengaturan konfigurasi untuk entitas database.

Health

Property	Description
entities.entity-name.health.enabled	Mengaktifkan pemeriksaan kesehatan untuk entitas (titik akhir REST dan GraphQL)
entities.entity-name.health.first	Jumlah baris yang dikembalikan dalam kueri pemeriksaan kesehatan (rentang: 1-500)
entities.entity-name.health.threshold-ms	Durasi maksimum dalam milidetik untuk kueri pemeriksaan kesehatan (min: Satu)

Description

Property	Description
entities.entity-name.description	Deskripsi entitas yang dapat dibaca manusia

Fields

Property	Description
entities.entity-name.fields[].name	Nama bidang database (diperlukan)
entities.entity-name.fields[].alias	Nama yang diekspos API (menggantikan pemetaan)
entities.entity-name.fields[].description	Deskripsi bidang yang dapat dibaca manusia
entities.entity-name.fields[].primary-key	Menandai bidang sebagai kunci primer (menggantikan bidang kunci)

Source

Property	Description
entities.entity-name.source.type	Jenis objek: table, view, atau stored-procedure
entities.entity-name.source.object	Nama objek database
entities.entity-name.source.object-description	Deskripsi objek database yang dapat dibaca manusia
entities.entity-name.source.parameters	Parameter untuk prosedur atau fungsi tersimpan
entities.entity-name.source.key-fields	Daftar bidang kunci utama untuk tampilan (tidak digunakan lagi)
entities.entity-name.mappings	Memetakan nama bidang API ke kolom database (tidak digunakan lagi)

REST

Property	Description
entities.entity-name.rest.enabled	Mengaktifkan REST untuk entitas ini
entities.entity-name.rest.path	Rute kustom untuk titik akhir REST
entities.entity-name.rest.methods	Metode REST yang diizinkan: get, post, put, patch, delete

GraphQL

Property	Description
entities.entity-name.graphql.type	Ketik nama atau objek dengan singular dan plural
entities.entity-name.graphql.operation	Jenis operasi: query atau mutation
entities.entity-name.graphql.enabled	Mengaktifkan GraphQL untuk entitas ini

Permissions

Property	Description
entities.entity-name.permissions[].role	String nama peran
entities.entity-name.permissions[].actions	Satu atau beberapa dari: create, read, update, delete, execute

Relationships

Property	Description
entities.entity-name.relationships.relationship-name.cardinality	one atau many
entities.entity-name.relationships.relationship-name.target.entity	Nama entitas target
entities.entity-name.relationships.relationship-name.source.fields	Bidang dari entitas ini yang digunakan dalam hubungan
entities.entity-name.relationships.relationship-name.target.fields	Bidang dari entitas target
entities.entity-name.relationships.relationship-name.linking.object	Gabungkan objek yang digunakan untuk hubungan banyak-ke-banyak
entities.entity-name.relationships.relationship-name.linking.source.fields	Bidang dari entitas sumber yang digunakan dalam gabungan
entities.entity-name.relationships.relationship-name.linking.target.fields	Bidang dari entitas target yang digunakan dalam gabungan

Cache

Property	Description
entities.entity-name.cache.enabled	Mengaktifkan penembolokan respons untuk entitas
entities.entity-name.cache.ttl-seconds	Cache time-to-live dalam hitungan detik
entities.entity-name.cache.level	Tingkat cache: L1 (hanya dalam memori) atau L1L2 (dalam memori + terdistribusi)

MCP

Property	Description
entities.entity-name.mcp	Objek yang mengontrol partisipasi Model Context Protocol (MCP) untuk entitas
entities.entity-name.mcp.dml-tools	Mengaktifkan atau menonaktifkan alat bahasa manipulasi data (DML) untuk entitas
entities.entity-name.mcp.custom-tool	Mendaftarkan prosedur tersimpan sebagai alat MCP bernama (hanya entitas prosedur tersimpan)

Gambaran umum format

{
  "entities": {
    "{entity-name}": {
      "description": <string>,
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      },
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ],
      "mappings": { // DEPRECATED: use fields[].alias
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": <string>,
          "source.fields": [<string>],
          "target.fields": [<string>],
          "linking.object": <string>,
          "linking.source.fields": [<string>],
          "linking.target.fields": [<string>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ],
      "cache": {
        "enabled": <boolean>,
        "ttl-seconds": <integer>,
        "level": "L1" | "L1L2" // default: "L1L2"
      },
      "mcp": {
        "dml-tools": <boolean>,       // default: true
        "custom-tool": <boolean>      // stored-procedure only; default: false
      }
    }
  }
}

Sumber (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	source	objek	✔️ Ya	None

Detail sumber database entitas.

Properti berlapis

Parent	Property	Type	Required	Default
entities.{entity-name}.source	object	string	✔️ Ya	None
entities.{entity-name}.source	object-description	string	❌ Tidak	None
entities.{entity-name}.source	type	enum (table, view, stored-procedure)	✔️ Ya	None
entities.{entity-name}.source	key-fields	larik string	❌ Tidak*	None
entities.{entity-name}.source	parameters	array atau objek	❌ Tidak**	None

* key-fields hanya diperlukan ketika type adalah view dan fields array tidak digunakan. Nilai mewakili kunci primer.

Peringatan

Properti key-fields tidak digunakan lagi dalam DAB 2.0. fields Gunakan array dengan primary-key: true sebagai gantinya. Skema memberlakukan itu fields dan key-fields tidak dapat hidup berdampingan pada entitas yang sama.

** parameters hanya diperlukan ketika type adalah stored-procedure dan hanya untuk parameter dengan nilai default. Jenis data parameter disimpulkan. Parameter tanpa default dapat dihilangkan.

object-description adalah deskripsi opsional yang dapat dibaca manusia dari objek database yang mendasar. Nilai ini muncul selama penemuan alat MCP, membantu agen AI memahami tujuan entitas.

Tip

Jika objek milik skema dbo, menentukan skema bersifat opsional. Selain itu, tanda kurung siku di sekitar nama objek (misalnya, dbo.Users vs. [dbo].[Users]) dapat digunakan jika diperlukan.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      }
    }
  }
}

Format array parameter

Dalam pratinjau DAB 2.0, parameters mendukung format array terstruktur dengan metadata yang lebih kaya. Setiap parameter adalah objek dengan properti berikut:

Property	Type	Required	Description
name	string	✔️ Ya	Nama parameter (tanpa awalan @ )
required	boolean	❌ Tidak	Apakah parameter diperlukan (true) atau opsional (false)
default	apa pun	❌ Tidak	Nilai default yang digunakan saat parameter tidak disediakan
description	string	❌ Tidak	Deskripsi parameter yang dapat dibaca manusia

Contoh (format array—lebih disukai)

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "default": null,
            "description": "The unique identifier of the book"
          }
        ]
      }
    }
  }
}

Peringatan

Format kamus untuk parameters (misalnya, { "id": 0 }) tidak digunakan lagi dalam DAB 2.0. Gunakan format array sebelumnya. Format lama masih diterima untuk kompatibilitas mundur tetapi akan dihapus dalam rilis mendatang.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Izin (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.permissions	role	string	✔️ Ya	None

Menentukan nama peran yang izinnya berlaku. Gunakan peran sistem (Anonymous, Authenticated) atau peran kustom yang ditentukan dalam penyedia identitas Anda.

Tip

Untuk informasi terperinci tentang evaluasi peran, peran sistem, dan X-MS-API-ROLE header, lihat Gambaran umum otorisasi.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"Anonymous" | "Authenticated" | "custom-role">,
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

Pewarisan peran

DAB 2.0 memperkenalkan pewarisan peran untuk izin entitas. Saat peran tidak dikonfigurasi secara eksplisit untuk entitas, peran tersebut mewarisi izin dari peran yang lebih luas menggunakan rantai berikut:

named-role → authenticated → anonymous

• Jika authenticated tidak dikonfigurasi untuk entitas, entitas tersebut mewarisi dari anonymous.
• Jika peran bernama tidak dikonfigurasi, peran tersebut mewarisi dari authenticated, atau dari anonymous jika authenticated juga tidak ada.

Ini berarti Anda dapat menentukan izin sekali aktif anonymous dan setiap peran yang lebih luas mendapatkan akses yang sama secara otomatis, tanpa duplikasi yang diperlukan.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Example

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Dengan konfigurasi ini, anonymous, authenticated, dan peran bernama yang tidak dikonfigurasi semuanya dapat membaca Book. Gunakan dab configure --show-effective-permissions untuk melihat izin yang diselesaikan untuk setiap entitas setelah pewarisan diterapkan.

Tindakan (entitas nama entitas Izin string-array)

Parent	Property	Type	Required	Default
entities.permissions	actions	oneOf [string, array]	✔️ Ya	None

Array string yang merinci operasi apa yang diizinkan untuk peran terkait.

Action	Operasi SQL
*	Semua tindakan
create	Sisipkan satu atau beberapa* baris
read	Pilih satu atau beberapa baris
update	Mengubah satu atau beberapa* baris
delete	Menghapus satu atau beberapa* baris
execute	Menjalankan prosedur tersimpan

* Beberapa operasi saat ini hanya didukung di GraphQL.

Note

Untuk prosedur tersimpan, tindakan kartubebas (*) hanya meluas ke tindakan execute. Untuk tabel dan tampilan, tabel diperluas ke create, read, update, dan delete.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

Format alternatif (hanya string, saat type=stored-procedure)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Tindakan (entitas nama entitas Izin array objek)

Parent	Property	Type	Required	Default
entities.{entity-name}.permissions	actions	larik string	✔️ Ya	None

Array objek yang merinci operasi apa yang diizinkan untuk peran terkait.

Note

Untuk prosedur tersimpan, tindakan kartubebas (*) diperluas hanya ke execute. Untuk tabel/tampilan, tabel diperluas ke create, read, update, dan delete.

Properti berlapis

Parent	Property	Type	Required	Default
entities.{entity-name}.permissions.actions[]	action	string	✔️ Ya	None
entities.{entity-name}.permissions.actions[]	fields	objek	❌ Tidak	None
entities.{entity-name}.permissions.actions[]	policy	objek	❌ Tidak	None
entities.{entity-name}.permissions.actions[].policy	database	string	✔️ Ya	None

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }

Example

Ini memberikan read izin kepada auditor entitas User , dengan pembatasan bidang dan kebijakan.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Catatan kebijakan

Kebijakan database memfilter hasil kueri menggunakan predikat gaya OData. Gunakan @item.<field> untuk mereferensikan bidang entitas dan @claims.<type> untuk menyuntikkan klaim pengguna yang diautentikasi.

Aspek	Detail lebih lanjut
Syntax	Predikat OData (eq, , ne, andor, gt, lt)
Referensi bidang	@item.<field> (gunakan nama yang dipetakan jika berlaku)
Referensi klaim	@claims.<claimType>
Tindakan yang didukung	read update delete
Tidak didukung	create, execute

Tip

Untuk panduan komprehensif tentang kebijakan database, termasuk penggantian klaim dan pemecahan masalah, lihat Mengonfigurasi kebijakan database.

Jenis (entitas nama entitas GraphQL)

Parent	Property	Type	Required	Default
entities.{entity-name}.graphql	type	objek	❌ Tidak	{entity-name}

Mengatur konvensi penamaan untuk entitas dalam skema GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

Properti berlapis

Parent	Property	Required	Type	Default
entities.{entity-name}.graphql.type	singular	✔️ Ya*	string	None
entities.{entity-name}.graphql.type	plural	❌ Tidak	string	N/A (default ke nilai tunggal)

* singular diperlukan ketika type ditentukan sebagai objek. Ketika type adalah string biasa, string tersebut digunakan sebagai nama tunggal.

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Kueri GraphQL

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

Respons GraphQL

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Operasi (entitas nama entitas GraphQL)

Parent	Property	Type	Required	Default
entities.{entity-name}.graphql	operation	string enum	❌ Tidak	mutation

Menunjuk stored-procedure apakah operasi muncul di bawah Query atau Mutation.

Note

Ketika {entity-name}.type diatur ke stored-procedure, jenis executeXXX GraphQL baru dibuat secara otomatis. Properti ini operation mengontrol tempat jenis ini ditempatkan dalam skema GraphQL. Tidak ada dampak fungsional, hanya kebersihan skema.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Contoh: operasi

Kapan operation diatur ke query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Kapan operation diatur ke mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Diaktifkan (entitas nama entitas GraphQL)

Parent	Property	Type	Required	Default
entities.{entity-name}.graphql	enabled	boolean	❌ Tidak	True

Memungkinkan pengembang secara selektif menyertakan entitas dalam skema GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}.rest	enabled	boolean	❌ Tidak	True
entities.rest	path	string	❌ Tidak	/{entity-name}
entities.{entity-name}.rest	methods	larik string	❌ Tidak*	POST

* Properti methods hanya untuk stored-procedure titik akhir.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Format

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "{entity-name}">
      }
    }
  }
}

Deskripsi (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	description	string	❌ Tidak	None

Deskripsi entitas yang dapat dibaca manusia opsional. Nilai ini muncul dalam dokumentasi API yang dihasilkan dan sebagai komentar dalam skema GraphQL.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Format

{
  "entities": {
    "{entity-name}": {
      "description": "<string>"
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "description": "Represents a book in the catalog with title, author, and pricing information.",
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Bidang (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	fields	array	❌ Tidak	None

Menentukan metadata untuk bidang database individual, termasuk alias, deskripsi, dan penuntasan kunci utama. fields Array menggantikan (mappingsmelalui alias properti) dan source.key-fields (melalui primary-key properti) dalam satu struktur terpadu.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Properti berlapis

Parent	Property	Type	Required	Default
entities.{entity-name}.fields[]	name	string	✔️ Ya	None
entities.{entity-name}.fields[]	alias	string	❌ Tidak	None
entities.{entity-name}.fields[]	description	string	❌ Tidak	None
entities.{entity-name}.fields[]	primary-key	boolean	❌ Tidak	false

Format

{
  "entities": {
    "{entity-name}": {
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "fields": [
        {
          "name": "id",
          "description": "Unique book identifier",
          "primary-key": true
        },
        {
          "name": "sku_title",
          "alias": "title",
          "description": "The display title of the book"
        },
        {
          "name": "sku_status",
          "alias": "status"
        }
      ]
    }
  }
}

Dalam contoh ini, id ditetapkan sebagai kunci primer (menggantikan kebutuhan untuk source.key-fields), sementara sku_title dan sku_status diberi alias sebagai title dan status (menggantikan kebutuhan untuk mappings).

Important

Skema memberlakukan yang fields tidak dapat hidup berdampingan dengan mappings atau source.key-fields pada entitas yang sama. Migrasikan ke fields dan hapus properti yang tidak digunakan lagi.

Pemetaan (entitas nama entitas)

Peringatan

Properti mappings tidak digunakan lagi dalam DAB 2.0. fields Gunakan array dengan properti sebagai gantinyaalias. Skema memberlakukan itu fields dan mappings tidak dapat hidup berdampingan pada entitas yang sama.

Parent	Property	Type	Required	Default
entities.{entity-name}	mappings	objek	❌ Tidak	None

Mengaktifkan alias kustom, atau nama yang diekspos, untuk bidang objek database.

Important

Untuk entitas dengan GraphQL diaktifkan, nama yang diekspos yang dikonfigurasi harus memenuhi persyaratan nama GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Examples

Tabel Database

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

{
  "entities": {
    "Books": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Cache (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	cache	objek	❌ Tidak	None

Mengaktifkan dan mengonfigurasi penembolokan untuk entitas.

Properti berlapis

Parent	Property	Type	Required	Default
entities.{entity-name}.cache	enabled	boolean	❌ Tidak	False
entities.{entity-name}.cache	ttl-seconds	integer	❌ Tidak	-
entities.{entity-name}.cache	level	enum (L1 | L1L2)	❌ Tidak	L1L2

Format

{
  "entities": {
    "{entity-name}": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>,
        "level": <"L1" | "L1L2"> (default: "L1L2")
      }
    }
  }
}

Properti level mengontrol tingkat cache mana yang digunakan:

Nilai	Description
L1	Hanya cache dalam memori. Tercepat, tetapi tidak dibagikan di seluruh instans.
L1L2	Cache dalam memori ditambah cache terdistribusi (Redis). Dibagikan di seluruh instans yang diskalakan. Default.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Note

Ketika tidak ditentukan, ttl-seconds mewarisi nilai global yang ditetapkan di bawah runtime.cache.

Example

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30,
        "level": "L1"
      }
    }
  }
}

Hubungan (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	relationships	objek	❌ Tidak	None

Mengonfigurasi bagaimana entitas GraphQL terkait dengan entitas lain yang terekspos. Untuk informasi selengkapnya, lihat perincian hubungan penyusun API Data .

Note

Properti untuk setiap hubungan harus unik di semua hubungan untuk entitas tersebut relationship-name .

Properti berlapis

Properti ini digunakan dalam kombinasi yang berbeda tergantung pada kardinalitas hubungan.

Parent	Property	Type	Required	Default
entities.{entity-name}.relationships	cardinality	string	✔️ Ya	None
entities.{entity-name}.relationships	target.entity	string	✔️ Ya	None
entities.{entity-name}.relationships	target.fields	larik string	❌ Tidak	None
entities.{entity-name}.relationships	source.fields	larik string	❌ Tidak	None
entities.{entity-name}.relationships	linking.object	string	❌ Tidak	None
entities.{entity-name}.relationships	linking.source.fields	larik string	❌ Tidak	None
entities.{entity-name}.relationships	linking.target.fields	larik string	❌ Tidak	None

Format

{
  "entities": {
    "{entity-name}": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Relationship	Cardinality	Example
one-to-many	many	Satu entitas kategori dapat berhubungan dengan banyak entitas todo
many-to-one	one	Banyak entitas todo dapat berhubungan dengan satu entitas kategori
many-to-many	many	Satu entitas todo dapat berhubungan dengan banyak entitas pengguna, dan satu entitas pengguna dapat berhubungan dengan banyak entitas todo

Contoh: Kardinalitas satu-ke-satu

Masing-masing Profile terkait dengan tepat satu User, dan masing-masing User memiliki tepat satu terkait Profile.

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

Skema GraphQL

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Contoh: Kardinalitas satu ke banyak

Dapat Category memiliki satu atau beberapa entitas terkait Book , sementara masing-masing Book dapat memiliki satu entitas terkait Category.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Skema GraphQL

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Baris perintah

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

Contoh: Kardinalitas banyak ke satu

Banyak Book entitas dapat memiliki satu terkait Category, sementara dapat Category memiliki satu atau beberapa entri terkait Book .

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Skema GraphQL

type Book
{
  id: Int!
  ...
  category: Category
}

Baris perintah

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

Contoh: Kardinalitas banyak ke banyak

Banyak Book entitas dapat memiliki banyak entitas terkait Author , sementara banyak Author entitas dapat memiliki banyak entri terkait Book .

Note

Hubungan ini dimungkinkan dengan tabel ketiga, dbo.books_authors, yang kita sebut sebagai objek penautan.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

Skema GraphQL

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Baris perintah

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Kesehatan (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	health	objek	❌ Tidak	None

Mengaktifkan dan mengonfigurasi pemeriksaan kesehatan untuk entitas.

Properti berlapis

Parent	Property	Type	Required	Default
entities.{entity-name}.health	enabled	boolean	❌ Tidak	true
entities.{entity-name}.health	first	integer	❌ Tidak	100
entities.{entity-name}.health	threshold-ms	integer	❌ Tidak	1000

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Note

Nilai first harus kurang dari atau sama dengan runtime.pagination.max-page-size pengaturan. Nilai yang lebih kecil membantu pemeriksaan kesehatan selesai lebih cepat.

Important

Prosedur tersimpan secara otomatis dikecualikan dari pemeriksaan kesehatan entitas karena memerlukan parameter dan mungkin tidak deterministik.

MCP (entitas nama entitas)

Parent	Property	Type	Required	Default
entities.{entity-name}	mcp	objek	❌ Tidak	diaktifkan secara default saat dihilangkan

Mengontrol partisipasi MCP untuk entitas. Ketika MCP diaktifkan secara global, entitas berpartisipasi secara default. Gunakan properti ini untuk memilih keluar atau mengaktifkan alat MCP kustom untuk entitas prosedur tersimpan.

Note

Fungsionalitas Pembuat API Data 2.0 yang dijelaskan di bagian ini saat ini dalam pratinjau dan mungkin berubah sebelum ketersediaan umum. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Format objek

Gunakan format objek untuk kontrol terperinci:

Parent	Property	Type	Required	Default
entities.{entity-name}.mcp	dml-tools	boolean	❌ Tidak	true
entities.{entity-name}.mcp	custom-tool	boolean	❌ Tidak	false

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

Alat kustom (hanya prosedur tersimpan)

Untuk entitas prosedur tersimpan, atur custom-tool ke untuk true mendaftarkan prosedur sebagai alat MCP bernama:

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Important

Properti custom-tool hanya berlaku untuk entitas prosedur tersimpan. Mengaturnya pada tabel atau melihat entitas menghasilkan kesalahan konfigurasi.

Contoh CLI

dab add Book --source books --permissions "anonymous:*" --mcp.dml-tools true

dab add GetBookById --source dbo.get_book_by_id --source.type stored-procedure --permissions "anonymous:execute" --mcp.custom-tool true