CrudApiPlugin

Simula uma API CRUD com um armazenamento de dados na memória. Envia respostas JSON. Dá suporte ao CORS para uso entre domínios de aplicativos do lado do cliente. Opcionalmente, simula APIs CRUD protegidas com Microsoft Entra.

Definição da instância do plug-in

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

Exemplo de configuração

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

Propriedades de configuração

Propriedade	Descrição
apiFile	Caminho para o arquivo que contém a definição da API CRUD

Opções de linha de comando

Nenhum

Exemplo de arquivo de API

A seguir estão vários exemplos de arquivos de API que definem uma API CRUD para obter informações sobre clientes.

API CRUD anônima

Veja a seguir um exemplo de um arquivo de API que define uma API CRUD anônima para obter informações sobre 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 com Microsoft Entra usando um único escopo

Veja a seguir um exemplo de um arquivo de API que define uma API CRUD para obter informações sobre clientes protegidos com Microsoft Entra. Todas as ações são protegidas com um escopo. CrudApiPlugin valida o público do token, o emissor e o escopo.

{
  "$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 com Microsoft Entra usando escopos específicos

Veja a seguir um exemplo de um arquivo de API que define uma API CRUD para obter informações sobre clientes protegidos com Microsoft Entra. As ações são protegidas com escopos específicos. CrudApiPlugin valida o público do token, o emissor e o escopo.

{
  "$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"]
      }
    }
  ]
}

Propriedades do arquivo de API

Propriedade	Descrição	Obrigatório
actions	Lista de ações compatíveis com a API.	Yes
auth	Determina se a API está protegida ou não. Valores Permitidos: none e entra. Padrão none	No
baseUrl	URL base em que o Proxy de Desenvolvimento expõe a URL. O Proxy de Desenvolvimento anexa a URL base às URLs definidas em ações.	Yes
dataFile	Caminho para o arquivo que contém os dados da API.	Yes
entraAuthConfig	Configuração para autenticação Microsoft Entra.	Sim, quando você configura auth para entra

Você pode se referir ao dataFile usando um caminho absoluto ou relativo. O Proxy de Desenvolvimento resolve caminhos relativos relativamente ao arquivo de definição de API.

O dataFile deve definir uma matriz JSON. A matriz pode estar vazia ou pode conter um conjunto inicial de objetos.

Propriedades entraAuthConfig

Ao configurar a auth propriedade para entra, você deve definir a entraAuthConfig propriedade . Se você não defini-lo, CrudApiPlugin mostrará um aviso e a API estará disponível anonimamente.

Você pode definir entraAuthConfig no arquivo de API e em cada ação de API. Quando você o define no arquivo de API, ele se aplica a todas as ações. Quando você o define em uma ação, ela substitui a configuração de arquivo de API para essa ação específica.

A entraAuthConfig propriedade tem as propriedades a seguir.

Propriedade	Descrição	Obrigatório	Padrão
audience	Especifique o público-alvo válido para o token. Quando especificado, CrudApiPlugin compara o público-alvo do token com esse público-alvo. Se forem diferentes, CrudApiPlugin retornará uma resposta 401 Não autorizada.	Não	Nenhum
issuer	Especifique o emissor de token válido. Quando especificado, CrudApiPlugin compara o emissor do token com esse emissor. Se forem diferentes, CrudApiPlugin retornará uma resposta 401 Não autorizada.	Não	Nenhum
scopes	Especifique a matriz de escopos válidos. Quando especificado, CrudApiPlugin controla se um dos escopos está presente no token. Se nenhum dos escopos estiver presente, CrudApiPlugin retornará uma resposta 401 Não autorizada.	Não	Nenhum
roles	Especifique a matriz de funções válidas. Quando especificado, CrudApiPlugin controla se uma das funções está presente no token. Se nenhuma das funções estiver presente, CrudApiPlugin retornará uma resposta 401 Não autorizada.	Não	Nenhum
validateLifetime	Defina como true para o CrudApiPlugin para validar se o token não expirou. Quando CrudApiPlugin detecta um token expirado, ele retorna uma resposta 401 Não autorizada.	No	false
validateSigningKey	Defina como true para o CrudApiPlugin para validar se o token é autêntico. Quando CrudApiPlugin detecta um token com uma assinatura inválida (por exemplo, porque você modificou o token manualmente), ele retorna uma resposta 401 Não autorizada.	No	false

