CrudApiPlugin

Simuliert eine CRUD-API mit einem In-Memory-Datenspeicher. Sendet JSON-Antworten. Unterstützt CORS für die domänenübergreifende Verwendung von clientseitigen Anwendungen. Optional simuliert CRUD-APIs, die mit Microsoft Entra geschützt sind.

Definition von Plug-In-instance

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

Konfigurationsbeispiel

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

Konfigurationseigenschaften

Eigenschaft	BESCHREIBUNG
apiFile	Pfad zu der Datei, die die Definition der CRUD-API enthält

Befehlszeilenoptionen

Keine

API-Dateibeispiel

Es folgen mehrere Beispiele für API-Dateien, die eine CRUD-API für Informationen zu Kunden definieren.

Anonyme CRUD-API

Im Folgenden finden Sie ein Beispiel für eine API-Datei, die eine anonyme CRUD-API für Kundeninformationen definiert.

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

CRUD-API, die mit Microsoft Entra mithilfe eines einzelnen Bereichs geschützt ist

Im Folgenden finden Sie ein Beispiel für eine API-Datei, die eine CRUD-API für Informationen zu Kunden definiert, die mit Microsoft Entra geschützt sind. Alle Aktionen werden mit einem Bereich gesichert. CrudApiPlugin überprüft die Tokenzielgruppe, den Aussteller und den Bereich.

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

CRUD-API, die mit Microsoft Entra unter Verwendung bestimmter Bereiche gesichert ist

Im Folgenden finden Sie ein Beispiel für eine API-Datei, die eine CRUD-API für Informationen zu Kunden definiert, die mit Microsoft Entra geschützt sind. Aktionen werden mit bestimmten Bereichen geschützt. CrudApiPlugin überprüft die Tokenzielgruppe, den Aussteller und den Bereich.

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

API-Dateieigenschaften

Eigenschaft	BESCHREIBUNG	Erforderlich
actions	Liste der Aktionen, die von der API unterstützt werden.	Yes
auth	Bestimmt, ob die API gesichert ist oder nicht. Zulässige Werte: none, entra. Standard none	No
baseUrl	Basis-URL, in der der Dev Proxy die URL verfügbar macht. Der Dev Proxy stellt die Basis-URL den URLs voran, die Sie in Aktionen definieren.	Yes
dataFile	Pfad zu der Datei, die die Daten für die API enthält.	Yes
entraAuthConfig	Konfiguration für die Microsoft Entra-Authentifizierung.	Ja, wenn Sie für konfigurieren authentra

Sie können mit einem absoluten oder einem relativen Pfad auf die dataFile verweisen. Der Dev Proxy löst relative Pfade relativ zur API-Definitionsdatei auf.

Der dataFile muss ein JSON-Array definieren. Das Array kann leer sein oder einen anfänglichen Satz von Objekten enthalten.

EntraAuthConfig-Eigenschaften

Wenn Sie die auth -Eigenschaft auf entrakonfigurieren, müssen Sie die entraAuthConfig -Eigenschaft definieren. Wenn Sie sie nicht definieren, zeigt CrudApiPlugin eine Warnung an, und die API ist anonym verfügbar.

Sie können für die API-Datei und für jede API-Aktion definieren entraAuthConfig . Wenn Sie sie für die API-Datei definieren, gilt sie für alle Aktionen. Wenn Sie sie für eine Aktion definieren, wird die API-Dateikonfiguration für diese spezifische Aktion überschrieben.

Die entraAuthConfig -Eigenschaft verfügt über die folgenden Eigenschaften.

Eigenschaft	BESCHREIBUNG	Erforderlich	Standard
audience	Geben Sie die gültige Zielgruppe für das Token an. Wenn angegeben, vergleicht CrudApiPlugin die Zielgruppe aus dem Token mit dieser Zielgruppe. Wenn sie unterschiedlich sind, gibt CrudApiPlugin die Antwort 401 Nicht autorisiert zurück.	Nein	Keine
issuer	Geben Sie den gültigen Tokenaussteller an. Wenn angegeben, vergleicht CrudApiPlugin den Aussteller aus dem Token mit diesem Aussteller. Wenn sie unterschiedlich sind, gibt CrudApiPlugin die Antwort 401 Nicht autorisiert zurück.	Nein	Keine
scopes	Geben Sie das Array gültiger Bereiche an. Wenn angegeben, steuert CrudApiPlugin, ob einer der Bereiche im Token vorhanden ist. Wenn keiner der Bereiche vorhanden ist, gibt CrudApiPlugin die Antwort 401 Nicht autorisiert zurück.	Nein	Keine
roles	Geben Sie das Array gültiger Rollen an. Wenn angegeben, steuert CrudApiPlugin, ob eine der Rollen im Token vorhanden ist. Wenn keine der Rollen vorhanden ist, gibt CrudApiPlugin die Antwort 401 Nicht autorisiert zurück.	Nein	Keine
validateLifetime	Legen Sie auf true fest, damit crudApiPlugin überprüft, ob das Token nicht abgelaufen ist. Wenn CrudApiPlugin ein abgelaufenes Token erkennt, wird die Antwort 401 Nicht autorisiert zurückgegeben.	No	false
validateSigningKey	Legen Sie auf fest true , damit crudApiPlugin überprüft, ob das Token authentisch ist. Wenn CrudApiPlugin ein Token mit einer ungültigen Signatur erkennt (z. B. weil Sie das Token manuell geändert haben), wird die Antwort 401 Nicht autorisiert zurückgegeben.	No	false

