CrudApiPlugin

Mensimulasikan CRUD API dengan penyimpanan data dalam memori. Mengirim respons JSON. Mendukung CORS untuk penggunaan lintas domain dari aplikasi sisi klien. Secara opsional, mensimulasikan API CRUD yang diamankan dengan Microsoft Entra atau kunci API.

Cuplikan layar prompt perintah dengan Dev Proxy mensimulasikan CRUD API.

Contoh konfigurasi

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/rc.schema.json",
  "plugins": [
    {
      "name": "CrudApiPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "customersApi"
    }
  ],
  "customersApi": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/crudapiplugin.schema.json",
    "apiFile": "customers-api.json"
  }
}

Properti konfigurasi

Harta benda Deskripsi
apiFile Jalur ke file yang berisi definisi CRUD API

Opsi baris perintah

Tidak

Contoh file API

Berikut adalah beberapa contoh file API yang menentukan CRUD API untuk informasi tentang pelanggan.

API CRUD Anonim

Berikut ini adalah contoh file API yang mendefinisikan CRUD API anonim untuk informasi tentang pelanggan.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/crudapiplugin.apifile.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": [
    {
      "action": "getMany",
      "url": "?city={customer-city}",
      "query": "$.[?(@.city == '{customer-city}')]"
    },
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

CRUD API diamankan dengan Microsoft Entra menggunakan satu cakupan

