Bagikan melalui


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 , GraphQL, host, cache, dan telemetri.
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 di mana jumlah maksimum percobaan ulang lima. Durasi backoff coba lagi setelah permintaan berikutnya dihitung menggunakan rumus ini (dengan asumsi upaya coba lagi saat ini 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 Autentikasi dan kecualikan UserId dan argumen Kata Sandi dari string koneksi Anda: . Tidak adanya UserId dan properti string koneksi Kata Sandi 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;"
  • 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;"
  • 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;"
  • 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;"
  • 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;"

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:

  1. Prosedur Tersimpan (GetUser):

    • Prosedur memeriksa SESSION_CONTEXT untuk memvalidasi apakah pemanggil memiliki peran admin atau cocok dengan userId yang disediakan.
    • Akses tidak sah menghasilkan kesalahan.
  2. Konfigurasi JSON :

    • set-session-context diaktifkan untuk meneruskan metadata pengguna dari token akses ke database.
    • Properti parameters memetakan parameter userId 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.

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

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 pengecualian BadRequest.
  • 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 payload null. Kolom dengan default() tidak diabaikan selama UPDATE 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.

Diagram dukungan token web JSON di penyusun API Data.

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-sizesaat 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 parametersdiperlukan 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 App.

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 actionsmembuat, 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.

Untuk informasi selengkapnya, lihat predikat .

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_deletefalse.

{
  "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 actionscreate, read, update, dan delete.
  • Sintaks ekspresi OData kebijakan database hanya mendukung skenario ini.
    • Operator biner termasuk, tetapi tidak terbatas pada; and, or, eq, gt, dan lt. Untuk informasi selengkapnya, lihat BinaryOperatorKind .
    • Operator unary seperti operator - (meniadakan) dan not. Untuk informasi selengkapnya, lihat UnaryOperatorKind .
  • 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 operationmutation, skema GraphQL akan menyerupai:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Ketika operationquery, 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 sebagai id 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 yang diekspos memiliki hubungan satu-ke-banyak dengan entitas . Di sini, kardinalitas diatur ke 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 didefinisikan dengan kardinalitas dan lebih banyak metadata untuk menentukan objek database mana yang digunakan untuk membuat hubungan dalam database cadangan. Di sini, entitas 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 yang digunakan untuk menyambungkan ke item terkait 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.

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 yang digunakan untuk menyambungkan ke item terkait 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.

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