Propriedades da ação

Cada ação na actions lista tem as propriedades a seguir.

Propriedade	Descrição	Obrigatório	Padrão
action	Define como o Proxy de Desenvolvimento interage com os dados. Valores possíveis: getAll, getOne, , getMany, create, merge, update, delete.	Sim	Nenhum
auth	Determina se a ação está protegida ou não. Valores Permitidos: none e entra.	No	none
entraAuthConfig	Configuração para autenticação Microsoft Entra.	Sim, quando você configura auth para entra	Nenhum
method	Método HTTP que o Proxy de Desenvolvimento usa para expor a ação.	No	Depende da ação
query	Consulta Newtonsoft JSONPath que o Proxy de Desenvolvimento usa para localizar os dados no arquivo de dados.	No	Vazio
url	URL na qual o Proxy de Desenvolvimento expõe a ação. O Proxy de Desenvolvimento acrescenta a URL à URL base.	No	Vazio

A URL especificada na url propriedade pode conter parâmetros. Você define parâmetros encapsulando o nome do parâmetro em chaves, por exemplo, {customer-id}. Ao rotear a solicitação, o Proxy de Desenvolvimento substitui o parâmetro pelo valor da URL de solicitação.

Você pode usar o mesmo parâmetro na consulta. Por exemplo, se você definir o url como e o query como $.[?(@.id == {customer-id})]/customers/{customer-id} , o Proxy de Desenvolvimento substituirá o {customer-id} parâmetro na consulta pelo valor da URL de solicitação.

Importante

O Proxy de Desenvolvimento implementa o query JSONPath na propriedade usando Newtonsoft.Json. Há algumas limitações para usá-lo, como, ele dá suporte apenas a aspas simples. Antes de enviar um problema, certifique-se de validar sua consulta.

Quando o plug-in não consegue encontrar os dados no arquivo de dados usando a consulta, ele retorna uma 404 Not Found resposta.

Cada tipo de ação tem um método HTTP padrão. Você pode substituir o padrão especificando a method propriedade . Por exemplo, o get tipo de ação tem um método padrão de GET. Se você quiser usar POST , especifique a method propriedade como POST.

A actions matriz definiu uma coleção de ações que você deseja simular. Você pode definir várias ações para o mesmo método HTTP e tipo de ação. Por exemplo, você pode definir duas getOne ações, uma que recupera um cliente por sua ID e a outra pelo endereço de email. Certifique-se de definir URLs exclusivas para cada ação.

Ações

O Proxy de Desenvolvimento dá suporte às seguintes ações para APIs CRUD.

Ação	Descrição	Método Default
getAll	Retorna todos os itens do arquivo de dados.	GET
getOne	Retorna um único item do arquivo de dados. Falha quando a consulta corresponde a vários itens.	GET
getMany	Retorna vários itens do arquivo de dados. Retornará uma matriz vazia se a consulta não corresponder a nenhum item.	GET
create	Adiciona um novo item à coleção de dados.	POST
merge	Mescla os dados da solicitação com os dados do arquivo de dados.	PATCH
update	Substitui os dados no arquivo de dados pelos dados da solicitação.	PUT
delete	Exclui o item do arquivo de dados.	DELETE

Quando você cria um novo item usando uma create ação, o plug-in não valida sua forma e o adiciona à coleta de dados como está.

Exemplo de arquivo de dados

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