Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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/DevProxy.Plugins.dll",
"configSection": "customersApi"
}
Esempio di configurazione
{
"customersApi": {
"$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.schema.json",
"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/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 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à di certificazione e l'ambito del token.
{
"$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 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 vengono protette con ambiti specifici. CrudApiPlugin convalida il gruppo di destinatari, l'autorità di certificazione e l'ambito del token.
{
"$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"]
}
}
]
}
Proprietà del file API
| Proprietà | Descrizione | Obbligatorio |
|---|---|---|
actions |
Elenco di azioni supportate dall'API. | Sì |
auth |
Determina se l'API è protetta o meno. Valori consentiti: none, entra.
none predefinita |
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 che contiene i dati per l'API. | Sì |
entraAuthConfig |
Configurazione per l'autenticazione di Microsoft Entra. | Sì, quando si configura auth per entra |
È possibile fare riferimento alla dataFile usando un percorso assoluto o relativo. Dev Proxy risolve i percorsi relativi relativamente al file di definizione dell'API.
Il dataFile deve definire una matrice JSON. La matrice può essere vuota oppure può contenere un set iniziale di oggetti.
Proprietà EntraAuthConfig
Quando si configura la proprietà auth per entra, è necessario definire la proprietà entraAuthConfig. 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 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 proprietà entraAuthConfig ha le proprietà seguenti.
| Proprietà | Descrizione | Obbligatorio | Predefinito |
|---|---|---|---|
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 non autorizzata 401. |
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à dell'azione
Ogni azione nell'elenco actions ha le proprietà seguenti.
| Proprietà | Descrizione | Obbligatorio | Predefinito |
|---|---|---|---|
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 auth per entra |
Nessuno |
method |
Metodo HTTP usato da Dev Proxy per esporre l'azione. | NO | Dipende dall'azione |
query |
Newtonsoft JSONPath query usata da Dev Proxy per trovare i dati nel file di dati. | NO | Vuoto |
url |
URL in cui Dev Proxy espone l'azione. Dev Proxy aggiunge l'URL all'URL di base. | NO | Vuoto |
L'URL specificato nella proprietà url può contenere parametri. È possibile definire i parametri eseguendo il wrapping del nome del parametro tra parentesi graffe, ad esempio {customer-id}. Quando si instrada la 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 il url come /customers/{customer-id} e il query come $.[?(@.id == {customer-id})], Dev Proxy sostituisce il parametro {customer-id} nella query con il valore dell'URL della richiesta.
Importante
Dev Proxy implementa JSONPath nella proprietà query usando Newtonsoft.Json. Esistono alcune limitazioni per usarlo, 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 risposta 404 Not Found.
Ogni tipo di azione ha un metodo HTTP predefinito. È possibile eseguire l'override del valore predefinito specificando la proprietà method. Ad esempio, il tipo di azione get ha un metodo predefinito di GET. Se invece si desidera utilizzare POST, specificare la proprietà method come POST.
La matrice actions ha definito una raccolta di azioni che si desidera simulare. È possibile definire più azioni per lo stesso metodo HTTP e lo stesso tipo di azione. Ad esempio, è possibile definire due azioni getOne, una che recupera un cliente in base al proprio ID e l'altra in base al proprio 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 | Metodo predefinito |
|---|---|---|
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 |
Unisce i dati della 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 dati as-is.
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"
}
]
Passo successivo
Collabora con noi su GitHub
L'origine di questo contenuto è disponibile in GitHub, in cui è anche possibile creare ed esaminare i problemi e le richieste pull. Per ulteriori informazioni, vedere la guida per i collaboratori.
