CrudApiPlugin

發行項
03/07/2025

使用記憶體內部數據存放區模擬 CRUD API。傳送 JSON 回應。支援從用戶端應用程式使用跨網域的CORS。選擇性地模擬使用 Microsoft Entra 保護的 CRUD API。

外掛程式實例定義

{
  "name": "CrudApiPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
  "configSection": "customersApi"
}

組態範例

{
  "customersApi": {
    "apiFile": "customers-api.json"
  }
}

組態屬性

財產	描述
`apiFile`	包含 CRUD API 定義的檔案路徑

命令行選項

沒有

API 檔案範例

以下是定義 CRUD API 的數個 API 檔案範例，以取得客戶的相關信息。

匿名 CRUD API

以下是定義匿名 CRUD API 的 API 檔案範例，以取得客戶的相關信息。

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.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})]"
    }
  ]
}

使用單一範圍以 Microsoft Entra 保護的 CRUD API

以下是 API 檔案的範例，該檔案會定義 CRUD API，以取得使用 Microsoft Entra 保護的客戶相關信息。所有動作都會受到一個範圍保護。 CrudApiPlugin 會驗證令牌對象、簽發者和範圍。

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.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})]"
    }
  ]
}

使用特定範圍以 Microsoft Entra 保護的 CRUD API

以下是 API 檔案的範例，該檔案會定義 CRUD API，以取得使用 Microsoft Entra 保護的客戶相關信息。動作會受到特定範圍保護。 CrudApiPlugin 會驗證令牌對象、簽發者和範圍。

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.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"]
      }
    }
  ]
}

API 檔案屬性

財產	描述	必填
`actions`	API 支援的動作清單。	是的
`auth`	判斷 API 是否受到保護。允許的值：`none`、`entra`。默認 `none`	不
`baseUrl`	開發人員 Proxy 公開 URL 的基底 URL。開發人員 Proxy 會在動作中定義的 URL 前面加上基底 URL。	是的
`dataFile`	包含 API 資料之檔案的路徑。	是的
`entraAuthConfig`	Microsoft Entra 驗證的組態。	是，當您將 `auth` 設定為 `entra`

您可以使用絕對路徑或相對路徑來參考 dataFile。開發 Proxy 會相對解析 API 定義檔的相對路徑。

dataFile 必須定義 JSON 陣列。數位可以是空的，也可以包含一組初始物件。

EntraAuthConfig 屬性

當您將 auth 屬性設定為 entra時，您必須定義 entraAuthConfig 屬性。如果您未定義，CrudApiPlugin 會顯示警告，且 API 可供匿名使用。

您可以在 API 檔案和每個 API 動作上定義 entraAuthConfig。當您在 API 檔案上定義它時，它會套用至所有動作。當您在動作上定義它時，它會覆寫此特定動作的 API 檔案組態。

entraAuthConfig 屬性具有下列屬性。

財產	描述	必填	違約
`audience`	指定令牌的有效物件。指定時，CrudApiPlugin 會比較令牌中的對象與這個物件。如果不同，CrudApiPlugin 會傳回 401 未經授權回應。	不	沒有
`issuer`	指定有效的令牌簽發者。指定時，CrudApiPlugin 會比較令牌中的簽發者與這個簽發者。如果不同，CrudApiPlugin 會傳回 401 未經授權回應。	不	沒有
`scopes`	指定有效範圍的陣列。指定時，CrudApiPlugin 會控制令牌上是否有其中一個範圍。如果兩個範圍都沒有存在，CrudApiPlugin 會傳回 401 未經授權回應。	不	沒有
`roles`	指定有效角色的陣列。指定時，CrudApiPlugin 會控制令牌上是否有任一角色。如果兩個角色都不存在，CrudApiPlugin 會傳回 401 未經授權回應。	不	沒有
`validateLifetime`	設定為 `true` CrudApiPlugin，以驗證令牌是否已過期。當 CrudApiPlugin 偵測到過期的令牌時，它會傳回 401 未經授權回應。	不	`false`
`validateSigningKey`	將設定為 crudApiPlugin 的 `true`，以驗證令牌是否為正宗。當 CrudApiPlugin 偵測到具有無效簽章的令牌時（例如，因為您手動修改令牌），它會傳回 401 未經授權回應。	不	`false`

動作屬性

actions 清單中的每個動作都有下列屬性。

財產	描述	必填	違約
`action`	定義 Dev Proxy 如何與數據互動。可能的值：`getAll`、`getOne`、`getMany`、`create`、`merge`、`updatedelete`。	是的	沒有
`auth`	判斷動作是否受到保護。允許的值：`none`、`entra`。	不	`none`
`entraAuthConfig`	Microsoft Entra 驗證的組態。	是，當您將 `auth` 設定為 `entra`	沒有
`method`	開發 Proxy 用來公開動作的 HTTP 方法。	不	視動作而定
`query`	Newtonsoft JSONPath 查詢，開發人員 Proxy 用來尋找數據文件中的數據。	不	空
`url`	開發人員 Proxy 公開動作所在的URL。開發人員 Proxy 會將URL附加至基底URL。	不	空

url 屬性中指定的 URL 可以包含參數。您可以藉由將參數名稱包裝在大括弧中來定義參數，例如，{customer-id}。路由要求時，Dev Proxy 會將參數取代為來自要求URL的值。

您可以在查詢中使用相同的參數。例如，如果您將 url 定義為 /customers/{customer-id}，並將 query 定義為 $.[?(@.id == {customer-id})]，Dev Proxy 會將查詢中的 {customer-id} 參數取代為來自要求 URL 的值。

重要

Dev Proxy 會使用 Newtonsoft.Json，在 query 屬性中實作 JSONPath。使用它有一些限制，例如，它只支援單引號。提交問題之前，請務必驗證您的查詢。

當外掛程式使用查詢找不到資料檔中的數據時，它會傳回 404 Not Found 回應。

每個動作類型都有預設的 HTTP 方法。您可以藉由指定 method 屬性來覆寫預設值。例如，get 動作類型具有預設的 GET方法。如果您要改用 POST，請將 method 屬性指定為 POST。

actions 陣列定義了您想要仿真的動作集合。您可以針對相同的 HTTP 方法和動作類型定義多個動作。例如，您可以定義兩個 getOne 動作，其中一個動作會依其標識符擷取客戶，另一個則由其電子郵件地址擷取。請務必為每個動作定義唯一的URL。

行動

Dev Proxy 支援 CRUD API 的下列動作。

行動	描述	默認方法
`getAll`	傳回資料檔中的所有專案。	`GET`
`getOne`	從數據檔傳回單一專案。查詢符合多個項目時失敗。	`GET`
`getMany`	從數據檔傳回多個專案。如果查詢不符合任何專案，則傳回空陣列。	`GET`
`create`	將新專案加入至數據收集。	`POST`
`merge`	將要求中的數據與數據檔中的數據合併。	`PATCH`
`update`	以要求中的數據取代數據檔中的數據。	`PUT`
`delete`	從資料檔中刪除專案。	`DELETE`

當您使用 create 動作建立新專案時，外掛程式不會驗證其圖形，並將它新增至資料收集 as-is。

數據檔範例

[
  {
    "id": 1,
    "name": "Contoso",
    "address": "4567 Main St Buffalo, NY 98052"
  },
  {
    "id": 2,
    "name": "Fabrikam",
    "address": "4567 Main St Buffalo, NY 98052"
  }
]

共用方式為