Referensi skema konfigurasi penyusun API Data
Mesin pembuat API Data memerlukan file konfigurasi. File konfigurasi Data API Builder menyediakan pendekatan terstruktur dan komprehensif untuk menyiapkan API Anda, merinci semuanya mulai dari variabel lingkungan hingga konfigurasi khusus entitas. Dokumen berformat JSON ini dimulai dengan properti $schema
. Penyetelan ini memvalidasi dokumen.
Properti database-type
dan connection-string
memastikan integrasi yang mulus dengan sistem database, dari Azure SQL Database ke Cosmos DB NoSQL API.
File konfigurasi dapat mencakup opsi seperti:
- Layanan database dan informasi koneksi
- Opsi konfigurasi global dan runtime
- Set entitas yang diekspos
- Metode autentikasi
- Aturan keamanan diperlukan untuk mengakses identitas
- Aturan pemetaan nama antara API dan database
- Hubungan antar entitas yang tidak dapat disimpulkan
- Fitur unik untuk layanan database tertentu
Gambaran umum sintaks
Berikut adalah perincian cepat dari "bagian" utama dalam file konfigurasi.
{
"$schema": "...",
"data-source": { ... },
"data-source-files": [ ... ],
"runtime": {
"rest": { ... },
"graphql": { .. },
"host": { ... },
"cache": { ... },
"telemetry": { ... },
"pagination": { ... }
}
"entities": [ ... ]
}
Properti tingkat atas
Berikut deskripsi properti tingkat atas dalam format tabel:
Harta benda | Deskripsi |
---|---|
$schema | Menentukan skema JSON untuk validasi, memastikan konfigurasi mematuhi format yang diperlukan. |
sumber data | Berisi detail tentang jenis database dan string koneksi , diperlukan untuk membuat koneksi database. |
file sumber data | Array opsional yang menentukan file konfigurasi lain yang mungkin menentukan sumber data lainnya. |
runtime |
Mengonfigurasi perilaku dan pengaturan runtime, termasuk subproperti untukREST |
entitas |
Menentukan kumpulan entitas (tabel database, tampilan, dll.) yang diekspos melalui API, termasuk pemetaan mereka, izin , dan hubungan . |
Konfigurasi sampel
Berikut adalah contoh file konfigurasi yang hanya menyertakan properti yang diperlukan untuk satu entitas sederhana. Sampel ini dimaksudkan untuk mengilustrasikan skenario minimal.
{
"$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
"data-source": {
"database-type": "mssql",
"connection-string": "@env('SQL_CONNECTION_STRING')"
},
"entities": {
"User": {
"source": "dbo.Users",
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
Untuk contoh skenario yang lebih kompleks, lihat konfigurasi sampel end-to-end.
Lingkungan
File konfigurasi penyusun API Data dapat mendukung skenario di mana Anda perlu mendukung beberapa lingkungan, mirip dengan file appSettings.json
di ASP.NET Core. Kerangka kerja ini menyediakan tiga nilai lingkungan umum ; Development
, Staging
, dan Production
; tetapi Anda dapat memilih untuk menggunakan nilai lingkungan apa pun yang Anda pilih. Lingkungan yang digunakan penyusun Api Data harus dikonfigurasi menggunakan variabel lingkungan DAB_ENVIRONMENT
.
Pertimbangkan contoh di mana Anda menginginkan konfigurasi dasar dan konfigurasi khusus pengembangan. Contoh ini memerlukan dua file konfigurasi:
Lingkungan | |
---|---|
dab-config.json | Dasar |
dab-config.Development.json | Pengembangan |
Untuk menggunakan konfigurasi khusus pengembangan, Anda harus mengatur variabel lingkungan DAB_ENVIRONMENT
ke Development
.
File konfigurasi khusus lingkungan mengambil alih nilai properti dalam file konfigurasi dasar. Dalam contoh ini, jika nilai connection-string
diatur dalam kedua file, nilai dari file *.Development.json digunakan.
Lihat matriks ini untuk lebih memahami nilai mana yang digunakan tergantung di mana nilai tersebut ditentukan (atau tidak ditentukan) dalam salah satu file.
Ditentukan dalam konfigurasi dasar | Tidak ditentukan dalam konfigurasi dasar | |
---|---|---|
Ditentukan dalam konfigurasi lingkungan saat ini | Lingkungan saat ini | Lingkungan saat ini |
Tidak ditentukan dalam konfigurasi lingkungan saat ini | Dasar | Tidak |
Untuk contoh penggunaan beberapa file konfigurasi, lihat menggunakan penyusun API Data dengan lingkungan.
Properti konfigurasi
Bagian ini mencakup semua kemungkinan properti konfigurasi yang tersedia untuk file konfigurasi.
Skema
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
$root |
$schema |
tali | ✔️ Ya | Tidak |
Setiap file konfigurasi dimulai dengan properti $schema
, menentukan skema JSON untuk validasi.
Format
{
"$schema": <string>
}
Contoh
File skema tersedia untuk versi 0.3.7-alpha
dan seterusnya pada URL tertentu, memastikan Anda 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
Versi terbaru skema selalu tersedia di https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.
Berikut adalah beberapa contoh nilai skema yang valid.
Versi | URI | Deskripsi |
---|---|---|
0.3.7-alpha | https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json |
Menggunakan skema konfigurasi dari versi alfa alat. |
0.10.23 | https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json |
Menggunakan skema konfigurasi untuk rilis alat yang stabil. |
Terbaru | https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json |
Menggunakan versi terbaru skema konfigurasi. |
Nota
Versi penyusun Api Data sebelum 0.3.7-alpha mungkin memiliki URI skema yang berbeda.
Sumber data
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
$root |
data-source |
tali | ✔️ Ya | Tidak |
Bagian data-source
menentukan database dan akses ke database melalui string koneksi. Ini juga mendefinisikan opsi database. Properti data-source
mengonfigurasi kredensial yang diperlukan untuk menyambungkan ke database cadangan. Bagian data-source
menguraikan konektivitas database backend, menentukan database-type
dan connection-string
.
Format
{
"data-source": {
"database-type": <string>,
"connection-string": <string>,
// mssql-only
"options": {
"set-session-context": <true> (default) | <false>
},
// cosmosdb_nosql-only
"options": {
"database": <string>,
"container": <string>,
"schema": <string>
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
database-type |
✔️ Ya | string enum |
connection-string |
✔️ Ya | tali |
options |
❌ Tidak | benda |
Jenis database
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
data-source |
database-type |
enum-string | ✔️ Ya | Tidak |
String enum yang digunakan untuk menentukan jenis database yang akan digunakan sebagai sumber data.
Format
{
"data-source": {
"database-type": <string>
}
}
Ketik nilai
Properti type
menunjukkan jenis database backend.
Jenis | Deskripsi | Versi Min |
---|---|---|
mssql |
Azure SQL Database | Tidak |
mssql |
Azure SQL MI | Tidak |
mssql |
SQL Server | SQL 2016 |
sqldw |
Gudang Data Azure SQL | Tidak |
postgresql |
PostgreSQL | v11 |
mysql |
MySQL | v8 |
cosmosdb_nosql |
Azure Cosmos DB untuk NoSQL | Tidak |
cosmosdb_postgresql |
Azure Cosmos DB for PostgreSQL | Tidak |
String koneksi
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
data-source |
connection-string |
tali | ✔️ Ya | Tidak |
String nilai yang berisi string koneksi yang valid untuk menyambungkan ke layanan database target. String koneksi ADO.NET untuk menyambungkan ke database backend. Untuk informasi selengkapnya, lihat ADO.NET string koneksi.
Format
{
"data-source": {
"connection-string": <string>
}
}
Ketahanan koneksi
Pembuat API Data secara otomatis mencoba kembali permintaan database setelah mendeteksi kesalahan sementara. Logika coba lagi mengikuti strategi Backoff Eksponensial r
): $r^2$
Dengan menggunakan rumus ini, Anda dapat menghitung waktu untuk setiap upaya coba lagi dalam hitungan detik.
Detik | |
---|---|
Pertama | 2 |
Kedua |
4 |
Ketiga | 8 |
Keempat | 16 |
Kelima | 32 |
Azure SQL dan SQL Server
Penyusun API Data menggunakan pustaka SqlClient
untuk menyambungkan ke Azure SQL atau SQL Server menggunakan string koneksi yang Anda sediakan dalam file konfigurasi. Daftar semua opsi string koneksi yang didukung tersedia di sini: Properti SqlConnection.ConnectionString.
Penyusun API Data juga dapat terhubung ke database target menggunakan Identitas Layanan Terkelola (MSI) saat penyusun API Data dihosting di Azure.
DefaultAzureCredential
yang ditentukan dalam pustaka Azure.Identity
digunakan untuk menyambungkan menggunakan identitas yang diketahui saat Anda tidak menentukan nama pengguna atau kata sandi dalam string koneksi Anda. Untuk informasi selengkapnya, lihat contoh DefaultAzureCredential
.
Identitas Terkelola yang Ditetapkan Pengguna (UMI): Tambahkan properti Autentikasi dan Id Pengguna ke string koneksi Anda saat menggantikan id klien Identitas Terkelola yang Ditetapkan Pengguna Anda: . System Assigned Managed Identity (SMI): Tambahkan properti Autentikasidan kecualikan UserId Kata Sandidan argumen Kata Sandi dari string koneksi Anda: . Tidak adanya UserId dan properti string koneksi akan memberi sinyal KEPADA DAB untuk mengautentikasi menggunakan identitas terkelola yang ditetapkan sistem.
Untuk informasi selengkapnya tentang mengonfigurasi Identitas Layanan Terkelola dengan Azure SQL atau SQL Server, lihat identitas terkelola di Microsoft Entra untuk Azure SQL.
Contoh
Nilai yang digunakan untuk string koneksi sebagian besar tergantung pada layanan database yang digunakan dalam skenario Anda. Anda selalu dapat memilih untuk menyimpan string koneksi dalam variabel lingkungan dan mengaksesnya menggunakan fungsi @env()
.
Nilai | Deskripsi | |
---|---|---|
Menggunakan nilai string Azure SQL Database | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>; |
String koneksi ke akun Azure SQL Database. Untuk informasi selengkapnya, lihat string koneksi Azure SQL Database. |
Menggunakan nilai string Azure Database for PostgreSQL | Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require; |
String koneksi ke akun Azure Database for PostgreSQL. Untuk informasi selengkapnya, lihat string koneksi Azure Database for PostgreSQL. |
Menggunakan Azure Cosmos DB untuk nilai string NoSQL | AccountEndpoint=<endpoint>;AccountKey=<key>; |
String koneksi ke akun Azure Cosmos DB for NoSQL. Untuk informasi selengkapnya, lihat Azure Cosmos DB untuk string koneksi NoSQL. |
Menggunakan nilai string Azure Database for MySQL | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>; |
String koneksi ke akun Azure Database for MySQL. Untuk informasi selengkapnya, lihat string koneksi Azure Database for MySQL. |
variabel lingkungan akses |
@env('SQL_CONNECTION_STRING') |
Akses variabel lingkungan dari komputer lokal. Dalam contoh ini, variabel lingkungan SQL_CONNECTION_STRING dirujuk. |
Ujung
Sebagai praktik terbaik, hindari menyimpan informasi sensitif dalam file konfigurasi Anda. Jika memungkinkan, gunakan @env()
untuk mereferensikan variabel lingkungan. Untuk informasi selengkapnya, lihat fungsi @env()
.
Sampel ini hanya menggambarkan bagaimana setiap jenis database mungkin dikonfigurasi. Skenario Anda mungkin unik, tetapi sampel ini adalah tempat awal yang baik. Ganti tempat penampung seperti myserver
, myDataBase
, mylogin
, dan myPassword
dengan nilai aktual khusus untuk lingkungan Anda.
mssql
"data-source": { "database-type": "mssql", "connection-string": "$env('my-connection-string')", "options": { "set-session-context": true } }
-
Format string koneksi umum:
"Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
-
Format string koneksi umum:
postgresql
"data-source": { "database-type": "postgresql", "connection-string": "$env('my-connection-string')" }
-
Format string koneksi umum:
"Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
-
Format string koneksi umum:
mysql
"data-source": { "database-type": "mysql", "connection-string": "$env('my-connection-string')" }
-
Format string koneksi umum:
"Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"
-
Format string koneksi umum:
cosmosdb_nosql
"data-source": { "database-type": "cosmosdb_nosql", "connection-string": "$env('my-connection-string')", "options": { "database": "Your_CosmosDB_Database_Name", "container": "Your_CosmosDB_Container_Name", "schema": "Path_to_Your_GraphQL_Schema_File" } }
-
Format string koneksi umum:
"AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"
-
Format string koneksi umum:
cosmosdb_postgresql
"data-source": { "database-type": "cosmosdb_postgresql", "connection-string": "$env('my-connection-string')" }
-
Format string koneksi umum:
"Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"
-
Format string koneksi umum:
Nota
"Opsi" yang ditentukan seperti database
, container
, dan schema
khusus untuk API NoSQL Azure Cosmos DB daripada API PostgreSQL. Untuk Azure Cosmos DB menggunakan API PostgreSQL, "opsi" tidak akan menyertakan database
, container
, atau schema
seperti dalam penyiapan NoSQL.
Pilihan
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
data-source |
options |
benda | ❌ Tidak | Tidak |
Bagian opsional dari parameter kunci-nilai tambahan untuk koneksi database tertentu.
Apakah bagian options
diperlukan atau tidak sebagian besar tergantung pada layanan database yang digunakan.
Format
{
"data-source": {
"options": {
"<key-name>": <string>
}
}
}
options: { set-session-context: boolean }
Untuk Azure SQL dan SQL Server, pembuat API Data dapat memanfaatkan SESSION_CONTEXT
untuk mengirim metadata yang ditentukan pengguna ke database yang mendasar. Metadata tersebut tersedia untuk penyusun API Data berdasarkan klaim yang ada dalam token akses. Data SESSION_CONTEXT
tersedia untuk database selama koneksi database hingga koneksi tersebut ditutup. Untuk informasi selengkapnya, lihat konteks sesi.
Contoh Prosedur Tersimpan SQL:
CREATE PROC GetUser @userId INT AS
BEGIN
-- Check if the current user has access to the requested userId
IF SESSION_CONTEXT(N'user_role') = 'admin'
OR SESSION_CONTEXT(N'user_id') = @userId
BEGIN
SELECT Id, Name, Age, IsAdmin
FROM Users
WHERE Id = @userId;
END
ELSE
BEGIN
RAISERROR('Unauthorized access', 16, 1);
END
END;
Contoh Konfigurasi JSON:
{
"$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
"data-source": {
"database-type": "mssql",
"connection-string": "@env('SQL_CONNECTION_STRING')",
"options": {
"set-session-context": true
}
},
"entities": {
"User": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
},
"permissions": [
{
"role": "authenticated",
"actions": ["execute"]
}
]
}
}
}
Penjelasan:
Prosedur Tersimpan (
GetUser
):- Prosedur memeriksa
SESSION_CONTEXT
untuk memvalidasi apakah pemanggil memiliki peranadmin
atau cocok denganuserId
yang disediakan. - Akses tidak sah menghasilkan kesalahan.
- Prosedur memeriksa
Konfigurasi JSON :
-
set-session-context
diaktifkan untuk meneruskan metadata pengguna dari token akses ke database. - Properti
parameters
memetakan parameteruserId
yang diperlukan oleh prosedur tersimpan. - Blok
permissions
memastikan hanya pengguna terautentikasi yang dapat menjalankan prosedur tersimpan.
-
File sumber data
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
$root |
data-source-files |
array string | ❌ Tidak | Tidak |
Penyusun API Data mendukung beberapa file konfigurasi untuk sumber data yang berbeda, dengan satu ditunjuk sebagai file tingkat atas yang mengelola pengaturan runtime
. Semua konfigurasi memiliki skema yang sama, memungkinkan pengaturan runtime
dalam file apa pun tanpa kesalahan. Konfigurasi anak bergabung secara otomatis, tetapi referensi melingkar harus dihindari. Entitas dapat dibagi menjadi file terpisah untuk manajemen yang lebih baik, tetapi hubungan antar entitas harus dalam file yang sama.
Format
{
"data-source-files": [ <string> ]
}
Pertimbangan file konfigurasi
- Setiap file konfigurasi harus menyertakan properti
data-source
. - Setiap file konfigurasi harus menyertakan properti
entities
. - Pengaturan
runtime
hanya digunakan dari file konfigurasi tingkat atas, bahkan jika disertakan dalam file lain. - File konfigurasi anak juga dapat menyertakan file anak mereka sendiri.
- File konfigurasi dapat diatur ke dalam subfolder seperti yang diinginkan.
- Nama entitas harus unik di semua file konfigurasi.
- Hubungan antar entitas dalam file konfigurasi yang berbeda tidak didukung.
Contoh
{
"data-source-files": [
"dab-config-2.json"
]
}
{
"data-source-files": [
"dab-config-2.json",
"dab-config-3.json"
]
}
Sintaks subfolder juga didukung:
{
"data-source-files": [
"dab-config-2.json",
"my-folder/dab-config-3.json",
"my-folder/my-other-folder/dab-config-4.json"
]
}
Runtime
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
$root |
runtime |
benda | ✔️ Ya | Tidak |
Bagian runtime
menguraikan opsi yang memengaruhi perilaku runtime dan pengaturan untuk semua entitas yang terekspos.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api),
"enabled": <true> (default) | <false>,
"request-body-strict": <true> (default) | <false>
},
"graphql": {
"path": <string> (default: /graphql),
"enabled": <true> (default) | <false>,
"allow-introspection": <true> (default) | <false>
},
"host": {
"mode": "production" (default) | "development",
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
},
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
},
"cache": {
"enabled": <true> | <false> (default),
"ttl-seconds": <integer; default: 5>
},
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>,
"max-response-size-mb": <integer; default: 158>
},
"telemetry": {
"application-insights": {
"connection-string": <string>,
"enabled": <true> | <false> (default)
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
rest |
❌ Tidak | benda |
graphql |
❌ Tidak | benda |
host |
❌ Tidak | benda |
cache |
❌ Tidak | benda |
Contoh
Berikut adalah contoh bagian runtime dengan beberapa parameter default umum yang ditentukan.
{
"runtime": {
"rest": {
"enabled": true,
"path": "/api",
"request-body-strict": true
},
"graphql": {
"enabled": true,
"path": "/graphql",
"allow-introspection": true
},
"host": {
"mode": "development",
"cors": {
"allow-credentials": false,
"origins": [
"*"
]
},
"authentication": {
"provider": "StaticWebApps",
"jwt": {
"audience": "<client-id>",
"issuer": "<identity-provider-issuer-uri>"
}
}
},
"cache": {
"enabled": true,
"ttl-seconds": 5
},
"pagination": {
"max-page-size": -1 | <integer; default: 100000>,
"default-page-size": -1 | <integer; default: 100>,
"max-response-size-mb": <integer; default: 158>
},
"telemetry": {
"application-insights": {
"connection-string": "<connection-string>",
"enabled": true
}
}
}
}
GraphQL (runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
graphql |
benda | ❌ Tidak | Tidak |
Objek ini menentukan apakah GraphQL diaktifkan dan nama yang digunakan untuk mengekspos entitas sebagai jenis GraphQL. Objek ini bersifat opsional dan hanya digunakan jika nama atau pengaturan default tidak cukup. Bagian ini menguraikan pengaturan global untuk titik akhir GraphQL.
Format
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql),
"enabled": <true> (default) | <false>,
"depth-limit": <integer; default: none>,
"allow-introspection": <true> (default) | <false>,
"multiple-mutations": <object>
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
❌ Tidak | Boolean | Benar |
path |
❌ Tidak | tali | /graphql (default) |
allow-introspection |
❌ Tidak | Boolean | Benar |
multiple-mutations |
❌ Tidak | benda | { create: { enabled: false } } |
Diaktifkan (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql |
enabled |
Boolean | ❌ Tidak | Tidak |
Menentukan apakah akan mengaktifkan atau menonaktifkan titik akhir GraphQL secara global. Jika dinonaktifkan secara global, tidak ada entitas yang dapat diakses melalui permintaan GraphQL terlepas dari pengaturan entitas individual.
Format
{
"runtime": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
Contoh
Dalam contoh ini, titik akhir GraphQL dinonaktifkan untuk semua entitas.
{
"runtime": {
"graphql": {
"enabled": false
}
}
}
Batas kedalaman (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql |
depth-limit |
Integer | ❌ Tidak | Tidak |
Kedalaman kueri maksimum yang diizinkan dari kueri.
Kemampuan GraphQL untuk menangani kueri berlapis berdasarkan definisi hubungan adalah fitur yang luar biasa, memungkinkan pengguna mengambil data terkait yang kompleks dalam satu kueri. Namun, karena pengguna terus menambahkan kueri berlapis, kompleksitas kueri meningkat, yang akhirnya dapat membahayakan performa dan keandalan database dan titik akhir API. Untuk mengelola situasi ini, properti runtime/graphql/depth-limit
mengatur kedalaman maksimum yang diizinkan dari kueri GraphQL (dan mutasi). Properti ini memungkinkan pengembang untuk mencapai keseimbangan, memungkinkan pengguna untuk menikmati manfaat kueri berlapis sambil menempatkan batas untuk mencegah skenario yang dapat membahayakan performa dan kualitas sistem.
Contoh
{
"runtime": {
"graphql": {
"depth-limit": 2
}
}
}
Jalur (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql |
path |
tali | ❌ Tidak | "/graphql" |
Menentukan jalur URL tempat titik akhir GraphQL tersedia. Misalnya, jika parameter ini diatur ke /graphql
, titik akhir GraphQL diekspos sebagai /graphql
. Secara default, jalurnya adalah /graphql
.
Penting
Sub-jalur tidak diperbolehkan untuk properti ini. Nilai jalur yang dikustomisasi untuk titik akhir GraphQL saat ini tidak tersedia.
Format
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql)
}
}
}
Contoh
Dalam contoh ini, URI GraphQL akar /query
.
{
"runtime": {
"graphql": {
"path": "/query"
}
}
}
Izinkan introspeksi (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql |
allow-introspection |
Boolean | ❌ Tidak | Benar |
Bendera Boolean ini mengontrol kemampuan untuk melakukan kueri introspeksi skema pada titik akhir GraphQL. Mengaktifkan introspeksi memungkinkan klien untuk mengkueri skema untuk informasi tentang jenis data yang tersedia, jenis kueri yang dapat mereka lakukan, dan mutasi yang tersedia.
Fitur ini berguna selama pengembangan untuk memahami struktur API GraphQL dan untuk alat yang secara otomatis menghasilkan kueri. Namun, untuk lingkungan produksi, mungkin dinonaktifkan untuk mengaburkan detail skema API dan meningkatkan keamanan. Secara default, introspeksi diaktifkan, memungkinkan eksplorasi langsung dan komprehensif dari skema GraphQL.
Format
{
"runtime": {
"graphql": {
"allow-introspection": <true> (default) | <false>
}
}
}
Contoh
Dalam contoh ini, introspeksi dinonaktifkan.
{
"runtime": {
"graphql": {
"allow-introspection": false
}
}
}
Beberapa mutasi (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql |
multiple-mutations |
benda | ❌ Tidak | Tidak |
Mengonfigurasi semua beberapa operasi mutasi untuk runtime GraphQL.
Nota
Secara default, beberapa mutasi tidak diaktifkan dan harus secara eksplisit dikonfigurasi untuk diaktifkan.
Format
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
create |
❌ Tidak | benda |
Beberapa mutasi - buat (runtime GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.graphql.multiple-mutations |
create |
Boolean | ❌ Tidak | Palsu |
Mengonfigurasi beberapa operasi pembuatan untuk runtime GraphQL.
Format
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
✔️ Ya | Boolean | Benar |
Contoh
Berikut ini menunjukkan cara mengaktifkan dan menggunakan beberapa mutasi dalam runtime bahasa umum GraphQL. Dalam hal ini, operasi create
dikonfigurasi untuk memungkinkan pembuatan beberapa rekaman dalam satu permintaan dengan mengatur properti runtime.graphql.multiple-mutations.create.enabled
ke true
.
Contoh Konfigurasi
Konfigurasi ini memungkinkan beberapa mutasi create
:
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": true
}
}
}
},
"entities": {
"User": {
"source": "dbo.Users",
"permissions": [
{
"role": "anonymous",
"actions": ["create"]
}
]
}
}
}
Contoh Mutasi GraphQL
Dengan menggunakan konfigurasi di atas, mutasi berikut membuat beberapa rekaman User
dalam satu operasi:
mutation {
createUsers(input: [
{ name: "Alice", age: 30, isAdmin: true },
{ name: "Bob", age: 25, isAdmin: false },
{ name: "Charlie", age: 35, isAdmin: true }
]) {
id
name
age
isAdmin
}
}
REST (runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
rest |
benda | ❌ Tidak | Tidak |
Bagian ini menguraikan pengaturan global untuk titik akhir REST. Pengaturan ini berfungsi sebagai default untuk semua entitas tetapi dapat ditimpa berdasarkan per entitas dalam konfigurasi masing-masing.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api),
"enabled": <true> (default) | <false>,
"request-body-strict": <true> (default) | <false>
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
❌ Tidak | Boolean | Benar |
path |
❌ Tidak | tali | /api |
request-body-strict |
❌ Tidak | Boolean | Benar |
Diaktifkan (runtime REST)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.rest |
enabled |
Boolean | ❌ Tidak | Tidak |
Bendera Boolean yang menentukan ketersediaan global titik akhir REST. Jika dinonaktifkan, entitas tidak dapat diakses melalui REST, terlepas dari pengaturan entitas individual.
Format
{
"runtime": {
"rest": {
"enabled": <true> (default) | <false>,
}
}
}
Contoh
Dalam contoh ini, titik akhir REST API dinonaktifkan untuk semua entitas.
{
"runtime": {
"rest": {
"enabled": false
}
}
}
Jalur (runtime REST)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.rest |
path |
tali | ❌ Tidak | "/api" |
Mengatur jalur URL untuk mengakses semua titik akhir REST yang terekspos. Misalnya, mengatur path
ke /api
membuat titik akhir REST dapat diakses di /api/<entity>
. Subpath tidak diizinkan. Bidang ini bersifat opsional, dengan /api
sebagai default.
Nota
Saat menyebarkan penyusun API Data menggunakan Static Web Apps (pratinjau), layanan Azure secara otomatis menyuntikkan subpath tambahan /data-api
ke url. Perilaku ini memastikan kompatibilitas dengan fitur Static Web App yang ada. Titik akhir yang dihasilkan akan /data-api/api/<entity>
. Ini hanya relevan dengan Static Web Apps.
Format
{
"runtime": {
"rest": {
"path": <string> (default: /api)
}
}
}
Penting
Sub-jalur yang disediakan pengguna tidak diperbolehkan untuk properti ini.
Contoh
Dalam contoh ini, URI REST API akar /data
.
{
"runtime": {
"rest": {
"path": "/data"
}
}
}
Ujung
Jika Anda menentukan entitas Author
, titik akhir untuk entitas ini akan /data/Author
.
Isi Permintaan Ketat (REST Runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.rest |
request-body-strict |
Boolean | ❌ Tidak | Benar |
Pengaturan ini mengontrol seberapa ketat isi permintaan untuk operasi mutasi REST (misalnya, POST
, PUT
, PATCH
) divalidasi.
-
true
(default): Bidang tambahan dalam isi permintaan yang tidak dipetakan ke kolom tabel menyebabkan pengecualianBadRequest
. -
false
: Bidang tambahan diabaikan, dan hanya kolom yang valid yang diproses.
Pengaturan ini tidak berlaku untuk permintaan GET
, karena isi permintaannya selalu diabaikan.
Perilaku dengan Konfigurasi Kolom Tertentu
- Kolom dengan nilai default() diabaikan selama
INSERT
hanya ketika nilainya dalam payloadnull
. Kolom dengan default() tidak diabaikan selamaUPDATE
terlepas dari nilai payload. - Kolom komputasi selalu diabaikan.
- Kolom yang dihasilkan secara otomatis selalu diabaikan.
Format
{
"runtime": {
"rest": {
"request-body-strict": <true> (default) | <false>
}
}
}
Contoh
CREATE TABLE Users (
Id INT PRIMARY KEY IDENTITY,
Name NVARCHAR(50) NOT NULL,
Age INT DEFAULT 18,
IsAdmin BIT DEFAULT 0,
IsMinor AS IIF(Age <= 18, 1, 0)
);
Contoh Konfigurasi
{
"runtime": {
"rest": {
"request-body-strict": false
}
}
}
Perilaku INSERT dengan request-body-strict: false
Meminta Payload:
{
"Id": 999,
"Name": "Alice",
"Age": null,
"IsAdmin": null,
"IsMinor": false,
"ExtraField": "ignored"
}
Pernyataan Sisipkan yang Dihasilkan:
INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.
Payload Respons
{
"Id": 1, // Auto-generated by the database
"Name": "Alice",
"Age": 18, // Default applied
"IsAdmin": false, // Default applied
"IsMinor": true // Computed
}
PERBARUI Perilaku dengan request-body-strict: false
Meminta Payload:
{
"Id": 1,
"Name": "Alice Updated",
"Age": null, // explicitely set to 'null'
"IsMinor": true, // ignored because computed
"ExtraField": "ignored"
}
Pernyataan Pembaruan yang Dihasilkan:
UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.
Payload Respons
{
"Id": 1,
"Name": "Alice Updated",
"Age": null,
"IsAdmin": false,
"IsMinor": false // Recomputed by the database (false when age is `null`)
}
Host (runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
host |
benda | ❌ Tidak | Tidak |
Bagian host
dalam konfigurasi runtime menyediakan pengaturan penting untuk lingkungan operasional penyusun API Data. Pengaturan ini mencakup mode operasional, konfigurasi CORS, dan detail autentikasi.
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development",
"max-response-size-mb": <integer; default: 158>,
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
},
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
mode |
❌ Tidak | string enum | produksi |
cors |
❌ Tidak | benda | Tidak |
authentication |
❌ Tidak | benda | Tidak |
Contoh
Berikut adalah contoh runtime yang dikonfigurasi untuk hosting pengembangan.
{
"runtime": {
"host": {
"mode": "development",
"cors": {
"allow-credentials": false,
"origins": ["*"]
},
"authentication": {
"provider": "Simulator"
}
}
}
}
Mode (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host |
mode |
tali | ❌ Tidak | "produksi" |
Menentukan apakah mesin pembuat API Data harus berjalan dalam mode development
atau production
. Nilai default adalah production
.
Biasanya, kesalahan database yang mendasar diekspos secara rinci dengan mengatur tingkat detail default agar log Debug
saat berjalan dalam pengembangan. Dalam produksi, tingkat detail untuk log diatur ke Error
.
Ujung
Tingkat log default dapat ditimpa lebih lanjut menggunakan dab start --LogLevel <level-of-detail>
. Untuk informasi selengkapnya, lihat referensi antarmuka baris perintah (CLI) .
Format
{
"runtime": {
"host": {
"mode": "production" (default) | "development"
}
}
}
Nilai
Berikut adalah daftar nilai yang diizinkan untuk properti ini:
Deskripsi | |
---|---|
production |
Gunakan saat menghosting dalam produksi di Azure |
development |
Gunakan dalam pengembangan pada komputer lokal |
Perilaku
- Hanya dalam mode
development
Swagger yang tersedia. - Hanya dalam mode
development
tersedia Banana Cake Pop.
Ukuran respons maksimum (Runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host |
max-response-size-mb |
Integer | ❌ Tidak | 158 |
Mengatur ukuran maksimum (dalam megabyte) untuk hasil tertentu. Pengaturan ini memungkinkan pengguna untuk mengonfigurasi jumlah data yang dapat ditangani memori platform host mereka saat streaming data dari sumber data yang mendasar.
Saat pengguna meminta tataan hasil besar, pengguna dapat membatasi database dan penyusun API Data. Untuk mengatasi hal ini, max-response-size-mb
memungkinkan pengembang membatasi ukuran respons maksimum, yang diukur dalam megabyte, sebagai aliran data dari sumber data. Batas ini didasarkan pada ukuran data keseluruhan, bukan jumlah baris. Karena kolom dapat bervariasi dalam ukuran, beberapa kolom (seperti teks, biner, XML, atau JSON) dapat menampung hingga 2 GB masing-masing, membuat baris individual berpotensi sangat besar. Pengaturan ini membantu pengembang melindungi titik akhir mereka dengan membatasi ukuran respons dan mencegah kelebihan sistem sambil mempertahankan fleksibilitas untuk berbagai jenis data.
Nilai yang diizinkan
Nilai | Hasil |
---|---|
null |
Default ke 158 megabyte jika tidak diatur atau secara eksplisit diatur ke null . |
integer |
Bilangan bulat 32-bit positif didukung. |
< 0 |
Tidak didukung. Kesalahan validasi terjadi jika diatur ke kurang dari 1 MB. |
Format
{
"runtime": {
"host": {
"max-response-size-mb": <integer; default: 158>
}
}
}
CORS (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host |
cors |
benda | ❌ Tidak | Tidak |
Pengaturan berbagi sumber daya lintas asal (CORS) untuk host mesin pembuat API Data.
Format
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
}
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
allow-credentials |
❌ Tidak | Boolean |
origins |
❌ Tidak | array string |
Izinkan kredensial (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.cors |
allow-credentials |
Boolean | ❌ Tidak | Palsu |
Jika true, atur header CORS Access-Control-Allow-Credentials
.
Nota
Untuk infromasi selengkapnya di header CORS Access-Control-Allow-Credentials
, lihat referensi CORS MDN Web Docs.
Format
{
"runtime": {
"host": {
"cors": {
"allow-credentials": <true> (default) | <false>
}
}
}
}
Asal (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.cors |
origins |
array string | ❌ Tidak | Tidak |
Mengatur array dengan daftar asal yang diizinkan untuk CORS. Pengaturan ini memungkinkan kartubebas *
untuk semua asal.
Format
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"]
}
}
}
}
Contoh
Berikut adalah contoh host yang memungkinkan CORS tanpa kredensial dari semua asal.
{
"runtime": {
"host": {
"cors": {
"allow-credentials": false,
"origins": ["*"]
}
}
}
}
Autentikasi (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host |
authentication |
benda | ❌ Tidak | Tidak |
Mengonfigurasi autentikasi untuk host pembuat API Data.
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<string>",
"issuer": "<string>"
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
provider |
❌ Tidak | string enum | StaticWebApps |
jwt |
❌ Tidak | benda | Tidak |
Autentikasi dan tanggung jawab pelanggan
Penyusun API Data dirancang untuk beroperasi dalam alur keamanan yang lebih luas, dan ada langkah-langkah penting untuk dikonfigurasi sebelum memproses permintaan. Penting untuk dipahami bahwa pembuat API Data tidak mengautentikasi pemanggil langsung (seperti aplikasi web Anda) melainkan pengguna akhir, berdasarkan token JWT yang valid yang disediakan oleh penyedia identitas tepercaya (misalnya, ID Entra). Ketika permintaan mencapai penyusun Data API, ia mengasumsikan token JWT valid dan memeriksanya terhadap prasyarat apa pun yang telah Anda konfigurasi, seperti klaim tertentu. Aturan otorisasi kemudian diterapkan untuk menentukan apa yang dapat diakses atau diubah pengguna.
Setelah otorisasi lolos, penyusun API Data menjalankan permintaan menggunakan akun yang ditentukan dalam string koneksi. Karena akun ini sering memerlukan izin yang ditinggikan untuk menangani berbagai permintaan pengguna, sangat penting untuk meminimalkan hak aksesnya untuk mengurangi risiko. Sebaiknya amankan arsitektur Anda dengan mengonfigurasi Private Link antara aplikasi web front-end Anda dan titik akhir API, dan dengan memperkuat mesin yang menghosting pembuat API Data. Langkah-langkah ini membantu memastikan lingkungan Anda tetap aman, melindungi data Anda, dan meminimalkan kerentanan yang dapat dieksploitasi untuk mengakses, memodifikasi, atau menyelundupkan informasi sensitif.
Penyedia (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.authentication |
provider |
tali | ❌ Tidak | "StaticWebApps" |
Pengaturan authentication.provider
dalam konfigurasi host
menentukan metode autentikasi yang digunakan oleh penyusun API Data. Ini menentukan bagaimana API memvalidasi identitas pengguna atau layanan yang mencoba mengakses sumber dayanya. Pengaturan ini memungkinkan fleksibilitas dalam penyebaran dan integrasi dengan mendukung berbagai mekanisme autentikasi yang disesuaikan dengan lingkungan dan persyaratan keamanan yang berbeda.
Penyedia | Deskripsi |
---|---|
StaticWebApps |
Menginstruksikan penyusun API Data untuk mencari sekumpulan header HTTP hanya ada saat berjalan dalam lingkungan Static Web Apps. |
AppService |
Saat runtime dihosting di Azure AppService dengan AppService Authentication diaktifkan dan dikonfigurasi (EasyAuth). |
AzureAd |
Microsoft Entra Identity perlu dikonfigurasi sehingga dapat mengautentikasi permintaan yang dikirim ke penyusun API Data ("Aplikasi Server"). Untuk informasi selengkapnya, lihat autentikasi ID Microsoft Entra. |
Simulator |
Penyedia autentikasi yang dapat dikonfigurasi yang menginstruksikan mesin pembuat API Data untuk memperlakukan semua permintaan sebagai diautentikasi. Untuk informasi selengkapnya, lihat autentikasi lokal. |
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...
}
}
}
}
Nilai
Berikut adalah daftar nilai yang diizinkan untuk properti ini:
Deskripsi | |
---|---|
StaticWebApps |
Azure Static Web Apps |
AppService |
Azure App Service |
AzureAD |
Microsoft Entra ID |
Simulator |
Simulator |
Token Web JSON (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.authentication |
jwt |
benda | ❌ Tidak | Tidak |
Jika penyedia autentikasi diatur ke AzureAD
(MICROSOFT Entra ID), maka bagian ini diperlukan untuk menentukan audiens dan penerbit untuk token JSOn Web Tokens (JWT). Data ini digunakan untuk memvalidasi token terhadap penyewa Microsoft Entra Anda.
Diperlukan jika penyedia autentikasi AzureAD
untuk ID Microsoft Entra. Bagian ini harus menentukan audience
dan issuer
untuk memvalidasi token JWT yang diterima terhadap penyewa AzureAD
yang dimaksudkan untuk autentikasi.
Pengaturan | Deskripsi |
---|---|
penonton | Mengidentifikasi penerima token yang dimaksud; biasanya pengidentifikasi aplikasi yang terdaftar di Microsoft Entra Identity (atau penyedia identitas Anda), memastikan bahwa token memang dikeluarkan untuk aplikasi Anda. |
Penerbit | Menentukan URL otoritas penerbit, yang merupakan layanan token yang mengeluarkan JWT. URL ini harus cocok dengan URL penerbit penyedia identitas tempat JWT diperoleh, memvalidasi asal token. |
Format
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
audience |
❌ Tidak | tali | Tidak |
issuer |
❌ Tidak | tali | Tidak |
Contoh
Pembuat API Data (DAB) menawarkan dukungan autentikasi yang fleksibel, terintegrasi dengan Microsoft Entra Identity dan server JSON Web Token (JWT) kustom. Dalam gambar ini, JWT Server mewakili layanan autentikasi yang mengeluarkan token JWT kepada klien setelah berhasil masuk. Klien kemudian meneruskan token ke DAB, yang dapat menginterogasi klaim dan propertinya.
Berikut ini adalah contoh properti host
yang diberikan berbagai pilihan arsitektur yang mungkin Anda buat dalam solusi Anda.
Azure Static Web Apps
{
"host": {
"mode": "development",
"cors": {
"origins": ["https://dev.example.com"],
"credentials": true
},
"authentication": {
"provider": "StaticWebApps"
}
}
}
Dengan StaticWebApps
, pembuat API Data mengharapkan Azure Static Web Apps untuk mengautentikasi permintaan dan header HTTP X-MS-CLIENT-PRINCIPAL
ada.
Azure App Service
{
"host": {
"mode": "production",
"cors": {
"origins": [ "https://api.example.com" ],
"credentials": false
},
"authentication": {
"provider": "AppService",
"jwt": {
"audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
"issuer": "https://example-appservice-auth.com"
}
}
}
}
Autentikasi didelegasikan ke IdP yang didukung di mana token akses dapat dikeluarkan. Token akses yang diperoleh harus disertakan dengan permintaan masuk ke penyusun API Data. Penyusun API Data kemudian memvalidasi token akses yang disajikan, memastikan bahwa penyusun API Data adalah audiens token yang dimaksudkan.
Microsoft Entra ID
{
"host": {
"mode": "production",
"cors": {
"origins": [ "https://api.example.com" ],
"credentials": true
},
"authentication": {
"provider": "AzureAD",
"jwt": {
"audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
"issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
}
}
}
}
Simulator (Khusus pengembangan)
{
"host": {
"mode": "development",
"authentication": {
"provider": "Simulator"
}
}
}
Audiens (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.authentication.jwt |
audience |
tali | ❌ Tidak | Tidak |
Audiens untuk token JWT.
Format
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"audience": "<client-id>"
}
}
}
}
}
Pengeluar sertifikat (Runtime host)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.host.authentication.jwt |
issuer |
tali | ❌ Tidak | Tidak |
Penerbit untuk token JWT.
Format
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"issuer": "<issuer-url>"
}
}
}
}
}
Penomoran halaman (Runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
pagination |
benda | ❌ Tidak | Tidak |
Mengonfigurasi batas penomoran halaman untuk titik akhir REST dan GraphQL.
Format
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
max-page-size |
❌ Tidak | Integer | 100,000 |
default-page-size |
❌ Tidak | Integer | 100 |
Contoh Konfigurasi
{
"runtime": {
"pagination": {
"max-page-size": 1000,
"default-page-size": 2
}
},
"entities": {
"Users": {
"source": "dbo.Users",
"permissions": [
{
"actions": ["read"],
"role": "anonymous"
}
]
}
}
}
Contoh Penomoran Halaman REST
Dalam contoh ini, mengeluarkan permintaan REST GET https://localhost:5001/api/users
akan mengembalikan dua rekaman dalam array value
karena default-page-size
diatur ke 2. Jika ada lebih banyak hasil, penyusun Api Data menyertakan nextLink
dalam respons.
nextLink
berisi parameter $after
untuk mengambil halaman data berikutnya.
Minta:
GET https://localhost:5001/api/users
Jawaban:
{
"value": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
Menggunakan nextLink
, klien dapat mengambil serangkaian hasil berikutnya.
Contoh Penomoran Halaman GraphQL
Untuk GraphQL, gunakan bidang hasNextPage
dan endCursor
untuk penomoran halaman. Bidang-bidang ini menunjukkan apakah lebih banyak hasil tersedia dan menyediakan kursor untuk mengambil halaman berikutnya.
Kueri:
query {
users {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
Jawaban:
{
"data": {
"users": {
"items": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"hasNextPage": true,
"endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
}
}
Untuk mengambil halaman berikutnya, sertakan nilai endCursor
dalam kueri berikutnya:
Kueri dengan Kursor:
query {
users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
Menyesuaikan Ukuran Halaman
REST dan GraphQL memungkinkan penyesuaian jumlah hasil per kueri menggunakan $limit
(REST) atau first
(GraphQL).
Nilai $limit /first |
Perilaku |
---|---|
-1 |
Default ke max-page-size . |
< max-page-size |
Membatasi hasil ke nilai yang ditentukan. |
0 atau < -1 |
Tidak didukung. |
> max-page-size |
Dibatasi pada max-page-size . |
Contoh Kueri REST:
GET https://localhost:5001/api/users?$limit=5
Contoh Kueri GraphQL:
query {
users(first: 5) {
items {
Id
Name
Age
IsAdmin
IsMinor
}
}
}
Ukuran halaman maksimum (runtime penomoran halaman)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.pagination |
max-page-size |
Int | ❌ Tidak | 100,000 |
Mengatur jumlah maksimum rekaman tingkat atas yang dikembalikan oleh REST atau GraphQL. Jika pengguna meminta lebih dari max-page-size
, hasilnya dibatasi pada max-page-size
.
Nilai yang diizinkan
Nilai | Hasil |
---|---|
-1 |
Default ke nilai maksimum yang didukung. |
integer |
Bilangan bulat 32-bit positif didukung. |
< -1 |
Tidak didukung. |
0 |
Tidak didukung. |
Format
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>
}
}
}
Ukuran halaman default (runtime penomoran halaman)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.pagination |
default-page-size |
Int | ❌ Tidak | 100 |
Mengatur jumlah default rekaman tingkat atas yang dikembalikan saat penomoran halaman diaktifkan tetapi tidak ada ukuran halaman eksplisit yang disediakan.
Nilai yang diizinkan
Nilai | Hasil |
---|---|
-1 |
Default ke pengaturan max-page-size saat ini. |
integer |
Bilangan bulat positif apa pun yang kurang dari max-page-size saat ini. |
< -1 |
Tidak didukung. |
0 |
Tidak didukung. |
Cache (runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
cache |
benda | ❌ Tidak | Tidak |
Mengaktifkan dan mengonfigurasi penembolokan untuk seluruh runtime.
Format
{
"runtime": {
"cache": <object>
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
❌ Tidak | Boolean | Tidak |
ttl-seconds |
❌ Tidak | Integer | 5 |
Contoh
Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 30 detik.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
Diaktifkan (Runtime cache)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.cache |
enabled |
Boolean | ❌ Tidak | Palsu |
Memungkinkan penembolokan secara global untuk semua entitas. Default ke false
.
Format
{
"runtime": {
"cache": {
"enabled": <boolean>
}
}
}
Contoh
Dalam contoh ini, cache dinonaktifkan.
{
"runtime": {
"cache": {
"enabled": false
}
}
}
TTL dalam hitungan detik (Runtime cache)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.cache |
ttl-seconds |
Integer | ❌ Tidak | 5 |
Mengonfigurasi nilai time-to-live (TTL) dalam hitungan detik untuk item yang di-cache. Setelah waktu ini berlalu, item secara otomatis diprakarsai dari cache. Nilai defaultnya adalah 5
detik.
Format
{
"runtime": {
"cache": {
"ttl-seconds": <integer>
}
}
}
Contoh
Dalam contoh ini, cache diaktifkan secara global dan semua item kedaluwarsa setelah 15 detik.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
Telemetri (runtime)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime |
telemetry |
benda | ❌ Tidak | Tidak |
Properti ini mengonfigurasi Application Insights untuk mempusatkan log API. Pelajari selengkapnya.
Format
{
"runtime": {
"telemetry": {
"application-insights": {
"enabled": <true; default: true> | <false>,
"connection-string": <string>
}
}
}
}
Application Insights (Runtime telemetri)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.telemetry |
application-insights |
benda | ✔️ Ya | Tidak |
Diaktifkan (telemetri Application Insights)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.telemetry.application-insights |
enabled |
Boolean | ❌ Tidak | Benar |
String koneksi (telemetri Application Insights)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
runtime.telemetry.application-insights |
connection-string |
tali | ✔️ Ya | Tidak |
Entitas
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
$root |
entities |
benda | ✔️ Ya | Tidak |
Bagian entities
berfungsi sebagai inti file konfigurasi, membuat jembatan antara objek database dan titik akhir API yang sesuai. Bagian ini memetakan objek database ke titik akhir yang terekspos. Bagian ini juga mencakup pemetaan properti dan definisi izin. Setiap entitas yang diekspos didefinisikan dalam objek khusus. Nama properti objek digunakan sebagai nama entitas untuk diekspos.
Bagian ini menentukan bagaimana setiap entitas dalam database diwakili dalam API, termasuk pemetaan dan izin properti. Setiap entitas dienkapsulasi dalam subbagiannya sendiri, dengan nama entitas bertindak sebagai kunci untuk referensi di seluruh konfigurasi.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true; default: true> | <false>,
"path": <string; default: "<entity-name>">,
"methods": <array of strings; default: ["GET", "POST"]>
},
"graphql": {
"enabled": <true; default: true> | <false>,
"type": {
"singular": <string>,
"plural": <string>
},
"operation": <"query" | "mutation"; default: "query">
},
"source": {
"object": <string>,
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>,
"parameters": {
"<parameter-name>": <string | number | boolean>
}
},
"mappings": {
"<database-field-name>": <string>
},
"relationships": {
"<relationship-name>": {
"cardinality": <"one" | "many">,
"target.entity": <string>,
"source.fields": <array of strings>,
"target.fields": <array of strings>,
"linking.object": <string>,
"linking.source.fields": <array of strings>,
"linking.target.fields": <array of strings>
}
},
"permissions": [
{
"role": <"anonymous" | "authenticated" | "custom-role-name">,
"actions": <array of strings>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": {
"database": <string>
}
}
]
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
source |
✔️ Ya | benda |
permissions |
✔️ Ya | Array |
rest |
❌ Tidak | benda |
graphql |
❌ Tidak | benda |
mappings |
❌ Tidak | benda |
relationships |
❌ Tidak | benda |
cache |
❌ Tidak | benda |
Contoh
Misalnya, objek JSON ini menginstruksikan pembangun API Data untuk mengekspos entitas GraphQL bernama User
dan titik akhir REST yang dapat dijangkau melalui jalur /User
. Tabel database dbo.User
mendukung entitas dan konfigurasi memungkinkan siapa pun mengakses titik akhir secara anonim.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
Contoh ini mendeklarasikan entitas User
. Nama ini User
digunakan di mana saja dalam file konfigurasi tempat entitas dirujuk. Jika tidak, nama entitas tidak relevan dengan titik akhir.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table",
"key-fields": ["Id"],
"parameters": {} // only when source.type = stored-procedure
},
"rest": {
"enabled": true,
"path": "/users",
"methods": [] // only when source.type = stored-procedure
},
"graphql": {
"enabled": true,
"type": {
"singular": "User",
"plural": "Users"
},
"operation": "query"
},
"mappings": {
"id": "Id",
"name": "Name",
"age": "Age",
"isAdmin": "IsAdmin"
},
"permissions": [
{
"role": "authenticated",
"actions": ["read"], // "execute" only when source.type = stored-procedure
"fields": {
"include": ["id", "name", "age", "isAdmin"],
"exclude": []
},
"policy": {
"database": "@claims.userId eq @item.id"
}
},
{
"role": "admin",
"actions": ["create", "read", "update", "delete"],
"fields": {
"include": ["*"],
"exclude": []
},
"policy": {
"database": "@claims.userRole eq 'UserAdmin'"
}
}
]
}
}
}
Sumber
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
source |
benda | ✔️ Ya | Tidak |
Konfigurasi {entity}.source
menghubungkan entitas yang diekspos API dan objek database yang mendasarnya. Properti ini menentukan tabel database, tampilan, atau prosedur tersimpan yang diwakili entitas, membuat tautan langsung untuk pengambilan dan manipulasi data.
Untuk skenario langsung di mana entitas memetakan langsung ke tabel database tunggal, properti sumber hanya memerlukan nama objek database tersebut. Kesederhanaan ini memfasilitasi penyiapan cepat untuk kasus penggunaan umum: "source": "dbo.User"
.
Format
{
"entities": {
"<entity-name>": {
"source": {
"object": <string>,
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>,
"parameters": { // only when source.type = stored-procedure
"<name>": <string | number | boolean>
}
}
}
}
}
Properti
Diperlukan | Jenis | |
---|---|---|
object |
✔️ Ya | tali |
type |
✔️ Ya | string enum |
parameters |
❌ Tidak | benda |
key-fields |
❌ Tidak | array string |
Contoh
1. Pemetaan Tabel Sederhana:
Contoh ini menunjukkan cara mengaitkan entitas User
dengan tabel sumber dbo.Users
.
SQL
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
Konfigurasi
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
2. Contoh Prosedur Tersimpan:
Contoh ini menunjukkan cara mengaitkan entitas User
dengan proc sumber dbo.GetUsers
.
SQL
CREATE PROCEDURE GetUsers
@IsAdmin BIT
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;
Konfigurasi
{
"entities": {
"User": {
"source": {
"type": "stored-procedure",
"object": "GetUsers",
"parameters": {
"IsAdmin": "boolean"
}
},
"mappings": {
"Id": "id",
"Name": "name",
"Age": "age",
"IsAdmin": "isAdmin"
}
}
}
}
Properti mappings
bersifat opsional untuk prosedur tersimpan.
Benda
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.source |
object |
tali | ✔️ Ya | Tidak |
Nama objek database yang akan digunakan. 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 atau dihilangkan.
Contoh
SQL
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
Konfigurasi
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
Notasi Alternatif Tanpa Skema dan Tanda Kurung:
Jika tabel berada dalam skema dbo
, Anda dapat menghilangkan skema atau tanda kurung:
{
"entities": {
"User": {
"source": {
"object": "Users",
"type": "table"
}
}
}
}
Jenis (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.source |
type |
tali | ✔️ Ya | Tidak |
Properti type
mengidentifikasi jenis objek database di belakang entitas, termasuk view
, table
, dan stored-procedure
. Properti ini diperlukan dan tidak memiliki nilai default.
Format
{
"entities": {
"<entity-name>": {
"type": <"view" | "stored-procedure" | "table">
}
}
}
Nilai
Nilai | Deskripsi |
---|---|
table |
Mewakili tabel. |
stored-procedure |
Mewakili prosedur tersimpan. |
view |
Mewakili tampilan. |
Contoh
1. Contoh Tabel:
SQL
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
Konfigurasi
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
2. Contoh Tampilan:
SQL
CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;
Konfigurasi
{
"entities": {
"AdminUsers": {
"source": {
"object": "dbo.AdminUsers",
"type": "view",
"key-fields": ["Id"]
},
"mappings": {
"Id": "id",
"Name": "name",
"Age": "age"
}
}
}
}
Catatan: Menentukan key-fields
penting untuk dilihat karena tidak memiliki kunci primer yang melekat.
3. Contoh Prosedur Tersimpan:
SQL
CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;
Konfigurasi
{
"entities": {
"User": {
"source": {
"type": "stored-procedure",
"object": "GetUsers",
"parameters": {
"IsAdmin": "boolean"
}
}
}
}
}
Bidang kunci
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.source |
key-fields |
array string | ❌ Tidak | Tidak |
Properti {entity}.key-fields
sangat diperlukan untuk entitas yang didukung oleh tampilan, sehingga Data API Builder tahu cara mengidentifikasi dan mengembalikan satu item. Jika type
diatur ke view
tanpa menentukan key-fields
, mesin menolak untuk memulai. Properti ini diizinkan dengan tabel dan prosedur tersimpan, tetapi tidak digunakan dalam kasus tersebut.
Penting
Properti ini diperlukan jika jenis objek adalah view
.
Format
{
"entities": {
"<entity-name>": {
"source": {
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>
}
}
}
}
Contoh: Menampilkan dengan Bidang Kunci
Contoh ini menggunakan tampilan dbo.AdminUsers
dengan Id
yang ditunjukkan sebagai bidang kunci.
SQL
CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;
Konfigurasi
{
"entities": {
"AdminUsers": {
"source": {
"object": "dbo.AdminUsers",
"type": "view",
"key-fields": ["Id"]
}
}
}
}
Parameter
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.source |
parameters |
benda | ❌ Tidak | Tidak |
Properti parameters
dalam entities.{entity}.source
digunakan untuk entitas yang didukung oleh prosedur tersimpan. Ini memastikan pemetaan nama parameter dan jenis data yang tepat yang diperlukan oleh prosedur tersimpan.
Penting
Properti parameters
diperlukan jika type
objek stored-procedure
dan parameter diperlukan.
Format
{
"entities": {
"<entity-name>": {
"source": {
"type": "stored-procedure",
"parameters": {
"<parameter-name-1>": <string | number | boolean>,
"<parameter-name-2>": <string | number | boolean>
}
}
}
}
}
Contoh 1: Prosedur Tersimpan Tanpa Parameter
SQL
CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;
Konfigurasi
{
"entities": {
"Users": {
"source": {
"object": "dbo.GetUsers",
"type": "stored-procedure"
}
}
}
}
Contoh 2: Prosedur Tersimpan Dengan Parameter
SQL
CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;
Konfigurasi
{
"entities": {
"User": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
}
}
}
}
Izin
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
permissions |
benda | ✔️ Ya | Tidak |
Bagian ini menentukan siapa yang dapat mengakses entitas terkait dan tindakan apa yang diizinkan. Izin ditentukan dalam hal peran dan operasi CRUD: create
, read
, update
, dan delete
. Bagian permissions
menentukan peran mana yang dapat mengakses entitas terkait dan menggunakan tindakan mana.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"actions": ["create", "read", "update", "delete", "execute", "*"]
}
]
}
}
}
Perbuatan | Deskripsi |
---|---|
create |
Memungkinkan pembuatan rekaman baru di entitas. |
read |
Memungkinkan membaca atau mengambil rekaman dari entitas. |
update |
Memungkinkan pembaruan rekaman yang ada di entitas. |
delete |
Memungkinkan penghapusan rekaman dari entitas. |
execute |
Memungkinkan menjalankan prosedur atau operasi tersimpan. |
* |
Memberikan semua operasi CRUD yang berlaku. |
Contoh
Contoh 1: Peran Anonim pada Entitas Pengguna
Dalam contoh ini, peran anonymous
didefinisikan dengan akses ke semua tindakan yang mungkin pada entitas User
.
{
"entities": {
"User": {
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
Contoh 2: Tindakan Campuran untuk Peran Anonim
Contoh ini menunjukkan cara mencampur tindakan string dan array objek untuk entitas User
.
{
"entities": {
"User": {
"permissions": [
{
"role": "anonymous",
"actions": [
{ "action": "read" },
"create"
]
}
]
}
}
}
Peran Anonim: Memungkinkan pengguna anonim membaca semua bidang kecuali bidang sensitif hipotetis (misalnya, secret-field
). Menggunakan "include": ["*"]
dengan "exclude": ["secret-field"]
menyembunyikan secret-field
sambil mengizinkan akses ke semua bidang lainnya.
Peran Terautentikasi : Memungkinkan pengguna terautentikasi membaca dan memperbarui bidang tertentu. Misalnya, secara eksplisit termasuk id
, name
, dan age
tetapi tidak termasuk isAdmin
dapat menunjukkan bagaimana pengecualian mengambil alih penyertaan.
Peran Admin: Admin dapat melakukan semua operasi (*
) pada semua bidang tanpa pengecualian. Menentukan "include": ["*"]
dengan array "exclude": []
kosong memberikan akses ke semua bidang.
Konfigurasi ini:
"fields": {
"include": [],
"exclude": []
}
secara efektif identik dengan:
"fields": {
"include": ["*"],
"exclude": []
}
Pertimbangkan juga penyiapan ini:
"fields": {
"include": [],
"exclude": ["*"]
}
Ini menentukan tidak ada bidang yang disertakan secara eksplisit dan semua bidang dikecualikan, yang biasanya membatasi akses sepenuhnya.
Praktis Menggunakan: Konfigurasi seperti itu mungkin tampak berlawanan karena membatasi akses ke semua bidang. Namun, ini dapat digunakan dalam skenario di mana peran melakukan tindakan tertentu (seperti membuat entitas) tanpa mengakses datanya.
Perilaku yang sama, tetapi dengan sintaks yang berbeda, adalah:
"fields": {
"include": ["Id", "Name"],
"exclude": ["*"]
}
Penyiapan ini mencoba untuk hanya menyertakan bidang Id
dan Name
, tetapi mengecualikan semua bidang karena kartubebas di exclude
.
Cara lain untuk mengekspresikan logika yang sama adalah:
"fields": {
"include": ["Id", "Name"],
"exclude": ["Id", "Name"]
}
Mengingat bahwa exclude
lebih diutamakan daripada include
, menentukan exclude: ["*"]
berarti semua bidang dikecualikan, bahkan yang ada di include
. Dengan demikian, pada pandangan pertama, konfigurasi ini mungkin tampaknya mencegah bidang apa pun dapat diakses.
Terbalik : Jika niatnya adalah memberikan akses hanya ke bidang Id
dan Name
, lebih jelas dan lebih dapat diandalkan untuk menentukan hanya bidang tersebut di bagian include
tanpa menggunakan wildcard pengecualian:
"fields": {
"include": ["Id", "Name"],
"exclude": []
}
Properti
Diperlukan | Jenis | |
---|---|---|
role |
✔️ Ya | tali |
actions (string-array)atau actions (object-array) |
✔️ Ya | array objek atau string |
Peranan
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.permissions |
role |
tali | ✔️ Ya | Tidak |
String yang berisi nama peran tempat izin yang ditentukan berlaku. Peran mengatur konteks izin tempat permintaan harus dijalankan. Untuk setiap entitas yang ditentukan dalam konfigurasi runtime, Anda dapat menentukan sekumpulan peran dan izin terkait yang menentukan bagaimana entitas dapat diakses melalui titik akhir REST dan GraphQL. Peran tidak aditif.
Data API Builder mengevaluasi permintaan dalam konteks satu peran:
Peranan | Deskripsi |
---|---|
anonymous |
Tidak ada token akses yang disajikan |
authenticated |
Token akses yang valid disajikan |
<custom-role> |
Token akses yang valid disajikan dan header HTTP X-MS-API-ROLE menentukan peran yang ada dalam token |
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <"anonymous" | "authenticated" | "custom-role">,
"actions": ["create", "read", "update", "delete", "execute", "*"],
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
}
}
]
}
}
}
Contoh
Contoh ini menentukan peran bernama reader
hanya dengan izin read
pada entitas User
.
{
"entities": {
"User": {
"permissions": [
{
"role": "reader",
"actions": ["read"]
}
]
}
}
}
Anda dapat menggunakan <custom-role>
saat token akses yang valid disajikan dan header HTTP X-MS-API-ROLE
disertakan, menentukan peran pengguna yang juga terkandung dalam klaim peran token akses. Di bawah ini adalah contoh permintaan GET ke entitas User
, termasuk token pembawa otorisasi dan header X-MS-API-ROLE
, pada /api
dasar titik akhir REST di localhost
menggunakan bahasa yang berbeda.
GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role
Tindakan (string-array)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.permissions |
actions |
oneOf [string, array] | ✔️ Ya | Tidak |
Array nilai string yang merinci operasi apa yang diizinkan untuk peran terkait. Untuk objek database table
dan view
, peran dapat menggunakan kombinasi tindakan create
, read
, update
, atau delete
. Untuk prosedur tersimpan, peran hanya dapat memiliki tindakan execute
.
Perbuatan | Operasi SQL |
---|---|
* |
Kartubebas, termasuk eksekusi |
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 |
Nota
Untuk prosedur tersimpan, tindakan kartubebas (*
) hanya meluas ke tindakan execute
. Untuk tabel dan tampilan, tabel diperluas ke create
, read
, update
, dan delete
.
Contoh
Contoh ini memberikan izin create
dan read
ke peran bernama contributor
dan izin delete
ke peran bernama auditor
pada entitas User
.
{
"entities": {
"User": {
"permissions": [
{
"role": "auditor",
"actions": ["delete"]
},
{
"role": "contributor",
"actions": ["read", "create"]
}
]
}
}
}
Contoh lain:
{
"entities": {
"User": {
"permissions": [
{
"role": "contributor",
"actions": ["read", "create"]
}
]
}
}
}
Tindakan (object-array)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.permissions |
actions |
array string | ✔️ Ya | Tidak |
Array objek tindakan yang merinci operasi yang diizinkan untuk peran terkait. Untuk objek table
dan view
, peran dapat menggunakan kombinasi create
, read
, update
, atau delete
. Untuk prosedur tersimpan, hanya execute
yang diizinkan.
Nota
Untuk prosedur tersimpan, tindakan kartubebas (*
) diperluas hanya ke execute
. Untuk tabel/tampilan, tabel diperluas ke create
, read
, update
, dan delete
.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <array of strings>,
"policy": <object>
}
]
}
]
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
action |
✔️ Ya | tali | Tidak |
fields |
❌ Tidak | array string | Tidak |
policy |
❌ Tidak | benda | Tidak |
Contoh
Contoh ini hanya memberikan izin read
ke peran auditor
pada 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"
}
}
]
}
]
}
}
}
Perbuatan
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.permissions.actions[] |
action |
tali | ✔️ Ya | Tidak |
Menentukan operasi tertentu yang diizinkan pada objek database.
Nilai
Tabel | Dilihat | Prosedur Tersimpan | Deskripsi | |
---|---|---|---|---|
create |
✔️ Ya | ✔️ Ya | ❌ Tidak | Membuat item baru |
read |
✔️ Ya | ✔️ Ya | ❌ Tidak | Membaca item yang sudah ada |
update |
✔️ Ya | ✔️ Ya | ❌ Tidak | Memperbarui atau mengganti item |
delete |
✔️ Ya | ✔️ Ya | ❌ Tidak | Hapus item |
execute |
❌ Tidak | ❌ Tidak | ✔️ Ya | Menjalankan operasi terprogram |
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": "<role>",
"actions": [
{
"action": "<string>",
"fields": {
"include": [/* fields */],
"exclude": [/* fields */]
},
"policy": {
"database": "<predicate>"
}
}
]
}
]
}
}
}
Contoh
Berikut adalah contoh di mana pengguna anonymous
diizinkan untuk execute
prosedur tersimpan dan read
dari tabel User
.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read"
}
]
}
]
},
"GetUser": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
}
}
Bidang
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.permissions.actions[] |
fields |
benda | ❌ Tidak | Tidak |
Spesifikasi terperinci di mana bidang tertentu diizinkan akses untuk objek database. Konfigurasi peran adalah jenis objek dengan dua properti internal, include
dan exclude
. Nilai-nilai ini mendukung secara terperinci menentukan kolom database (bidang) mana yang diizinkan akses di bagian fields
.
Format
{
"entities": {
<string>: {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": <object>
}
]
}
]
}
}
}
Contoh
Dalam contoh ini, peran anonymous
diizinkan untuk membaca dari semua bidang kecuali id
, tetapi dapat menggunakan semua bidang saat membuat item.
{
"entities": {
"Author": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"fields": {
"include": [ "*" ],
"exclude": [ "id" ]
}
},
{ "action": "create" }
]
}
]
}
}
}
Sertakan dan kecualikan bekerja sama. Kartubebas *
di bagian include
menunjukkan semua bidang. Bidang yang dicatat di bagian exclude
lebih diutamakan daripada bidang yang dicatat di bagian include
. Definisi yang diterjemahkan ke menyertakan semua bidang kecuali untuk bidang 'last_updated.'
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ],
// Include All Except Specific Fields
"fields": {
"include": [ "*" ],
"exclude": [ "secret-field" ]
}
},
{
"role": "authenticated",
"actions": [ "read", "update" ],
// Explicit Include and Exclude
"fields": {
"include": [ "id", "title", "secret-field" ],
"exclude": [ "secret-field" ]
}
},
{
"role": "author",
"actions": [ "*" ],
// Include All With No Exclusions (default)
"fields": {
"include": ["*"],
"exclude": []
}
}
]
}
Kebijakan
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.permissions.actions[] |
policy |
benda | ❌ Tidak | Tidak |
Bagian policy
, yang ditentukan per action
, menentukan aturan keamanan tingkat item (kebijakan database) yang membatasi hasil yang dikembalikan dari permintaan. Sub bagian database
menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <object>,
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
database |
✔️ Ya | tali | Tidak |
Deskripsi
Kebijakan database
: ekspresi seperti OData yang diterjemahkan ke dalam predikat kueri yang dievaluasi database, termasuk operator seperti eq
, lt
, dan gt
. Agar hasil dikembalikan untuk permintaan, predikat kueri permintaan yang diselesaikan dari kebijakan database harus dievaluasi ke true
saat mengeksekusi terhadap database.
Contoh Kebijakan Item | Predikat |
---|---|
@item.OwnerId eq 2000 |
WHERE Table.OwnerId = 2000 |
@item.OwnerId gt 2000 |
WHERE Table.OwnerId > 2000 |
@item.OwnerId lt 2000 |
WHERE Table.OwnerId < 2000 |
predicate
adalah ekspresi yang mengevaluasi ke TRUE atau FALSE. Predikat digunakan dalam kondisi pencarian klausa WHERE dan klausa HAVING, kondisi gabungan klausa FROM, dan konstruksi lain di mana nilai Boolean diperlukan. (Microsoft Learn Docs)
Kebijakan database
Dua jenis arahan dapat digunakan untuk mengelola kebijakan database saat menulis ekspresi kebijakan database:
Direktif | Deskripsi |
---|---|
@claims |
Mengakses klaim dalam token akses tervalidasi yang disediakan dalam permintaan |
@item |
Mewakili bidang entitas yang kebijakan databasenya ditentukan |
Nota
Saat autentikasi Azure Static Web Apps (EasyAuth) dikonfigurasi, sejumlah jenis klaim terbatas tersedia untuk digunakan dalam kebijakan database: identityProvider
, userId
, userDetails
, dan userRoles
. Untuk informasi selengkapnya, lihat dokumentasi data utama Klien Azure Static Web
Berikut adalah beberapa contoh kebijakan database:
@claims.userId eq @item.OwnerId
@claims.userId gt @item.OwnerId
@claims.userId lt @item.OwnerId
Penyusun API Data membandingkan nilai klaim UserId
dengan nilai bidang database OwnerId
. Payload hasil hanya mencakup rekaman yang memenuhi baik metadata permintaan dan ekspresi kebijakan database.
Keterbatasan
Kebijakan database didukung untuk tabel dan tampilan. Prosedur tersimpan tidak dapat dikonfigurasi dengan kebijakan.
Kebijakan database tidak mencegah permintaan dijalankan dalam database. Perilaku ini karena diselesaikan sebagai predikat dalam kueri yang dihasilkan yang diteruskan ke mesin database.
Kebijakan database hanya didukung untuk actions
membuat, membaca, memperbarui, dan menghapus. Karena tidak ada predikat dalam panggilan prosedur tersimpan, mereka tidak dapat ditambahkan.
Operator seperti OData yang didukung
Operator | Deskripsi | Sintaks Sampel |
---|---|---|
and |
LOGIS AND | "@item.status eq 'active' and @item.age gt 18" |
or |
LOGIS ATAU | "@item.region eq 'US' or @item.region eq 'EU'" |
eq |
Sama | "@item.type eq 'employee'" |
gt |
Lebih besar dari | "@item.salary gt 50000" |
lt |
Kurang | "@item.experience lt 5" |
Untuk informasi selengkapnya, lihat operator biner.
Operator | Deskripsi | Sintaks Sampel |
---|---|---|
- |
Meniadakan (numerik) | "@item.balance lt -100" |
not |
Negasi logis (NOT) | "not @item.status eq 'inactive'" |
Untuk informasi selengkapnya, lihat operator unary.
Pembatasan nama bidang entitas
-
Aturan: Harus dimulai dengan huruf atau garis bawah (
_
), diikuti hingga 127 huruf, garis bawah (_
), atau digit (0-9
). - Impact: Bidang yang tidak mematuhi aturan ini tidak dapat langsung digunakan dalam kebijakan database.
-
Solution: Gunakan bagian
mappings
untuk membuat alias untuk bidang yang tidak memenuhi konvensi penamaan ini; pemetaan memastikan semua bidang dapat disertakan dalam ekspresi kebijakan.
Memanfaatkan mappings
untuk bidang yang tidak sesuai
Jika nama bidang entitas Anda tidak memenuhi aturan sintaks OData atau Anda hanya ingin alias karena alasan lain, Anda dapat menentukan alias di bagian mappings
konfigurasi Anda.
{
"entities": {
"<entity-name>": {
"mappings": {
"<field-1-name>": <string>,
"<field-2-name>": <string>,
"<field-3-name>": <string>
}
}
}
}
Dalam contoh ini, field-1-name
adalah nama bidang database asli yang tidak memenuhi konvensi penamaan OData. Membuat peta ke field-1-name
dan field-1-alias
memungkinkan bidang ini direferensikan dalam ekspresi kebijakan database tanpa masalah. Pendekatan ini tidak hanya membantu mematuhi konvensi penamaan OData tetapi juga meningkatkan kejelasan dan aksesibilitas model data Anda dalam titik akhir GraphQL dan RESTful.
Contoh
Pertimbangkan entitas bernama Employee
dalam konfigurasi API Data yang menggunakan klaim dan arahan item. Ini memastikan akses data dikelola dengan aman berdasarkan peran pengguna dan kepemilikan entitas:
{
"entities": {
"Employee": {
"source": {
"object": "HRUNITS",
"type": "table",
"key-fields": ["employee NUM"],
"parameters": {}
},
"mappings": {
"employee NUM": "EmployeeId",
"employee Name": "EmployeeName",
"department COID": "DepartmentId"
},
"policy": {
"database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
}
}
}
}
Definisi Entitas: Entitas Employee
dikonfigurasi untuk antarmuka REST dan GraphQL, menunjukkan datanya dapat dikueri atau dimanipulasi melalui titik akhir ini.
Konfigurasi Sumber : Mengidentifikasi HRUNITS
dalam database, dengan employee NUM
sebagai bidang kunci.
Pemetaan: Alias digunakan untuk memetakan employee NUM
, employee Name
, dan department COID
untuk EmployeeId
, EmployeeName
, dan DepartmentId
, masing-masing, menyederhanakan nama bidang dan berpotensi mengaburkan detail skema database sensitif.
Policy Application: Bagian policy
menerapkan kebijakan database menggunakan ekspresi seperti OData. Kebijakan ini membatasi akses data kepada pengguna dengan peran SDM (@claims.role eq 'HR'
) atau kepada pengguna yang klaim UserId
nya cocok dengan EmployeeId
- alias bidang - dalam database (@claims.userId eq @item.EmployeeId
). Ini memastikan bahwa karyawan hanya dapat mengakses catatan mereka sendiri kecuali mereka termasuk dalam departemen SDM. Kebijakan dapat memberlakukan keamanan tingkat baris berdasarkan kondisi dinamis.
Basis data
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.permissions.actions.policy |
database |
benda | ✔️ Ya | Tidak |
Bagian policy
, yang ditentukan per action
, menentukan aturan keamanan tingkat item (kebijakan database) yang membatasi hasil yang dikembalikan dari permintaan. Sub bagian database
menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan.
Format
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
Properti ini menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan. String kebijakan adalah ekspresi OData yang diterjemahkan ke dalam kueri yang diprediksi dievaluasi oleh database. Misalnya, ekspresi kebijakan @item.OwnerId eq 2000
diterjemahkan ke predikat kueri WHERE <schema>.<object-name>.OwnerId = 2000
.
Nota
Predikat adalah ekspresi yang mengevaluasi ke TRUE
, FALSE
, atau UNKNOWN
. Predikat digunakan dalam:
- Kondisi pencarian klausa
WHERE
- Kondisi pencarian klausa
FROM
- Kondisi gabungan klausa
FROM
- Konstruksi lain di mana nilai boolean diperlukan.
Agar hasil dikembalikan untuk permintaan, predikat kueri permintaan yang diselesaikan dari kebijakan database harus dievaluasi ke true
saat mengeksekusi terhadap database.
Dua jenis arahan dapat digunakan untuk mengelola kebijakan database saat menulis ekspresi kebijakan database:
Deskripsi | |
---|---|
@claims |
Mengakses klaim dalam token akses tervalidasi yang disediakan dalam permintaan |
@item |
Mewakili bidang entitas yang kebijakan databasenya ditentukan |
Nota
Sejumlah jenis klaim terbatas tersedia untuk digunakan dalam kebijakan database saat autentikasi Azure Static Web Apps (EasyAuth) dikonfigurasi. Jenis klaim ini meliputi: identityProvider
, userId
, userDetails
, dan userRoles
. Untuk informasi selengkapnya, lihat data utama klien Azure Static Web Apps.
Contoh
Misalnya, ekspresi kebijakan dasar dapat mengevaluasi apakah bidang tertentu benar dalam tabel. Contoh ini mengevaluasi apakah bidang soft_delete
false
.
{
"entities": {
"Manuscripts": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.soft_delete eq false"
}
}
]
}
]
}
}
}
Predikat juga dapat mengevaluasi jenis direktif claims
dan item
. Contoh ini menarik bidang UserId
dari token akses dan membandingkannya dengan bidang owner_id
dalam tabel database target.
{
"entities": {
"Manuscript": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@claims.userId eq @item.owner_id"
}
}
]
}
]
}
}
}
Keterbatasan
- Kebijakan database didukung untuk tabel dan tampilan. Prosedur tersimpan tidak dapat dikonfigurasi dengan kebijakan.
- Kebijakan database tidak dapat digunakan untuk mencegah permintaan dijalankan dalam database. Batasan ini karena kebijakan database diselesaikan sebagai predikat kueri dalam kueri database yang dihasilkan. Mesin database pada akhirnya mengevaluasi kueri ini.
- Kebijakan database hanya didukung untuk
actions
create
,read
,update
, dandelete
. - Sintaks ekspresi OData kebijakan database hanya mendukung skenario ini.
- Operator biner termasuk, tetapi tidak terbatas pada;
and
,or
,eq
,gt
, danlt
. Untuk informasi selengkapnya, lihatBinaryOperatorKind
. - Operator unary seperti operator
-
(meniadakan) dannot
. Untuk informasi selengkapnya, lihatUnaryOperatorKind
.
- Operator biner termasuk, tetapi tidak terbatas pada;
- Kebijakan database juga memiliki batasan yang terkait dengan nama bidang.
- Nama bidang entitas yang dimulai dengan huruf atau garis bawah, diikuti oleh paling banyak 127 huruf, garis bawah, atau digit.
- Persyaratan ini sesuai spesifikasi OData. Untuk informasi selengkapnya, lihat Bahasa Definisi Skema Umum OData.
Ujung
Bidang yang tidak sesuai dengan batasan yang disebutkan tidak dapat direferensikan dalam kebijakan database. Sebagai solusinya, konfigurasikan entitas dengan bagian pemetaan untuk menetapkan alias yang sesuai dengan bidang.
GraphQL (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
graphql |
benda | ❌ Tidak | Tidak |
Objek ini menentukan apakah GraphQL diaktifkan dan nama yang digunakan untuk mengekspos entitas sebagai jenis GraphQL. Objek ini bersifat opsional dan hanya digunakan jika nama atau pengaturan default tidak cukup.
Segmen ini menyediakan untuk mengintegrasikan entitas ke dalam skema GraphQL. Ini memungkinkan pengembang untuk menentukan atau memodifikasi nilai default untuk entitas di GraphQL. Penyiapan ini memastikan skema secara akurat mencerminkan struktur dan konvensi penamaan yang dimaksud.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <true> (default) | <false>,
"type": {
"singular": <string>,
"plural": <string>
},
"operation": "query" (default) | "mutation"
}
}
}
}
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <boolean>,
"type": <string-or-object>,
"operation": "query" (default) | "mutation"
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
❌ Tidak | Boolean | Tidak |
type |
❌ Tidak | string atau objek | Tidak |
operation |
❌ Tidak | string enum | Tidak |
Contoh
Kedua contoh ini setara secara fungsional.
{
"entities": {
"Author": {
"graphql": true
}
}
}
{
"entities": {
"Author": {
"graphql": {
"enabled": true
}
}
}
}
Dalam contoh ini, entitas yang ditentukan Book
, menunjukkan bahwa kami berurusan dengan sekumpulan data yang terkait dengan buku dalam database. Konfigurasi untuk entitas Book
dalam segmen GraphQL menawarkan struktur yang jelas tentang bagaimana entitas tersebut harus diwakili dan berinteraksi dalam skema GraphQL.
Properti yang diaktifkan: Entitas Book
disediakan melalui GraphQL ("enabled": true
), yang berarti pengembang dan pengguna dapat mengkueri atau membius data buku melalui operasi GraphQL.
Jenis properti: Entitas diwakili dengan nama tunggal "Book"
dan nama jamak "Books"
dalam skema GraphQL. Perbedaan ini memastikan bahwa saat mengkueri satu buku atau beberapa buku, skema menawarkan jenis bernama intuitif (Book
untuk satu entri, Books
untuk daftar), meningkatkan kegunaan API.
properti Operasi: Operasi diatur ke "query"
, menunjukkan bahwa interaksi utama dengan entitas Book
melalui GraphQL dimaksudkan untuk mengkueri (mengambil) data daripada mengubah (membuat, memperbarui, atau menghapusnya). Penyiapan ini selaras dengan pola penggunaan umum di mana data buku lebih sering dibaca daripada yang dimodifikasi.
{
"entities": {
"Book": {
...
"graphql": {
"enabled": true,
"type": {
"singular": "Book",
"plural": "Books"
},
"operation": "query"
},
...
}
}
}
Jenis (entitas GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.graphql |
type |
oneOf [string, object] | ❌ Tidak | {entity-name} |
Properti ini menentukan konvensi penamaan untuk entitas dalam skema GraphQL. Ini mendukung nilai string skalar dan jenis objek. Nilai objek menentukan bentuk tunggal dan jamak. Properti ini memberikan kontrol terperinci atas keterbacaan skema dan pengalaman pengguna.
Format
{
"entities": {
<entity-name>: {
"graphql": {
"type": <string>
}
}
}
}
{
"entities": {
<entity-name>: {
"graphql": {
"type": {
"singular": <string>,
"plural": <string>
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
singular |
❌ Tidak | tali | Tidak |
plural |
❌ Tidak | tali | N/A (default: tunggal) |
Contoh
Untuk kontrol yang lebih besar atas jenis GraphQL, Anda dapat mengonfigurasi bagaimana nama tunggal dan jamak diwakili secara independen.
Jika plural
hilang atau dihilangkan (seperti nilai skalar) Penyusun API Data mencoba memangkas nama secara otomatis, ikuti aturan bahasa Inggris untuk pluralisasi (misalnya: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)
{
"entities" {
"<entity-name>": {
...
"graphql": {
...
"type": {
"singular": "User",
"plural": "Users"
}
}
}
}
}
Nama entitas kustom dapat ditentukan menggunakan parameter type
dengan nilai string. Dalam contoh ini, mesin membedakan secara otomatis antara varian tunggal dan jamak dari nama ini menggunakan aturan bahasa Inggris umum untuk pluralisasi.
{
"entities": {
"Author": {
"graphql": {
"type": "bookauthor"
}
}
}
}
Jika Anda memilih untuk menentukan nama secara eksplisit, gunakan properti type.singular
dan type.plural
. Contoh ini secara eksplisit mengatur kedua nama.
{
"entities": {
"Author": {
"graphql": {
"type": {
"singular": "bookauthor",
"plural": "bookauthors"
}
}
}
}
}
Kedua contoh tersebut setara secara fungsional. Keduanya mengembalikan output JSON yang sama untuk kueri GraphQL yang menggunakan nama entitas bookauthors
.
{
bookauthors {
items {
first_name
last_name
}
}
}
{
"data": {
"bookauthors": {
"items": [
{
"first_name": "Henry",
"last_name": "Ross"
},
{
"first_name": "Jacob",
"last_name": "Hancock"
},
...
]
}
}
}
Operasi (entitas GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.graphql |
operation |
string enum | ❌ Tidak | Tidak |
Untuk entitas yang dipetakan ke prosedur tersimpan, properti operation
menunjuk jenis operasi GraphQL (kueri atau mutasi) tempat prosedur tersimpan dapat diakses. Pengaturan ini memungkinkan organisasi logis dari skema dan kepatuhan terhadap praktik terbaik GraphQL, tanpa memengaruhi fungsionalitas.
Nota
Entitas ditentukan sebagai prosedur tersimpan dengan mengatur nilai properti {entity}.type
ke stored-procedure
. Dalam kasus prosedur tersimpan, jenis GraphQL baru executeXXXX dibuat secara otomatis. Namun, properti operation
memungkinkan pengembang untuk memaksa lokasi jenis tersebut ke bagian mutation
atau query
dari skema. Properti ini memungkinkan higene skema dan tidak ada dampak fungsional terlepas dari nilai operation
.
Jika hilang, default operation
adalah mutation
.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"operation": "query" (default) | "mutation"
}
}
}
}
Nilai
Berikut adalah daftar nilai yang diizinkan untuk properti ini:
Deskripsi | |
---|---|
query |
Prosedur tersimpan yang mendasar diekspos sebagai kueri |
mutation |
Prosedur tersimpan yang mendasar diekspos sebagai mutasi |
Contoh
Ketika operation
mutation
, skema GraphQL akan menyerupai:
type Mutation {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
Ketika operation
query
, skema GraphQL akan menyerupai:
Skema GraphQL akan menyerupai:
type Query {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
Nota
Properti operation
hanya tentang penempatan operasi dalam skema GraphQL, itu tidak mengubah perilaku operasi.
Diaktifkan (entitas GraphQL)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.graphql |
enabled |
Boolean | ❌ Tidak | Benar |
Mengaktifkan atau menonaktifkan titik akhir GraphQL. Mengontrol apakah entitas tersedia melalui titik akhir GraphQL. Beralih ke properti enabled
memungkinkan pengembang mengekspos entitas secara selektif dari skema GraphQL.
Format
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
}
REST (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
rest |
benda | ❌ Tidak | Tidak |
Bagian rest
dari file konfigurasi didedikasikan untuk menyempurnakan titik akhir RESTful untuk setiap entitas database. Kemampuan penyesuaian ini memastikan bahwa REST API yang diekspos cocok dengan persyaratan tertentu, meningkatkan kemampuan utilitas dan integrasinya. Ini mengatasi potensi ketidakcocokan antara pengaturan default yang disimpulkan dan perilaku titik akhir yang diinginkan.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>,
"path": <string; default: "<entity-name>">,
"methods": <array of strings; default: ["GET", "POST"]>
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
✔️ Ya | Boolean | Benar |
path |
❌ Tidak | tali | /<entity-name> |
methods |
❌ Tidak | array string | DAPAT |
Contoh
Kedua contoh ini setara secara fungsional.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
],
"rest": true
}
}
}
{
"entities": {
"Author": {
...
"rest": {
"enabled": true
}
}
}
}
Berikut adalah contoh lain konfigurasi REST untuk entitas.
{
"entities" {
"User": {
"rest": {
"enabled": true,
"path": "/User"
},
...
}
}
}
Diaktifkan (entitas REST)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.rest |
enabled |
Boolean | ❌ Tidak | Benar |
Properti ini bertindak sebagai pengalih untuk visibilitas entitas dalam REST API. Dengan mengatur properti enabled
ke true
atau false
, pengembang dapat mengontrol akses ke entitas tertentu, memungkinkan permukaan API yang disesuaikan yang selaras dengan persyaratan keamanan dan fungsionalitas aplikasi.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>
}
}
}
}
Jalur (entitas REST)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.rest |
path |
tali | ❌ Tidak | Tidak |
Properti path
menentukan segmen URI yang digunakan untuk mengakses entitas melalui REST API. Penyesuaian ini memungkinkan jalur titik akhir yang lebih deskriptif atau disederhanakan di luar nama entitas default, meningkatkan navigasi API dan integrasi sisi klien. Secara default, jalurnya adalah /<entity-name>
.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"path": <string; default: "<entity-name>">
}
}
}
}
Contoh
Contoh ini mengekspos entitas Author
menggunakan titik akhir /auth
.
{
"entities": {
"Author": {
"rest": {
"path": "/auth"
}
}
}
}
Metode (entitas REST)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.rest |
methods |
array string | ❌ Tidak | Tidak |
Berlaku khusus untuk prosedur tersimpan, properti methods
menentukan kata kerja HTTP mana (misalnya, GET, POST) yang dapat direspons prosedur. Metode memungkinkan kontrol yang tepat atas bagaimana prosedur tersimpan diekspos melalui REST API, memastikan kompatibilitas dengan standar RESTful dan harapan klien. Bagian ini menggaris bawahi komitmen platform terhadap fleksibilitas dan kontrol pengembang, memungkinkan desain API yang tepat dan intuitif yang disesuaikan dengan kebutuhan spesifik setiap aplikasi.
Jika dihilangkan atau hilang, default methods
adalah POST
.
Format
{
"entities": {
"<entity-name>": {
"rest": {
"methods": ["GET" (default), "POST"]
}
}
}
}
Nilai
Berikut adalah daftar nilai yang diizinkan untuk properti ini:
Deskripsi | |
---|---|
get |
Mengekspos permintaan HTTP GET |
post |
Mengekspos permintaan HTTP POST |
Contoh
Contoh ini menginstruksikan mesin bahwa prosedur tersimpan stp_get_bestselling_authors
hanya mendukung tindakan HTTP GET
.
{
"entities": {
"BestSellingAuthor": {
"source": {
"object": "dbo.stp_get_bestselling_authors",
"type": "stored-procedure",
"parameters": {
"depth": "number"
}
},
"rest": {
"path": "/best-selling-authors",
"methods": [ "get" ]
}
}
}
}
Pemetaan (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
mappings |
benda | ❌ Tidak | Tidak |
Bagian mappings
memungkinkan konfigurasi alias, atau nama yang diekspos, untuk bidang objek database. Nama yang diekspos yang dikonfigurasi berlaku untuk titik akhir GraphQL dan REST.
Penting
Untuk entitas dengan GraphQL diaktifkan, nama yang diekspos yang dikonfigurasi harus memenuhi persyaratan penamaan GraphQL. Untuk informasi selengkapnya, lihat spesifikasi 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>"
}
}
}
}
Contoh
Dalam contoh ini, bidang sku_title
dari objek database dbo.magazines
diekspos menggunakan nama title
. Demikian pula, bidang sku_status
diekspos sebagai status
di titik akhir REST dan GraphQL.
{
"entities": {
"Magazine": {
...
"mappings": {
"sku_title": "title",
"sku_status": "status"
}
}
}
}
Berikut adalah contoh pemetaan lainnya.
{
"entities": {
"Book": {
...
"mappings": {
"id": "BookID",
"title": "BookTitle",
"author": "AuthorName"
}
}
}
}
Pemetaan: Objek mappings
menautkan bidang database (BookID
, BookTitle
, AuthorName
) ke nama yang lebih intuitif atau standar (id
, title
, author
) yang digunakan secara eksternal. Alias ini melayani beberapa tujuan:
Clarity and Consistency: Ini memungkinkan penggunaan penamaan yang jelas dan konsisten di seluruh API, terlepas dari skema database yang mendasar. Misalnya,
BookID
dalam database diwakili sebagaiid
di API, membuatnya lebih intuitif bagi pengembang yang berinteraksi dengan titik akhir.GraphQL Compliance: Dengan menyediakan mekanisme untuk nama bidang alias, ini memastikan bahwa nama yang diekspos melalui antarmuka GraphQL mematuhi persyaratan penamaan GraphQL. Perhatian terhadap nama penting karena GraphQL memiliki aturan ketat tentang nama (misalnya, tanpa spasi, harus dimulai dengan huruf atau garis bawah, dll.). Misalnya, jika nama bidang database tidak memenuhi kriteria ini, nama tersebut dapat dinamai dengan nama yang sesuai melalui pemetaan.
Fleksibilitas: Aliasing ini menambahkan lapisan abstraksi antara skema database dan API, memungkinkan perubahan dalam satu tanpa mengharukan perubahan di yang lain. Misalnya, perubahan nama bidang dalam database tidak memerlukan pembaruan ke dokumentasi API atau kode sisi klien jika pemetaan tetap konsisten.
Obfuscation Nama Bidang : Pemetaan memungkinkan obfuscation nama bidang, yang dapat membantu mencegah pengguna yang tidak sah menyimpulkan informasi sensitif tentang skema database atau sifat data yang disimpan.
Melindungi Informasi Kepemilikan: Dengan mengganti nama bidang, Anda juga dapat melindungi nama kepemilikan atau logika bisnis yang mungkin diisyaratkan melalui nama bidang asli database.
Hubungan (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity} |
relationships |
benda | ❌ Tidak | Tidak |
Peta bagian ini mencakup sekumpulan definisi hubungan yang memetakan bagaimana entitas terkait dengan entitas lain yang terekspos. Definisi hubungan ini juga dapat secara opsional menyertakan detail pada objek database yang mendasar yang digunakan untuk mendukung dan menegakkan hubungan. Objek yang ditentukan di bagian ini diekspos sebagai bidang GraphQL di entitas terkait. Untuk informasi selengkapnya, lihat perincian hubungan penyusun API Data .
Nota
Hubungan hanya relevan dengan kueri GraphQL. Titik akhir REST hanya mengakses satu entitas sekaligus dan tidak dapat mengembalikan jenis berlapis.
Bagian relationships
menguraikan bagaimana entitas berinteraksi dalam penyusun API Data, merinci asosiasi, dan dukungan database potensial untuk hubungan ini. Properti relationship-name
untuk setiap hubungan diperlukan dan harus unik di semua hubungan untuk entitas tertentu. Nama kustom memastikan koneksi yang jelas dan dapat diidentifikasi dan mempertahankan integritas skema GraphQL yang dihasilkan dari konfigurasi ini.
Hubungan | Kardinalitas | Contoh |
---|---|---|
satu-ke-banyak | many |
Satu entitas kategori dapat berhubungan dengan banyak entitas todo |
banyak-ke-satu | one |
Banyak entitas todo dapat berhubungan dengan satu entitas kategori |
banyak ke banyak | many |
Satu entitas todo dapat berhubungan dengan banyak entitas pengguna, dan satu entitas pengguna dapat berhubungan dengan banyak entitas todo |
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>"]
}
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
cardinality |
✔️ Ya | string enum | Tidak |
target.entity |
✔️ Ya | tali | Tidak |
source.fields |
❌ Tidak | array string | Tidak |
target.fields |
❌ Tidak | array string | Tidak |
linking.<object-or-entity> |
❌ Tidak | tali | Tidak |
linking.source.fields |
❌ Tidak | array string | Tidak |
linking.target.fields |
❌ Tidak | array string | Tidak |
Contoh
Saat mempertimbangkan hubungan, yang terbaik adalah membandingkan perbedaan antara satu ke banyak , banyak ke satu , dan hubungan banyak ke banyak.
Satu-ke-banyak
Pertama, mari kita pertimbangkan contoh hubungan dengan entitas many
. Setiap Category
dapat memiliki beberapa entitas Book
terkait sementara setiap entitas Book
hanya dikaitkan dengan satu entitas Category
.
{
"entities": {
"Book": {
...
},
"Category": {
"relationships": {
"category_books": {
"cardinality": "many",
"target.entity": "Book",
"source.fields": [ "id" ],
"target.fields": [ "category_id" ]
}
}
}
}
}
Dalam contoh ini, daftar source.fields
menentukan bidang id
entitas sumber (Category
). Bidang ini digunakan untuk menyambungkan ke item terkait di entitas target
. Sebaliknya, daftar target.fields
menentukan bidang category_id
entitas target (Book
). Bidang ini digunakan untuk menyambungkan ke item terkait di entitas source
.
Dengan hubungan ini ditentukan, skema GraphQL yang terekspos yang dihasilkan harus menyerupai contoh ini.
type Category
{
id: Int!
...
books: [BookConnection]!
}
Banyak ke satu
Selanjutnya, pertimbangkan banyak ke satu yang mengatur kardinalitas ke one
. Entitas Book
yang diekspos dapat memiliki satu entitas Category
terkait. Entitas Category
dapat memiliki beberapa entitas Book
terkait.
{
"entities": {
"Book": {
"relationships": {
"books_category": {
"cardinality": "one",
"target.entity": "Category",
"source.fields": [ "category_id" ],
"target.fields": [ "id" ]
}
},
"Category": {
...
}
}
}
}
Di sini, daftar source.fields
menentukan bahwa bidang category_id
entitas sumber (Book
) mereferensikan bidang id
entitas target terkait (Category
). Sebaliknya, daftar target.fields
menentukan hubungan terbalik. Dengan hubungan ini, skema GraphQL yang dihasilkan sekarang mencakup pemetaan kembali dari Buku ke Kategori.
type Book
{
id: Int!
...
category: Category
}
Banyak ke banyak
Akhirnya, hubungan banyak ke banyak Book
dapat memiliki beberapa entitas Author
dan sebaliknya entitas Author
dapat memiliki beberapa entitas Book
.
{
"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": {
...
}
}
}
}
Dalam contoh ini, source.fields
dan target.fields
menunjukkan bahwa tabel hubungan menggunakan pengidentifikasi utama (id
) dari entitas sumber (Book
) dan target (Author
). Bidang linking.object
menentukan bahwa hubungan ditentukan dalam objek database dbo.books_authors
. Selanjutnya, linking.source.fields
menentukan bahwa bidang book_id
objek penautan mereferensikan bidang id
entitas Book
dan linking.target.fields
menentukan bahwa bidang author_id
objek penautan mereferensikan bidang id
entitas Author
.
Contoh ini dapat dijelaskan menggunakan skema GraphQL yang mirip dengan contoh ini.
type Book
{
id: Int!
...
authors: [AuthorConnection]!
}
type Author
{
id: Int!
...
books: [BookConnection]!
}
Kardinalitas
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
cardinality |
tali | ✔️ Ya | Tidak |
Menentukan apakah entitas sumber saat ini hanya terkait dengan satu instans entitas target atau beberapa.
Nilai
Berikut adalah daftar nilai yang diizinkan untuk properti ini:
Deskripsi | |
---|---|
one |
Sumber hanya berkaitan dengan satu rekaman dari target |
many |
Sumber dapat berhubungan dengan rekaman nol ke banyak dari target |
Entitas target
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
target.entity |
tali | ✔️ Ya | Tidak |
Nama entitas yang ditentukan di tempat lain dalam konfigurasi yang merupakan target hubungan.
Bidang sumber
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
source.fields |
Array | ❌ Tidak | Tidak |
Parameter opsional untuk menentukan bidang yang digunakan untuk pemetaan di entitas sumber
Ujung
Bidang ini tidak diperlukan jika ada kunci asing batasan pada database antara dua objek database yang dapat digunakan untuk menyimpulkan hubungan secara otomatis.
Bidang target
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
target.fields |
Array | ❌ Tidak | Tidak |
Parameter opsional untuk menentukan bidang yang digunakan untuk pemetaan di entitas target
Ujung
Bidang ini tidak diperlukan jika ada kunci asing batasan pada database antara dua objek database yang dapat digunakan untuk menyimpulkan hubungan secara otomatis.
Menautkan objek atau entitas
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
linking.object |
tali | ❌ Tidak | Tidak |
Untuk hubungan banyak ke banyak, nama objek atau entitas database yang berisi data yang diperlukan untuk menentukan hubungan antara dua entitas lain.
Menautkan bidang sumber
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
linking.source.fields |
Array | ❌ Tidak | Tidak |
Nama bidang objek atau entitas database yang terkait dengan entitas sumber.
Menautkan bidang target
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.relationships |
linking.target.fields |
Array | ❌ Tidak | Tidak |
Nama bidang objek atau entitas database yang terkait dengan entitas target.
Cache (entitas)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.cache |
enabled |
Boolean | ❌ Tidak | Palsu |
Mengaktifkan dan mengonfigurasi penembolokan untuk entitas.
Format
You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:
```json
{
"entities": {
"<entity-name>": {
"cache": {
"enabled": <true> (default) | <false>,
"ttl-seconds": <integer; default: 5>
}
}
}
}
Properti
Harta benda | Diperlukan | Jenis | Default |
---|---|---|---|
enabled |
❌ Tidak | Boolean | Palsu |
ttl-seconds |
❌ Tidak | Integer | 5 |
Contoh
Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 30 detik.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
}
Diaktifkan (Entitas cache)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.{entity}.cache |
enabled |
Boolean | ❌ Tidak | Palsu |
Mengaktifkan penembolokan untuk entitas.
Dukungan Objek Database
Jenis objek | Dukungan cache |
---|---|
Meja | ✅ Ya |
Melihat | ✅ Ya |
Prosedur Tersimpan | ✖️ Tidak |
Wadah | ✖️ Tidak |
Dukungan Header HTTP
Header Permintaan | Dukungan cache |
---|---|
no-cache |
✖️ Tidak |
no-store |
✖️ Tidak |
max-age |
✖️ Tidak |
public |
✖️ Tidak |
private |
✖️ Tidak |
etag |
✖️ Tidak |
Format
{
"entities": {
"<entity-name>": {
"cache": {
"enabled": <boolean> (default: false)
}
}
}
}
Contoh
Dalam contoh ini, cache dinonaktifkan.
{
"entities": {
"Author": {
"cache": {
"enabled": false
}
}
}
}
TTL dalam hitungan detik (Entitas cache)
Ortu | Harta benda | Jenis | Diperlukan | Default |
---|---|---|---|---|
entities.cache |
ttl-seconds |
Integer | ❌ Tidak | 5 |
Mengonfigurasi nilai time-to-live (TTL) dalam hitungan detik untuk item yang di-cache. Setelah waktu ini berlalu, item secara otomatis diprakarsai dari cache. Nilai defaultnya adalah 5
detik.
Format
{
"entities": {
"<entity-name>": {
"cache": {
"ttl-seconds": <integer; inherited>
}
}
}
}
Contoh
Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 15 detik. Ketika dihilangkan, pengaturan ini mewarisi pengaturan global atau default.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
}
Konten terkait
- referensi
Functions - referensi antarmuka baris perintah (CLI)