CrudApiPlugin

Artículo
04/10/2024

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.

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.	Sí
`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.	Sí
`dataFile`	Ruta de acceso al archivo que contiene los datos de la API.	Sí
`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`	Sí	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"
  }
]

Compartir a través de