CrudApiPlugin

Simula uma API CRUD com um arquivo de dados dentro da memória. Envia respostas JSON. Suporta CORS para utilização entre domínios a partir de aplicações do lado do cliente. Opcionalmente, simula APIs CRUD protegidas com Microsoft Entra.

Definição da instância de 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 ficheiro que contém a definição da API CRUD

Opções da linha de comandos

Nenhuma

Exemplo de ficheiro de API

Seguem-se vários exemplos de ficheiros de API que definem uma API CRUD para obter informações sobre os clientes.

API CRUD Anónima

Segue-se um exemplo de um ficheiro de API que define uma API CRUD anónima para obter informações sobre os 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 através de um único âmbito

Segue-se um exemplo de um ficheiro 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 âmbito. CrudApiPlugin valida a audiência do token, o emissor e o â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 com Microsoft Entra através de âmbitos específicos

Segue-se um exemplo de um ficheiro de API que define uma API CRUD para obter informações sobre clientes protegidos com Microsoft Entra. As ações são protegidas com âmbitos específicos. CrudApiPlugin valida a audiência do token, o emissor e o â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"]
      }
    }
  ]
}

Propriedades do ficheiro de API

Propriedade	Descrição	Obrigatório
actions	Lista de ações suportadas pela API.	Yes
auth	Determina se a API está protegida ou não. Valores permitidos: none, entra. Predefinição none	No
baseUrl	URL base onde o Proxy de Programador expõe o URL. O Proxy de Programador prepara o URL base para URLs definidos em ações.	Yes
dataFile	Caminho para o ficheiro que contém os dados da API.	Yes
entraAuthConfig	Configuração para autenticação Microsoft Entra.	Sim, quando configurar auth para entra

Pode ver a dataFile utilização de um caminho absoluto ou relativo. O Proxy Dev resolve caminhos relativos relativamente para o ficheiro de definição da API.

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

Propriedades de EntraAuthConfig

Quando configurar a auth propriedade para entra, tem de definir a entraAuthConfig propriedade . Se não o definir, CrudApiPlugin mostra um aviso e a API está disponível anonimamente.

Pode definir entraAuthConfig no ficheiro da API e em cada ação da API. Quando o define no ficheiro da API, este aplica-se a todas as ações. Quando o define numa ação, substitui a configuração do ficheiro da API para esta ação específica.

A entraAuthConfig propriedade tem as seguintes propriedades.

Propriedade	Descrição	Obrigatório	Predefinição
audience	Especifique a audiência válida para o token. Quando especificado, CrudApiPlugin compara a audiência do token com esta audiência. Se forem diferentes, CrudApiPlugin devolve uma resposta 401 Não Autorizada.	No	Nenhuma
issuer	Especifique o emissor de tokens válido. Quando especificado, CrudApiPlugin compara o emissor do token com este emissor. Se forem diferentes, CrudApiPlugin devolve uma resposta 401 Não Autorizada.	No	Nenhuma
scopes	Especifique a matriz de âmbitos válidos. Quando especificado, CrudApiPlugin controla se um dos âmbitos está presente no token. Se nenhum dos âmbitos estiver presente, CrudApiPlugin devolve uma resposta 401 Não Autorizada.	No	Nenhuma
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 devolve uma resposta 401 Não Autorizada.	No	Nenhuma
validateLifetime	Defina como true para CrudApiPlugin para validar se o token não expirou. Quando CrudApiPlugin deteta um token expirado, devolve uma resposta 401 Não Autorizada.	No	false
validateSigningKey	Defina como true para CrudApiPlugin para validar se o token é autêntico. Quando CrudApiPlugin deteta um token com uma assinatura inválida (por exemplo, porque modificou o token manualmente), devolve uma resposta 401 Não Autorizada.	No	false

Propriedades da ação

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

Propriedade	Descrição	Obrigatório	Predefinição
action	Define como o Proxy de Programador interage com os dados. Valores possíveis: getAll, , getOne, getManycreate, merge, , . deleteupdate	Yes	Nenhuma
auth	Determina se a ação está protegida ou não. Valores permitidos: none, entra.	No	none
entraAuthConfig	Configuração para autenticação Microsoft Entra.	Sim, quando configurar auth para entra	Nenhuma
method	Método HTTP que o Proxy de Programador utiliza para expor a ação.	No	Depende da ação
query	Consulta Newtonsoft JSONPath que o Dev Proxy utiliza para localizar os dados no ficheiro de dados.	No	Vazio
url	URL em que o Proxy de Programador expõe a ação. O Proxy Dev acrescenta o URL ao URL base.	No	Vazio

O URL especificado na url propriedade pode conter parâmetros. Pode definir parâmetros ao encapsular o nome do parâmetro em chavetas, por exemplo, {customer-id}. Ao encaminhar o pedido, o Proxy Dev substitui o parâmetro pelo valor do URL do pedido.

Pode utilizar o mesmo parâmetro na consulta. Por exemplo, se definir como url/customers/{customer-id} e como query$.[?(@.id == {customer-id})], o Proxy Dev substitui o {customer-id} parâmetro na consulta pelo valor do URL do pedido.

Importante

O Dev Proxy implementa jSONPath na query propriedade com Newtonsoft.Json. Existem algumas limitações à sua utilização, como, por exemplo, suporta apenas plicas. Antes de submeter um problema, certifique-se de que valida a consulta.

Quando o plug-in não consegue localizar os dados no ficheiro de dados com a consulta, devolve uma 404 Not Found resposta.

Cada tipo de ação tem um método HTTP predefinido. Pode substituir a predefinição ao especificar a method propriedade . Por exemplo, o get tipo de ação tem um método predefinido de GET. Se quiser utilizar POST , especifique a method propriedade como POST.

A actions matriz definiu uma coleção de ações que pretende simular. Pode definir várias ações para o mesmo método HTTP e tipo de ação. Por exemplo, pode definir duas getOne ações, uma que obtém um cliente pelo respetivo ID e a outra pelo respetivo endereço de e-mail. Certifique-se de que define URLs exclusivos para cada ação.

Ações

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

Ação	Descrição	Método predefinido
getAll	Devolve todos os itens do ficheiro de dados.	GET
getOne	Devolve um único item do ficheiro de dados. Falha quando a consulta corresponde a vários itens.	GET
getMany	Devolve vários itens do ficheiro de dados. Devolve uma matriz vazia se a consulta não corresponder a itens.	GET
create	Adiciona um novo item à recolha de dados.	POST
merge	Intercala os dados do pedido com os dados do ficheiro de dados.	PATCH
update	Substitui os dados no ficheiro de dados pelos dados do pedido.	PUT
delete	Elimina o item do ficheiro de dados.	DELETE

Quando cria um novo item com uma create ação, o plug-in não valida a forma e adiciona-a à recolha de dados tal como está.

Exemplo de ficheiro de dados

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