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 o 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 os 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/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})]"
    }
  ]
}

API CRUD protegida com o 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 o Microsoft Entra. Todas as ações são protegidas com um escopo. CrudApiPlugin valida o público-alvo do token, o emissor e o escopo.

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

API CRUD protegida com o 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 o Microsoft Entra. As ações são protegidas com escopos específicos. CrudApiPlugin valida o público-alvo do token, o emissor e o escopo.

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

Propriedades do arquivo de API

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

Você pode consultar a 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 de EntraAuthConfig

Ao configurar a propriedade auth para entra, você deve definir a propriedade entraAuthConfig. 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ê define em uma ação, ela substitui a configuração de arquivo de API para essa ação específica.

A propriedade entraAuthConfig tem as propriedades a seguir.

Propriedade	Descrição	Necessário	Inadimplência
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 não autorizada 401.	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 não autorizada 401.	Não	Nenhum
scopes	Especifique a matriz de escopos válidos. Quando especificado, o CrudApiPlugin controla se qualquer um dos escopos estiver presente no token. Se nenhum dos escopos estiver presente, CrudApiPlugin retornará uma resposta não autorizada 401.	Não	Nenhum
roles	Especifique a matriz de funções válidas. Quando especificado, o CrudApiPlugin controla se uma das funções estiver presente no token. Se nenhuma das funções estiver presente, CrudApiPlugin retornará uma resposta não autorizada 401.	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 não autorizada 401.	Não	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 não autorizada 401.	Não	false

Propriedades da ação

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

Propriedade	Descrição	Necessário	Inadimplência
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, entra.	Não	none
entraAuthConfig	Configuração da autenticação do 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.	Não	Depende da ação
query	Newtonsoft consulta JSONPath que o Proxy de Desenvolvimento usa para localizar os dados no arquivo de dados.	Não	Vazio
url	URL na qual o Proxy de Desenvolvimento expõe a ação. O Proxy de Desenvolvimento 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, 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 /customers/{customer-id} e o query como $.[?(@.id == {customer-id})], o Proxy de Desenvolvimento substituirá o parâmetro {customer-id} na consulta pelo valor da URL da solicitação.

Importante

O Proxy de Desenvolvimento implementa o JSONPath na propriedade query 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 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 de getOne, 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 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. Retornará 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 à coleção 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"
  }
]