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

下面是一个 API 文件的示例，该文件定义一个匿名 CRUD 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`	开发代理公开 URL 的基 URL。开发代理将基本 URL 追加到在作中定义的 URL。	是的
`dataFile`	包含 API 数据的文件的路径。	是的
`entraAuthConfig`	Microsoft Entra 身份验证的配置。	是的，将 `auth` 配置为 `entra`

可以使用绝对路径或相对路径引用 dataFile。开发代理将相对路径解析为 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`	设置为 `true` CrudApiPlugin 以验证令牌是否真实。当 CrudApiPlugin 检测到具有无效签名的令牌（例如，由于手动修改了令牌），它将返回 401 未授权响应。	不	`false`

作属性

actions 列表中的每个作具有以下属性。

财产	描述	必填	违约
`action`	定义开发代理如何与数据交互。可能的值：`getAll`、`getOne`、`getMany`、`create`、`merge`、`update`、`delete`。	是的	没有
`auth`	确定作是否受到保护。允许的值：`none`、`entra`。	不	`none`
`entraAuthConfig`	Microsoft Entra 身份验证的配置。	是的，将 `auth` 配置为 `entra`	没有
`method`	开发代理用于公开作的 HTTP 方法。	不	取决于作
`query`	Newtonsoft JSONPath 查询，开发人员代理使用该查询在数据文件中查找数据。	不	空
`url`	开发人员代理在其中公开作的 URL。开发代理将 URL 追加到基 URL。	不	空

url 属性中指定的 URL 可以包含参数。通过将参数名称包装在大括号中来定义参数，例如，{customer-id}。路由请求时，开发代理会将参数替换为请求 URL 中的值。

可以在查询中使用同一参数。例如，如果将 url 定义为 /customers/{customer-id}，并将 query 定义为 $.[?(@.id == {customer-id})]，则开发人员代理会将查询中的 {customer-id} 参数替换为请求 URL 中的值。

重要

开发人员代理使用 Newtonsoft.Json 在 query 属性中实现 JSONPath。使用它有一些限制，例如，它仅支持单引号。提交问题之前，请务必验证查询。

当插件使用查询找不到数据文件中的数据时，它将返回 404 Not Found 响应。

每个作类型都有一个默认的 HTTP 方法。可以通过指定 method 属性来替代默认值。例如，get作类型具有默认 GET方法。如果要改用 POST，请将 method 属性指定为 POST。

actions 数组定义了要模拟的作集合。可以为同一 HTTP 方法和作类型定义多个作。例如，可以定义两个 getOne作，一个作按其 ID 检索客户，另一个作由其电子邮件地址检索。请务必为每个作定义唯一 URL。

行动

开发代理支持 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"
  }
]

通过