CrudApiPlugin

模拟具有内存中数据存储的 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 文件示例

下面是几个 API 文件示例，这些文件定义有关客户信息的 CRUD 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身份验证的配置。	是，当你将 配置为authentra

可以使用绝对路径或相对路径来引用 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 Unauthorized 响应。	否	无
roles	指定有效角色的数组。 指定时，CrudApiPlugin 控制令牌上是否存在任一角色。 如果这两个角色都不存在，CrudApiPlugin 将返回“401 未授权”响应。	否	无
validateLifetime	将 设置为 true ，以便 CrudApiPlugin 验证令牌是否未过期。 当 CrudApiPlugin 检测到过期的令牌时，它将返回“401 未授权”响应。	否	false
validateSigningKey	将 设置为 true ，以便 CrudApiPlugin 验证令牌是否真实。 例如，当 CrudApiPlugin 检测到签名无效的令牌 (时，由于你手动修改了令牌) ，它将返回“401 未授权”响应。	否	false

操作属性

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

属性	说明	必须	默认
action	定义开发代理与数据交互的方式。 可能的值：getAll、、getOne、getManycreate、merge、update、delete。	是	无
auth	确定操作是否安全。 允许的值：none、entra。	否	none
entraAuthConfig	Microsoft Entra身份验证的配置。	是，当你将 配置为authentra	无
method	开发代理用于公开操作的 HTTP 方法。	否	取决于操作
query	开发代理用于查找数据文件中的数据的 Newtonsoft JSONPath 查询。	否	空
url	开发人员代理在其中公开操作的 URL。 开发代理将 URL 追加到基 URL。	否	空

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

可以在查询中使用相同的参数。 例如，如果将 定义为 ，query将 定义为 url/customers/{customer-id}$.[?(@.id == {customer-id})]，Dev Proxy 会将{customer-id}查询中的 参数替换为请求 URL 中的 值。

重要

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

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

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

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

操作

开发代理支持对 CRUD API 执行以下操作。

操作	说明	Default 方法
getAll	返回数据文件中的所有项。	GET
getOne	从数据文件返回单个项。 当查询与多个项匹配时失败。	GET
getMany	从数据文件中返回多个项。 如果查询与任何项都不匹配，则返回空数组。	GET
create	向数据收集添加新项。	POST
merge	将请求中的数据与数据文件中的数据合并。	PATCH
update	将数据文件中的数据替换为请求中的数据。	PUT
delete	从数据文件中删除项。	DELETE

使用 create 操作创建新项时，插件不会验证其形状，并按原样将其添加到数据收集。

数据文件示例

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