Delen via

CrudApiPlugin

  • Artikel

Simuleert een CRUD-API met een in-memory gegevensarchief. Hiermee worden JSON-antwoorden verzonden. Ondersteunt CORS voor gebruik tussen domeinen vanuit toepassingen aan de clientzijde. Simuleert eventueel CRUD-API's die zijn beveiligd met Microsoft Entra.

schermopname van een opdrachtprompt met Dev Proxy die een CRUD-API simuleert.

Definitie van invoegtoepassingexemplaren

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

Configuratievoorbeeld

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

Configuratie-eigenschappen

Eigenschap Beschrijving
apiFile Pad naar het bestand dat de definitie van de CRUD-API bevat

Opdrachtregelopties

Geen

Voorbeeld van API-bestand

Hieronder volgen enkele voorbeelden van API-bestanden die een CRUD-API definiëren voor informatie over klanten.

Anonieme CRUD-API

Hieronder volgt een voorbeeld van een API-bestand dat een anonieme CRUD-API definieert voor informatie over klanten.

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

CRUD-API die is beveiligd met Microsoft Entra met behulp van één bereik

Hieronder volgt een voorbeeld van een API-bestand dat een CRUD-API definieert voor informatie over klanten die zijn beveiligd met Microsoft Entra. Alle acties worden beveiligd met één bereik. CrudApiPlugin valideert de tokendoelgroep, verlener en het bereik.

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

CRUD-API die is beveiligd met Microsoft Entra met behulp van specifieke bereiken

Hieronder volgt een voorbeeld van een API-bestand dat een CRUD-API definieert voor informatie over klanten die zijn beveiligd met Microsoft Entra. Acties worden beveiligd met specifieke bereiken. CrudApiPlugin valideert de tokendoelgroep, verlener en het bereik.

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

Eigenschappen van API-bestanden

Eigenschap Beschrijving Vereist
actions Lijst met acties die door de API worden ondersteund. Ja
auth Bepaalt of de API is beveiligd of niet. Toegestane waarden: none, entra. Standaard none Nee
baseUrl Basis-URL waarbij dev proxy de URL beschikbaar maakt. Dev Proxy prependeert de basis-URL naar URL's die u in acties definieert. Ja
dataFile Pad naar het bestand dat de gegevens voor de API bevat. Ja
entraAuthConfig Configuratie voor Microsoft Entra-verificatie. Ja, wanneer u auth configureert voor entra

U kunt naar de dataFile verwijzen met behulp van een absoluut of een relatief pad. Met Dev Proxy worden relatieve paden relatief omgezet in het API-definitiebestand.

De dataFile moet een JSON-matrix definiëren. De matrix kan leeg zijn of kan een eerste set objecten bevatten.

Eigenschappen entraAuthConfig

Wanneer u de eigenschap auth configureert voor entra, moet u de eigenschap entraAuthConfig definiëren. Als u deze niet definieert, geeft CrudApiPlugin een waarschuwing weer en is de API anoniem beschikbaar.

U kunt entraAuthConfig definiëren voor het API-bestand en voor elke API-actie. Wanneer u het definieert in het API-bestand, is dit van toepassing op alle acties. Wanneer u deze definieert voor een actie, wordt de configuratie van het API-bestand voor deze specifieke actie overschreven.

De eigenschap entraAuthConfig heeft de volgende eigenschappen.

Eigenschap Beschrijving Vereist Verstek
audience Geef de geldige doelgroep voor het token op. Wanneer dit is opgegeven, vergelijkt CrudApiPlugin de doelgroep van het token met deze doelgroep. Als deze verschillen zijn, retourneert CrudApiPlugin een 401 Niet-geautoriseerd antwoord. Nee Geen
issuer Geef de geldige tokenverlener op. Wanneer dit is opgegeven, vergelijkt CrudApiPlugin de verlener van het token met deze verlener. Als deze verschillen zijn, retourneert CrudApiPlugin een 401 Niet-geautoriseerd antwoord. Nee Geen
scopes Geef de matrix van geldige bereiken op. Wanneer dit is opgegeven, bepaalt CrudApiPlugin of een van de bereiken aanwezig is op het token. Als geen van de bereiken aanwezig is, retourneert CrudApiPlugin een 401 Niet-geautoriseerd antwoord. Nee Geen
roles Geef de matrix van geldige rollen op. Wanneer dit is opgegeven, bepaalt CrudApiPlugin of een van de rollen aanwezig is op het token. Als geen van de rollen aanwezig is, retourneert CrudApiPlugin een 401 Niet-geautoriseerd antwoord. Nee Geen
validateLifetime Ingesteld op true voor de CrudApiPlugin om te controleren of het token niet is verlopen. Wanneer CrudApiPlugin een verlopen token detecteert, wordt een 401 Niet-geautoriseerd antwoord geretourneerd. Nee false
validateSigningKey Ingesteld op true voor de CrudApiPlugin om te controleren of het token authentiek is. Wanneer CrudApiPlugin een token detecteert met een ongeldige handtekening (bijvoorbeeld omdat u het token handmatig hebt gewijzigd), wordt een 401 Niet-geautoriseerd antwoord geretourneerd. Nee false

