Compartir a través de


CrudApiPlugin

Simula una API CRUD con un almacén de datos en memoria. Envía respuestas JSON. Admite CORS para el uso entre dominios desde aplicaciones del lado cliente. Opcionalmente, simula las API CRUD protegidas con Microsoft Entra.

Captura de pantalla de un símbolo del sistema con el proxy de desarrollo simulando una API CRUD.

Definición de instancia del complemento

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

Ejemplo de configuración

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

Propiedades de configuración

Propiedad Descripción
apiFile Ruta de acceso al archivo que contiene la definición de la API CRUD

Opciones de línea de comandos

None

Ejemplo de archivo de API

A continuación se muestran varios ejemplos de archivos de API que definen una API CRUD para obtener información sobre los clientes.

API CRUD anónima

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD anónima para obtener información sobre los clientes.

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

API CRUD protegida con Microsoft Entra mediante un único ámbito

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD para obtener información sobre los clientes protegidos con Microsoft Entra. Todas las acciones se protegen con un ámbito. CrudApiPlugin valida la audiencia del token, el emisor y el ámbito.

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

API CRUD protegida con Microsoft Entra mediante ámbitos específicos

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD para obtener información sobre los clientes protegidos con Microsoft Entra. Las acciones se protegen con ámbitos específicos. CrudApiPlugin valida la audiencia del token, el emisor y el ámbito.

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

Propiedades del archivo de API

Propiedad Descripción Requerido
actions Lista de acciones que admite la API.
auth Determina si la API está protegida o no. Valores permitidos: none, entra. Predeterminado none No
baseUrl Dirección URL base donde dev Proxy expone la dirección URL. El proxy de desarrollo antepone la dirección URL base a las direcciones URL que defina en acciones.
dataFile Ruta de acceso al archivo que contiene los datos de la API.
entraAuthConfig Configuración para la autenticación de Microsoft Entra. Sí, al configurar auth para entra

Puede hacer referencia a dataFile mediante una ruta de acceso absoluta o relativa. Dev Proxy resuelve rutas de acceso relativas relativas al archivo de definición de API.

dataFile debe definir una matriz JSON. La matriz puede estar vacía o puede contener un conjunto inicial de objetos.

Propiedades de EntraAuthConfig

Al configurar la auth propiedad en entra, debe definir la entraAuthConfig propiedad . Si no lo define, CrudApiPlugin muestra una advertencia y la API está disponible de forma anónima.

Puede definir entraAuthConfig en el archivo de API y en cada acción de API. Al definirlo en el archivo de API, se aplica a todas las acciones. Cuando se define en una acción, invalida la configuración del archivo de API para esta acción específica.

La entraAuthConfig propiedad tiene las siguientes propiedades.

Propiedad Descripción Obligatorio Valor predeterminado
audience Especifique la audiencia válida para el token. Cuando se especifica, CrudApiPlugin compara la audiencia del token con esta audiencia. Si son diferentes, CrudApiPlugin devuelve una respuesta 401 No autorizada. No None
issuer Especifique el emisor de tokens válido. Cuando se especifica, CrudApiPlugin compara el emisor del token con este emisor. Si son diferentes, CrudApiPlugin devuelve una respuesta 401 No autorizada. No None
scopes Especifique la matriz de ámbitos válidos. Cuando se especifica, CrudApiPlugin controla si alguno de los ámbitos está presente en el token. Si ninguno de los ámbitos está presente, CrudApiPlugin devuelve una respuesta 401 No autorizada. No None
roles Especifique la matriz de roles válidos. Cuando se especifica, CrudApiPlugin controla si alguno de los roles está presente en el token. Si ninguno de los roles está presente, CrudApiPlugin devuelve una respuesta 401 No autorizada. No None
validateLifetime Establézcalo true en para que CrudApiPlugin valide si el token no ha expirado. Cuando CrudApiPlugin detecta un token expirado, devuelve una respuesta 401 No autorizada. No false
validateSigningKey Establézcalo true en para que CrudApiPlugin valide si el token es auténtico. Cuando CrudApiPlugin detecta un token con una firma no válida (por ejemplo, porque ha modificado el token manualmente), devuelve una respuesta 401 No autorizada. No false

Propiedades de la acción

Cada acción de la actions lista tiene las siguientes propiedades.

Propiedad Descripción Obligatorio Valor predeterminado
action Define cómo interactúa Dev Proxy con los datos. Valores posibles: getAll, , getManygetOne, create, merge, update. delete None
auth Determina si la acción está protegida o no. Valores permitidos: none, entra. No none
entraAuthConfig Configuración para la autenticación de Microsoft Entra. Sí, al configurar auth para entra None
method Método HTTP que usa dev Proxy para exponer la acción. No Depende de la acción
query Consulta newtonsoft JSONPath que usa el proxy de desarrollo para buscar los datos en el archivo de datos. No Vacío
url Dirección URL en la que dev Proxy expone la acción. El proxy de desarrollo anexa la dirección URL a la dirección URL base. No Vacío

La dirección URL especificada en la url propiedad puede contener parámetros. Para definir parámetros, encapsula el nombre del parámetro en llaves, por ejemplo, {customer-id}. Al enrutar la solicitud, Dev Proxy reemplaza el parámetro por el valor de la dirección URL de la solicitud.

Puede usar el mismo parámetro en la consulta. Por ejemplo, si define como url/customers/{customer-id} y query como $.[?(@.id == {customer-id})], Dev Proxy reemplaza el {customer-id} parámetro de la consulta por el valor de la dirección URL de la solicitud.

Importante

Dev Proxy implementa JSONPath en la query propiedad mediante Newtonsoft.Json. Hay algunas limitaciones para usarla, como, por ejemplo, solo admite comillas simples. Antes de enviar un problema, asegúrese de validar la consulta.

Cuando el complemento no encuentra los datos en el archivo de datos mediante la consulta, devuelve una 404 Not Found respuesta.

Cada tipo de acción tiene un método HTTP predeterminado. Puede invalidar el valor predeterminado especificando la method propiedad . Por ejemplo, el get tipo de acción tiene un método predeterminado de GET. Si quiere usar POST en su lugar, especifique la method propiedad como POST.

La actions matriz definió una colección de acciones que desea simular. Puede definir varias acciones para el mismo método HTTP y tipo de acción. Por ejemplo, puede definir dos getOne acciones, una que recupere un cliente por su identificador y el otro por su dirección de correo electrónico. Asegúrese de definir direcciones URL únicas para cada acción.

Acciones

Dev Proxy admite las siguientes acciones para las API CRUD.

Acción Descripción Default (método)
getAll Devuelve todos los elementos del archivo de datos. GET
getOne Devuelve un único elemento del archivo de datos. Se produce un error cuando la consulta coincide con varios elementos. GET
getMany Devuelve varios elementos del archivo de datos. Devuelve una matriz vacía si la consulta no coincide con ningún elemento. GET
create Agrega un nuevo elemento a la colección de datos. POST
merge Combina los datos de la solicitud con los datos del archivo de datos. PATCH
update Reemplaza los datos del archivo de datos por los datos de la solicitud. PUT
delete Elimina el elemento del archivo de datos. DELETE

Al crear un nuevo elemento mediante una create acción, el complemento no valida su forma y la agrega a la colección de datos tal cual.

Ejemplo de archivo de datos

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