Bagikan melalui

CrudApiPlugin

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

Cuplikan layar prompt perintah dengan Dev Proxy mensimulasikan CRUD API.

Definisi instans plugin

{
  "name": "CrudApiPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
  "configSection": "customersApi"
}

Contoh konfigurasi

{
  "customersApi": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/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/v1.0.0/crudapiplugin.apifile.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": [
    {
      "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/v1.0.0/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": "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/v1.0.0/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": "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
auth Menentukan apakah API diamankan atau tidak. Nilai yang diizinkan: none, entra. 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 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. 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. Tidak Kosong

URL yang ditentukan dalam properti url dapat berisi parameter. Anda menentukan parameter dengan membungkus nama parameter dalam kurung kurawal, misalnya, {customer-id}. 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 /customers/{customer-id} dan query sebagai $.[?(@.id == {customer-id})], Dev Proxy menggantikan parameter {customer-id} dalam kueri dengan nilai dari URL permintaan.

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": "4567 Main St Buffalo, NY 98052"
  },
  {
    "id": 2,
    "name": "Fabrikam",
    "address": "4567 Main St Buffalo, NY 98052"
  }
]

Langkah selanjutnya

Mensimulasikan CRUD API

  • Last updated on