Partilhar via

CrudApiPlugin

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

Captura de tela de um prompt de comando com Dev Proxy simulando uma API CRUD.

Definição de instância de plug-in

{
  "name": "CrudApiPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
  "configSection": "customersApi"
}

Exemplo de configuração

{
  "customersApi": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.schema.json",
    "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 API

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

API CRUD anônima

A seguir está 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/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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 o Microsoft Entra usando um único escopo

A seguir está um exemplo de um arquivo de API que define uma API CRUD para obter informações sobre clientes protegidos com o 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/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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 o Microsoft Entra usando escopos específicos

A seguir está um exemplo de um arquivo de API que define uma API CRUD para obter informações sobre clientes protegidos com o 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/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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 API

Propriedade Descrição Necessário
actions Lista de ações suportadas pela API. Sim
auth Determina se a API é protegida ou não. Valores permitidos: none, entra. Padrão none Não
baseUrl URL base onde o Dev Proxy expõe a URL. O Dev Proxy precede a URL base para URLs que você define em ações. Sim
dataFile Caminho para o arquivo que contém os dados para a API. Sim
entraAuthConfig Configuração para autenticação do Microsoft Entra. Sim, quando você configura o auth para entra

Você pode fazer referência ao dataFile usando um caminho absoluto ou relativo. O Dev Proxy resolve caminhos relativos relativos 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 propriedade auth para entra, você deve definir a propriedade entraAuthConfig. Se você não defini-lo, CrudApiPlugin mostra um aviso e a API está disponível anonimamente.

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

A propriedade entraAuthConfig tem as seguintes propriedades.

Propriedade Descrição Necessário Inadimplência
audience Especifique o público válido para o token. Quando especificado, CrudApiPlugin compara o público do token com esse público. Se eles forem diferentes, CrudApiPlugin retorna 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 este emissor. Se eles forem diferentes, CrudApiPlugin retorna uma resposta 401 não autorizada. Não Nenhum
scopes Especifique a matriz de escopos válidos. Quando especificado, CrudApiPlugin controla se qualquer 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 qualquer 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 validar se o token não expirou. Quando CrudApiPlugin deteta um token expirado, ele retorna uma resposta 401 não autorizada. Não false
validateSigningKey Defina como true para o CrudApiPlugin validar se o token é autêntico. Quando CrudApiPlugin deteta um token com uma assinatura inválida (por exemplo, porque você modificou o token manualmente), ele retorna uma resposta 401 Não autorizada. Não false

Propriedades da ação

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

Propriedade Descrição Necessário Inadimplência
action Define como o Dev Proxy interage com os dados. Valores possíveis: getAll, getOne, getMany, create, merge, update, delete. Sim Nenhum
auth Determina se a ação é segura ou não. Valores permitidos: none, entra. Não none
entraAuthConfig Configuração para autenticação do Microsoft Entra. Sim, quando você configura o auth para entra Nenhum
method Método HTTP que o Dev Proxy usa para expor a ação. Não Depende da ação
query Newtonsoft JSONPath consulta que o Dev Proxy usa para localizar os dados no arquivo de dados. Não Vazio
url URL onde o Dev Proxy expõe a ação. O Dev Proxy acrescenta a URL à URL base. Não Vazio

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

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

Importante

Dev Proxy implementa JSONPath na propriedade query usando Newtonsoft.Json. Existem algumas limitações para usá-lo, tais como, ele suporta apenas aspas únicas. Antes de submeter um problema, certifique-se de que valida a sua consulta.

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

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

A matriz actions 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 ações getOne, uma que recupera um cliente por seu ID e outra por seu endereço de e-mail. Certifique-se de definir URLs exclusivos para cada ação.

Ações

O Dev Proxy suporta as seguintes ações para APIs CRUD.

Ação Descrição Método padrão
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. Retorna uma matriz vazia se a consulta não corresponder a nenhum item. GET
create Adiciona um novo item à coleta 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 ação create, o plug-in não valida sua forma e o adiciona à coleta de dados as-is.

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

Próximo passo

Simular uma API CRUD

  • Last updated on