Actie-eigenschappen

Elke actie in de lijst actions heeft de volgende eigenschappen.

Eigenschap Beschrijving Vereist Verstek
action Definieert hoe Dev Proxy communiceert met de gegevens. Mogelijke waarden: getAll, getOne, getMany, create, merge, update, delete. Ja Geen
auth Bepaalt of de actie is beveiligd of niet. Toegestane waarden: none, entra. Nee none
entraAuthConfig Configuratie voor Microsoft Entra-verificatie. Ja, wanneer u auth configureert voor entra Geen
method Http-methode die door Dev Proxy wordt gebruikt om de actie beschikbaar te maken. Nee Afhankelijk van de actie
query Newtonsoft JSONPath query die dev proxy gebruikt om de gegevens in het gegevensbestand te vinden. Nee Leeg
url URL waar dev proxy de actie beschikbaar maakt op. Dev Proxy voegt de URL toe aan de basis-URL. Nee Leeg

De URL die is opgegeven in de eigenschap url kan parameters bevatten. U definieert parameters door de parameternaam in accolades te verpakken, bijvoorbeeld {customer-id}. Bij het routeren van de aanvraag vervangt Dev Proxy de parameter door de waarde van de aanvraag-URL.

U kunt dezelfde parameter in de query gebruiken. Als u bijvoorbeeld de url definieert als /customers/{customer-id} en de query als $.[?(@.id == {customer-id})], vervangt Dev Proxy de {customer-id} parameter in de query door de waarde van de aanvraag-URL.

Belangrijk

Dev Proxy implementeert JSONPath in de eigenschap query met behulp van Newtonsoft.Json. Er zijn enkele beperkingen voor het gebruik ervan, zoals het ondersteunt slechts enkele aanhalingstekens. Voordat u een probleem indient, moet u de query valideren.

Wanneer de invoegtoepassing de gegevens in het gegevensbestand niet kan vinden met behulp van de query, wordt er een 404 Not Found antwoord geretourneerd.

Elk actietype heeft een standaard HTTP-methode. U kunt de standaardwaarde overschrijven door de eigenschap method op te geven. Het actietype get heeft bijvoorbeeld een standaardmethode van GET. Als u in plaats daarvan POST wilt gebruiken, geeft u de eigenschap method op als POST.

De actions matrix heeft een verzameling acties gedefinieerd die u wilt mocken. U kunt meerdere acties definiëren voor dezelfde HTTP-methode en hetzelfde actietype. U kunt bijvoorbeeld twee getOne acties definiëren, een waarmee een klant wordt opgehaald op basis van hun id en de andere door het e-mailadres. Zorg ervoor dat u voor elke actie unieke URL's definieert.

Acties

Dev Proxy ondersteunt de volgende acties voor CRUD-API's.

Actie Beschrijving Standaardmethode
getAll Retourneert alle items uit het gegevensbestand. GET
getOne Retourneert één item uit het gegevensbestand. Mislukt wanneer de query overeenkomt met meerdere items. GET
getMany Retourneert meerdere items uit het gegevensbestand. Retourneert een lege matrix als de query niet overeenkomt met items. GET
create Hiermee voegt u een nieuw item toe aan de gegevensverzameling. POST
merge Hiermee worden de gegevens uit de aanvraag samengevoegd met de gegevens uit het gegevensbestand. PATCH
update Vervangt de gegevens in het gegevensbestand door de gegevens uit de aanvraag. PUT
delete Hiermee verwijdert u het item uit het gegevensbestand. DELETE

Wanneer u een nieuw item maakt met behulp van een create actie, valideert de invoegtoepassing de shape niet en voegt het toe aan de gegevensverzameling as-is.

Voorbeeld van gegevensbestand

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