CrudApiPlugin

Articolo
04/09/2024

Simula un'API CRUD con un archivio dati in memoria. Invia risposte JSON. Supporta CORS per l'utilizzo tra domini da applicazioni lato client. Facoltativamente, simula le API CRUD protette con Microsoft Entra.

Definizione dell'istanza del plug-in

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

Esempio di configurazione

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

Proprietà di configurazione

Proprietà	Descrizione
`apiFile`	Percorso del file contenente la definizione dell'API CRUD

Opzioni della riga di comando

Nessuno

Esempio di file API

Di seguito sono riportati diversi esempi di file API che definiscono un'API CRUD per informazioni sui clienti.

API CRUD anonima

Di seguito è riportato un esempio di file API che definisce un'API CRUD anonima per informazioni sui clienti.

{
  "$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 protetta con Microsoft Entra usando un singolo ambito

Di seguito è riportato un esempio di file API che definisce un'API CRUD per informazioni sui clienti protetti con Microsoft Entra. Tutte le azioni sono protette con un ambito. CrudApiPlugin convalida il gruppo di destinatari, l'autorità emittente del token e l'ambito.

{
  "$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 protetta con Microsoft Entra usando ambiti specifici

Di seguito è riportato un esempio di file API che definisce un'API CRUD per informazioni sui clienti protetti con Microsoft Entra. Le azioni sono protette con ambiti specifici. CrudApiPlugin convalida il gruppo di destinatari, l'autorità emittente del token e l'ambito.

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

Proprietà del file API

Proprietà	Descrizione	Obbligatoria
`actions`	Elenco di azioni supportate dall'API.	Sì
`auth`	Determina se l'API è protetta o meno. Valori consentiti: `none`, `entra`. Predefinito `none`	No
`baseUrl`	URL di base in cui Dev Proxy espone l'URL. Dev Proxy antepone l'URL di base agli URL definiti nelle azioni.	Sì
`dataFile`	Percorso del file contenente i dati per l'API.	Sì
`entraAuthConfig`	Configurazione per l'autenticazione di Microsoft Entra.	Sì, quando si configura in `authentra`

È possibile fare riferimento all'oggetto dataFile utilizzando un percorso assoluto o relativo. Dev Proxy risolve i percorsi relativi relativamente al file di definizione dell'API.

Deve dataFile definire una matrice JSON. La matrice può essere vuota oppure può contenere un set iniziale di oggetti.

Proprietà EntraAuthConfig

Quando si configura la auth proprietà su entra, è necessario definire la entraAuthConfig proprietà . Se non lo si definisce, CrudApiPlugin visualizza un avviso e l'API è disponibile in modo anonimo.

È possibile definire entraAuthConfig nel file dell'API e in ogni azione dell'API. Quando lo si definisce nel file API, si applica a tutte le azioni. Quando lo si definisce in un'azione, esegue l'override della configurazione del file API per questa azione specifica.

La entraAuthConfig proprietà ha le proprietà seguenti.

Proprietà	Descrizione	Obbligatoria	Default
`audience`	Specificare il gruppo di destinatari valido per il token. Se specificato, CrudApiPlugin confronta il gruppo di destinatari dal token con questo gruppo di destinatari. Se sono diversi, CrudApiPlugin restituisce una risposta 401 Non autorizzata.	No	nessuno
`issuer`	Specificare l'autorità emittente del token valida. Se specificato, CrudApiPlugin confronta l'autorità emittente dal token con questo emittente. Se sono diversi, CrudApiPlugin restituisce una risposta 401 Non autorizzata.	No	nessuno
`scopes`	Specificare la matrice di ambiti validi. Se specificato, CrudApiPlugin controlla se uno degli ambiti è presente nel token. Se nessuno degli ambiti è presente, CrudApiPlugin restituisce una risposta 401 Non autorizzata.	No	nessuno
`roles`	Specificare la matrice di ruoli validi. Se specificato, CrudApiPlugin controlla se uno dei ruoli è presente nel token. Se nessuno dei ruoli è presente, CrudApiPlugin restituisce una risposta 401 Non autorizzata.	No	nessuno
`validateLifetime`	Impostare su `true` per crudApiPlugin per verificare se il token non è scaduto. Quando CrudApiPlugin rileva un token scaduto, restituisce una risposta 401 Non autorizzata.	No	`false`
`validateSigningKey`	Impostare su `true` per crudApiPlugin per verificare se il token è autentico. Quando CrudApiPlugin rileva un token con una firma non valida, ad esempio perché il token è stato modificato manualmente, restituisce una risposta 401 Non autorizzata.	No	`false`

Proprietà delle azioni

Ogni azione nell'elenco actions ha le proprietà seguenti.

Proprietà	Descrizione	Obbligatoria	Default
`action`	Definisce il modo in cui Dev Proxy interagisce con i dati. Valori possibili: `getAll`, `getOne`, `getMany`, `create`, `merge`, `update`, . `delete`	Sì	Nessuno
`auth`	Determina se l'azione è protetta o meno. Valori consentiti: `none`, `entra`.	No	`none`
`entraAuthConfig`	Configurazione per l'autenticazione di Microsoft Entra.	Sì, quando si configura `authentra`	Nessuno
`method`	Metodo HTTP usato da Dev Proxy per esporre l'azione.	No	Dipende dall'azione
`query`	Query JSONPath Newtonsoft usata da Dev Proxy per trovare i dati nel file di dati.	No	Empty
`url`	URL in cui Dev Proxy espone l'azione in. Dev Proxy aggiunge l'URL all'URL di base.	No	Empty

L'URL specificato nella url proprietà può contenere parametri. È possibile definire i parametri eseguendo il wrapping del nome del parametro in parentesi graffe, ad esempio {customer-id}. Quando si esegue il routing della richiesta, Dev Proxy sostituisce il parametro con il valore dell'URL della richiesta.

È possibile usare lo stesso parametro nella query. Ad esempio, se si definisce url come /customers/{customer-id} e query$.[?(@.id == {customer-id})]come , Dev Proxy sostituisce il parametro nella query con il {customer-id} valore dell'URL della richiesta.

Importante

Dev Proxy implementa JSONPath nella query proprietà usando Newtonsoft.Json. Esistono alcune limitazioni per l'uso, ad esempio, supporta solo virgolette singole. Prima di inviare un problema, assicurarsi di convalidare la query.

Quando il plug-in non riesce a trovare i dati nel file di dati usando la query, restituisce una 404 Not Found risposta.

Ogni tipo di azione ha un metodo HTTP predefinito. È possibile eseguire l'override del valore predefinito specificando la method proprietà. Ad esempio, il get tipo di azione ha un metodo predefinito di GET. Se si vuole usare POST invece, specificare la method proprietà come POST.

La actions matrice ha definito una raccolta di azioni che si desidera simulare. È possibile definire più azioni per lo stesso metodo HTTP e tipo di azione. Ad esempio, è possibile definire due getOne azioni, una che recupera un cliente tramite il proprio ID e l'altra dall'indirizzo di posta elettronica. Assicurarsi di definire URL univoci per ogni azione.

Azioni

Dev Proxy supporta le azioni seguenti per le API CRUD.

Azione	Descrizione	Default (metodo)
`getAll`	Restituisce tutti gli elementi dal file di dati.	`GET`
`getOne`	Restituisce un singolo elemento dal file di dati. Ha esito negativo quando la query corrisponde a più elementi.	`GET`
`getMany`	Restituisce più elementi dal file di dati. Restituisce una matrice vuota se la query non corrisponde ad alcun elemento.	`GET`
`create`	Aggiunge un nuovo elemento alla raccolta dati.	`POST`
`merge`	Unire i dati dalla richiesta con i dati del file di dati.	`PATCH`
`update`	Sostituisce i dati nel file di dati con i dati della richiesta.	`PUT`
`delete`	Elimina l'elemento dal file di dati.	`DELETE`

Quando si crea un nuovo elemento usando un'azione create , il plug-in non convalida la forma e lo aggiunge alla raccolta di dati come è.

Esempio di file di dati

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

Share via