Berikut ini adalah contoh file API yang menentukan CRUD API untuk informasi tentang pelanggan yang diamankan dengan Microsoft Entra. Semua tindakan diamankan dengan satu cakupan. CrudApiPlugin memvalidasi audiens token, penerbit, dan cakupan.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/crudapiplugin.apifile.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"]
  },
  "actions": [
    {
      "action": "getMany",
      "url": "?city={customer-city}",
      "query": "$.[?(@.city == '{customer-city}')]"
    },
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

CRUD API diamankan dengan kunci API

Berikut ini adalah contoh file API yang menentukan CRUD API untuk informasi tentang pelanggan yang diamankan dengan kunci API. CrudApiPlugin memeriksa kunci API di parameter header atau kueri yang ditentukan.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/crudapiplugin.apifile.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "apiKey",
  "apiKeyAuthConfig": {
    "apiKey": "my-secret-key",
    "headerName": "X-API-Key"
  },
  "actions": [
    {
      "action": "getMany",
      "url": "?city={customer-city}",
      "query": "$.[?(@.city == '{customer-city}')]"
    },
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

CRUD API diamankan dengan Microsoft Entra menggunakan cakupan tertentu

Berikut ini adalah contoh file API yang menentukan CRUD API untuk informasi tentang pelanggan yang diamankan dengan Microsoft Entra. Tindakan diamankan dengan cakupan tertentu. CrudApiPlugin memvalidasi audiens token, penerbit, dan cakupan.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v3.3.1/crudapiplugin.apifile.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com"
  },
  "actions": [
    {
      "action": "getMany",
      "url": "?city={customer-city}",
      "query": "$.[?(@.city == '{customer-city}')]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "getAll",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "create",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    }
  ]
}

Properti file API

Harta benda Deskripsi Diperlukan
actions Daftar tindakan yang didukung API. Ya
apiKeyAuthConfig Konfigurasi untuk autentikasi kunci API. Ya, saat Anda mengonfigurasi auth ke apiKey
auth Menentukan apakah API diamankan atau tidak. Nilai yang diizinkan: none, entra, dan apiKey. none default Tidak
baseUrl URL Dasar tempat Proksi Dev mengekspos URL. Dev Proxy menambahkan URL dasar ke URL yang Anda tentukan dalam tindakan. Ya
dataFile Jalur ke file yang berisi data untuk API. Ya
entraAuthConfig Konfigurasi untuk autentikasi Microsoft Entra. Ya, saat Anda mengonfigurasi auth ke entra

Anda dapat merujuk ke dataFile menggunakan jalur absolut atau relatif. Proksi Dev menyelesaikan jalur relatif relatif ke file definisi API.

dataFile harus menentukan array JSON. Array dapat kosong atau dapat berisi sekumpulan objek awal.

Properti ApiKeyAuthConfig

Saat mengonfigurasi properti auth ke apiKey, Anda harus menentukan properti apiKeyAuthConfig. Jika Anda tidak menentukannya, CrudApiPlugin menunjukkan peringatan dan API tersedia secara anonim.

Anda menentukan apiKeyAuthConfig pada file API. Ini berlaku untuk semua tindakan.

Properti apiKeyAuthConfig memiliki properti berikut.

Harta benda Deskripsi Diperlukan Bawaan
apiKey Kunci API valid yang harus ada dalam permintaan. Ya Tidak
headerName Nama header HTTP untuk membaca kunci API. Tidak Tidak
queryParameterName Nama parameter query-string untuk membaca kunci API. Tidak Tidak

Anda harus menentukan setidaknya salah satu dari headerName atau queryParameterName. Jika Anda menentukan keduanya, CrudApiPlugin memeriksa header terlebih dahulu. Jika header tidak berisi kunci API, plugin akan memeriksa parameter kueri.

Properti EntraAuthConfig

Saat mengonfigurasi properti auth ke entra, Anda harus menentukan properti entraAuthConfig. Jika Anda tidak menentukannya, CrudApiPlugin menunjukkan peringatan dan API tersedia secara anonim.

Anda dapat menentukan entraAuthConfig pada file API dan pada setiap tindakan API. Saat Anda menentukannya pada file API, itu berlaku untuk semua tindakan. Saat Anda menentukannya pada tindakan, tindakan ini mengambil alih konfigurasi file API untuk tindakan khusus ini.

Properti entraAuthConfig memiliki properti berikut.

Harta benda Deskripsi Diperlukan Bawaan
audience Tentukan audiens yang valid untuk token. Jika ditentukan, CrudApiPlugin membandingkan audiens dari token dengan audiens ini. Jika berbeda, CrudApiPlugin mengembalikan respons 401 Tidak Sah. Tidak Tidak
issuer Tentukan penerbit token yang valid. Jika ditentukan, CrudApiPlugin membandingkan penerbit dari token dengan penerbit ini. Jika berbeda, CrudApiPlugin mengembalikan respons 401 Tidak Sah. Tidak Tidak
scopes Tentukan array cakupan yang valid. Jika ditentukan, CrudApiPlugin mengontrol apakah salah satu cakupan ada pada token. Jika tidak ada cakupan, CrudApiPlugin mengembalikan respons 401 Tidak Sah. Tidak Tidak
roles Tentukan array peran yang valid. Jika ditentukan, CrudApiPlugin mengontrol apakah salah satu peran ada pada token. Jika tidak ada peran, CrudApiPlugin mengembalikan respons 401 Tidak Sah. Tidak Tidak
validateLifetime Atur ke true untuk CrudApiPlugin untuk memvalidasi jika token belum kedaluwarsa. Ketika CrudApiPlugin mendeteksi token yang kedaluwarsa, crudApiPlugin mengembalikan respons 401 Tidak Sah. Tidak false
validateSigningKey Atur ke true untuk CrudApiPlugin untuk memvalidasi apakah token autentik. Ketika CrudApiPlugin mendeteksi token dengan tanda tangan yang tidak valid (misalnya, karena Anda memodifikasi token secara manual), token mengembalikan respons 401 Tidak Sah. Tidak false

Properti tindakan

Setiap tindakan dalam daftar actions memiliki properti berikut.

Harta benda Deskripsi Diperlukan Bawaan
action Menentukan bagaimana Proksi Dev berinteraksi dengan data. Nilai yang mungkin: getAll, getOne, getMany, create, merge, update, delete. Ya Tidak
auth Menentukan apakah tindakan diamankan atau tidak. Nilai yang diizinkan: none, entra, dan apiKey. Tidak none
entraAuthConfig Konfigurasi untuk autentikasi Microsoft Entra. Ya, saat Anda mengonfigurasi auth ke entra Tidak
method Metode HTTP yang digunakan Dev Proxy untuk mengekspos tindakan. Tidak Bergantung pada tindakan
query Newtonsoft kueri JSONPath yang digunakan Dev Proxy untuk menemukan data dalam file data. Tidak Kosong
url URL tempat Dev Proxy mengekspos tindakan. Proksi Dev menambahkan URL ke URL dasar. URL dapat berisi parameter jalur dan string kueri dalam kurung kurawal. Tidak Kosong

URL yang ditentukan dalam url properti dapat berisi parameter jalur dan string kueri. Anda menentukan parameter dengan membungkus nama parameter dalam kurung kurawal, misalnya, /{customer-id} atau ?city={customer-city}. Parameter string kueri harus mewakili nilai parameter lengkap. Saat merutekan permintaan, Dev Proxy mengganti parameter dengan nilai dari URL permintaan.

Anda bisa menggunakan parameter yang sama dalam kueri. Misalnya, jika Anda menentukan url sebagai /{customer-id} dan query sebagai $.[?(@.id == {customer-id})], Dev Proxy menggantikan parameter {customer-id} dalam kueri dengan nilai dari URL permintaan. Jika Anda mendefinisikan url sebagai ?city={customer-city} dan query sebagai $.[?(@.city == '{customer-city}')], panggilan ?city=Redmond mengembalikan pelanggan di Redmond.

Proksi Dev cocok dengan parameter string kueri secara independen dari urutannya. Anda dapat menggunakan nilai harfiah, seperti ?status=active, dan menyertakan parameter string kueri dalam permintaan yang tidak ditentukan dalam tindakan. Untuk mengambil parameter string kueri berulang, tentukan parameter yang sama beberapa kali. Proksi Dev cocok dengan parameter berulang berdasarkan posisinya. Contohnya:

{
  "action": "getMany",
  "url": "?id={first-id}&id={second-id}",
  "query": "$.[?(@.id == {first-id} || @.id == {second-id})]"
}

Penting

Proksi Dev menggunakan tindakan pertama yang cocok dengan metode HTTP, jalur, dan parameter string kueri yang dikonfigurasi. Tentukan tindakan khusus kueri sebelum tindakan yang cocok dengan metode dan jalur yang sama tanpa parameter string kueri.

Penting

Dev Proxy mengimplementasikan JSONPath di properti query menggunakan Newtonsoft.Json. Ada beberapa batasan untuk menggunakannya seperti, hanya mendukung tanda kutip tunggal. Sebelum mengirimkan masalah, pastikan untuk memvalidasi kueri Anda.

Ketika plugin tidak dapat menemukan data dalam file data menggunakan kueri, plugin mengembalikan respons 404 Not Found.

Setiap jenis tindakan memiliki metode HTTP default. Anda dapat mengambil alih default dengan menentukan properti method. Misalnya, jenis tindakan get memiliki metode default GET. Jika Anda ingin menggunakan POST sebagai gantinya, tentukan properti method sebagai POST.

Array actions menentukan kumpulan tindakan yang ingin Anda tirukan. Anda dapat menentukan beberapa tindakan untuk metode HTTP dan jenis tindakan yang sama. Misalnya, Anda dapat menentukan dua tindakan getOne, satu yang mengambil pelanggan dengan ID mereka dan yang lain dengan alamat email mereka. Pastikan untuk menentukan URL unik untuk setiap tindakan.

Tindakan

Dev Proxy mendukung tindakan berikut untuk CRUD API.

Perbuatan Deskripsi Metode default
getAll Mengembalikan semua item dari file data. GET
getOne Mengembalikan satu item dari file data. Gagal saat kueri cocok dengan beberapa item. GET
getMany Mengembalikan beberapa item dari file data. Mengembalikan array kosong jika kueri tidak cocok dengan item apa pun. GET
create Menambahkan item baru ke pengumpulan data. POST
merge Menggabungkan data dari permintaan dengan data dari file data. PATCH
update Mengganti data dalam file data dengan data dari permintaan. PUT
delete Menghapus item dari file data. DELETE

Saat Anda membuat item baru menggunakan tindakan create, plugin tidak memvalidasi bentuknya dan menambahkannya ke pengumpulan data as-is.

Contoh file data

[
  {
    "id": 1,
    "name": "Contoso",
    "address": "1 Microsoft Way",
    "city": "Redmond"
  },
  {
    "id": 2,
    "name": "Fabrikam",
    "address": "4567 Main St",
    "city": "Buffalo"
  }
]

Langkah selanjutnya

Mensimulasikan CRUD API

  • Terakhir diperbarui pada