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: 1)

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.parameters`	Parameter untuk prosedur atau fungsi tersimpan
`entities.entity-name.source.key-fields`	Daftar bidang kunci primer untuk tampilan
`entities.entity-name.mappings`	Memetakan nama bidang API ke kolom database

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

Gambaran umum format

{
  "entities": {
    "{entity-name}": {
      "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>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // primary keys for the view
        "parameters": { // only for stored-procedure
          "<parameter-name>": <default-value>,
          "<parameter-name>": <default-value>
        }
      },
      "mappings": {
        "<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>
          }
        }
      ]
    }
  }
}

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`	`type`	enum (`table`, `view`, `stored-procedure`)	✔️ Ya	None
`entities.{entity-name}.source`	`key-fields`	larik string	✔️ Ya*	None
`entities.{entity-name}.source`	`parameters`	objek	✔️ Ya**	None

key-fields hanya diperlukan ketika type adalah view. Nilai mewakili kunci primer.

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

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>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for option stored-procedure parameters
          "<parameter-name-1>": <default-value>
          "<parameter-name-2>": <default-value>
        }
      }
    }
  }
}

Izin (entitas nama entitas)

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

String yang menentukan nama peran yang diterapkan izin.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

Contoh ini mendefinisikan peran custom-role hanya read dengan izin pada User entitas.

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

Contoh penggunaan

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");
// To read the response content:
// var content = await response.Content.ReadAsStringAsync();

const response = await fetch('https://localhost:5001/api/User', {
  headers: {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});
// To read the response body as JSON:
// const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
# To print the response JSON:
print(response.json())

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 mendukung operator OData seperti eq.
Kebijakan mendukung predikat campuran menggunakan and dan or.
Hanya didukung untuk tindakan: create, read, update, dan delete. (Tidak execute)
Kebijakan memfilter hasil tetapi tidak mencegah eksekusi kueri dalam database.
Bidang harus menggunakan alias bidang, jika dipetakan.

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`	❌ Tidak	string	None
`entities.{entity-name}.graphql.type`	`plural`	❌ Tidak	string	N/A (default ke nilai 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.

Format

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

Pemetaan (entitas nama entitas)

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	-

Format

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

Note

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

Example

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

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.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-09-24

Bagikan melalui

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Gambaran umum format

Sumber (entitas nama entitas)

Properti berlapis

Format

Izin (entitas nama entitas)

Format

Example

Contoh penggunaan

Tindakan (entitas nama entitas Izin string-array)

Format

Example

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

Example

Tindakan (entitas nama entitas Izin array objek)

Properti berlapis

Format

Example

Catatan kebijakan

Jenis (entitas nama entitas GraphQL)

Format

Properti berlapis

Example

Operasi (entitas nama entitas GraphQL)

Format

Contoh: operasi

Diaktifkan (entitas nama entitas GraphQL)

Format

REST (entitas nama entitas)

Format

Pemetaan (entitas nama entitas)

Format

Examples

Cache (entitas nama entitas)

Properti berlapis

Format

Example

Hubungan (entitas nama entitas)

Properti berlapis

Format

Contoh: Kardinalitas satu-ke-satu

Contoh: Kardinalitas satu ke banyak

Contoh: Kardinalitas banyak ke satu

Contoh: Kardinalitas banyak ke banyak

Kesehatan (entitas nama entitas)

Properti berlapis

Example

Saran dan Komentar

Sumber Daya Tambahan:

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