Aktionseigenschaften

Jede Aktion in der actions Liste verfügt über die folgenden Eigenschaften.

Eigenschaft	BESCHREIBUNG	Erforderlich	Standard
action	Definiert, wie der Dev Proxy mit den Daten interagiert. Mögliche Werte: getAll, getOne, getMany, create, merge, update, , delete.	Ja	Keine
auth	Bestimmt, ob die Aktion gesichert ist oder nicht. Zulässige Werte: none, entra.	No	none
entraAuthConfig	Konfiguration für die Microsoft Entra-Authentifizierung.	Ja, wenn Sie für konfigurieren authentra	Keine
method	HTTP-Methode, die der Dev Proxy verwendet, um die Aktion verfügbar zu machen.	No	Hängt von der Aktion ab.
query	Newtonsoft JSONPath-Abfrage , die der Dev Proxy verwendet, um die Daten in der Datendatei zu suchen.	No	Leer
url	URL, in der der Dev Proxy die Aktion verfügbar macht. Der Dev Proxy fügt die URL an die Basis-URL an.	No	Leer

Die in der url -Eigenschaft angegebene URL kann Parameter enthalten. Sie definieren Parameter, indem Sie den Parameternamen in geschweifte Klammern umschließen, {customer-id}z. B. . Beim Weiterleiten der Anforderung ersetzt Dev Proxy den Parameter durch den Wert aus der Anforderungs-URL.

Sie können denselben Parameter in der Abfrage verwenden. Wenn Sie beispielsweise als url/customers/{customer-id} und als query$.[?(@.id == {customer-id})]definieren, ersetzt Dev Proxy den {customer-id} Parameter in der Abfrage durch den Wert aus der Anforderungs-URL.

Wichtig

Der Dev Proxy implementiert JSONPath in der query -Eigenschaft mithilfe von Newtonsoft.Json. Es gibt einige Einschränkungen bei der Verwendung, z. B. unterstützt er nur einzelne Anführungszeichen. Überprüfen Sie ihre Abfrage, bevor Sie ein Problem übermitteln.

Wenn das Plug-In die Daten in der Datendatei mithilfe der Abfrage nicht finden kann, gibt es eine 404 Not Found Antwort zurück.

Jeder Aktionstyp verfügt über eine HTTP-Standardmethode. Sie können die Standardeinstellung überschreiben, indem Sie die method -Eigenschaft angeben. Der Aktionstyp verfügt beispielsweise get über die Standardmethode GET. Wenn Sie stattdessen verwenden POST möchten, geben Sie die method -Eigenschaft als an POST.

Das actions Array hat eine Sammlung von Aktionen definiert, die Sie simulieren möchten. Sie können mehrere Aktionen für die gleiche HTTP-Methode und denselben Aktionstyp definieren. Sie können z. B. zwei getOne Aktionen definieren: eine, die einen Kunden anhand seiner ID abruft, und die andere nach seiner E-Mail-Adresse. Achten Sie darauf, für jede Aktion eindeutige URLs zu definieren.

Aktionen

Der Dev Proxy unterstützt die folgenden Aktionen für CRUD-APIs.

Aktion	BESCHREIBUNG	Standardmethode
getAll	Gibt alle Elemente aus der Datendatei zurück.	GET
getOne	Gibt ein einzelnes Element aus der Datendatei zurück. Tritt ein Fehler auf, wenn die Abfrage mit mehreren Elementen übereinstimmt.	GET
getMany	Gibt mehrere Elemente aus der Datendatei zurück. Gibt ein leeres Array zurück, wenn die Abfrage mit keinem Element übereinstimmt.	GET
create	Fügt der Datensammlung ein neues Element hinzu.	POST
merge	Führt die Daten aus der Anforderung mit den Daten aus der Datendatei zusammen.	PATCH
update	Ersetzt die Daten in der Datendatei durch die Daten aus der Anforderung.	PUT
delete	Löscht das Element aus der Datendatei.	DELETE

Wenn Sie ein neues Element mithilfe einer create Aktion erstellen, überprüft das Plug-In seine Form nicht und fügt es der Datensammlung unverändert hinzu.

Beispiel für eine Datendatei

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