Freigeben über

CrudApiPlugin

  • Artikel

Simuliert eine CRUD-API mit einem Speicher im Arbeitsspeicher. Sendet JSON-Antworten. Unterstützt CORS für die domänenübergreifende Nutzung von clientseitigen Anwendungen. Simuliert optional CRUD-APIs, die mit Microsoft Entra gesichert sind.

Screenshot einer Eingabeaufforderung mit Dev Proxy, die eine CRUD-API simuliert.

Definition der Plug-In-Instanz

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

Konfigurationsbeispiel

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

Konfigurationseigenschaften

Eigentum Beschreibung
apiFile Pfad zur Datei, die die Definition der CRUD-API enthält

Befehlszeilenoptionen

Nichts

API-Datei (Beispiel)

Im Folgenden sind mehrere Beispiele für API-Dateien aufgeführt, die eine CRUD-API für Informationen zu Kunden definieren.

Anonyme CRUD-API

Nachfolgend sehen Sie ein Beispiel für eine API-Datei, die eine anonyme CRUD-API für Informationen zu Kunden definiert.

{
  "$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 mit Microsoft Entra mit einem einzigen Bereich gesichert ist

Nachfolgend sehen Sie ein Beispiel für eine API-Datei, die eine CRUD-API für Informationen zu Kunden definiert, die mit Microsoft Entra gesichert sind. Alle Aktionen werden mit einem Bereich gesichert. CrudApiPlugin überprüft die Tokengruppe, den Aussteller und den Bereich.

{
  "$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 mit Microsoft Entra gesichert ist, mithilfe bestimmter Bereiche

Nachfolgend sehen Sie ein Beispiel für eine API-Datei, die eine CRUD-API für Informationen zu Kunden definiert, die mit Microsoft Entra gesichert sind. Aktionen werden mit bestimmten Bereichen gesichert. CrudApiPlugin überprüft die Tokengruppe, den Aussteller und den Bereich.

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

API-Dateieigenschaften

Eigentum Beschreibung Erforderlich
actions Liste der Aktionen, die von der API unterstützt werden. Ja
auth Bestimmt, ob die API gesichert ist oder nicht. Zulässige Werte: none, entra. Standard-none Nein
baseUrl Basis-URL, unter der Dev Proxy die URL verfügbar macht. Dev Proxy stellt die Basis-URL urLs vor, die Sie in Aktionen definieren. Ja
dataFile Pfad zur Datei, die die Daten für die API enthält. Ja
entraAuthConfig Konfiguration für die Microsoft Entra-Authentifizierung. Ja, wenn Sie auth für entra konfigurieren

Sie können auf die dataFile verweisen, indem Sie einen absoluten oder relativen Pfad verwenden. Dev Proxy löst relative Pfade relativ zur API-Definitionsdatei auf.

Die dataFile müssen ein JSON-Array definieren. Das Array kann leer sein oder einen anfänglichen Satz von Objekten enthalten.

EntraAuthConfig-Eigenschaften

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

Sie können entraAuthConfig für die API-Datei und für jede API-Aktion definieren. Wenn Sie sie in der API-Datei definieren, gilt sie für alle Aktionen. Wenn Sie sie für eine Aktion definieren, wird die API-Dateikonfiguration für diese bestimmte Aktion außer Kraft gesetzt.

Die eigenschaft entraAuthConfig hat die folgenden Eigenschaften.

Eigentum Beschreibung Erforderlich Vorgabe
audience Geben Sie die gültige Zielgruppe für das Token an. Wenn angegeben, vergleicht CrudApiPlugin die Zielgruppe vom Token mit dieser Zielgruppe. Wenn sie anders sind, gibt CrudApiPlugin eine 401 Nicht autorisierte Antwort zurück. Nein Nichts
issuer Geben Sie den gültigen Tokenherausgeber an. Wenn angegeben, vergleicht CrudApiPlugin den Aussteller vom Token mit diesem Aussteller. Wenn sie anders sind, gibt CrudApiPlugin eine 401 Nicht autorisierte Antwort zurück. Nein Nichts
scopes Geben Sie das Array gültiger Bereiche an. Wenn angegeben, steuert CrudApiPlugin, ob eines der Bereiche im Token vorhanden ist. Wenn keines der Bereiche vorhanden ist, gibt CrudApiPlugin eine 401 Nicht autorisierte Antwort zurück. Nein Nichts
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 eine 401 Nicht autorisierte Antwort zurück. Nein Nichts
validateLifetime Legen Sie für den CrudApiPlugin auf true fest, um zu überprüfen, ob das Token nicht abgelaufen ist. Wenn CrudApiPlugin ein abgelaufenes Token erkennt, gibt es eine 401 Nicht autorisierte Antwort zurück. Nein false
validateSigningKey Legen Sie für crudApiPlugin auf true fest, um zu überprüfen, ob das Token authentifiziert ist. Wenn CrudApiPlugin ein Token mit einer ungültigen Signatur erkennt (z. B. weil Sie das Token manuell geändert haben), wird eine 401 Nicht autorisierte Antwort zurückgegeben. Nein false

Aktionseigenschaften

Jede Aktion in der Liste actions weist die folgenden Eigenschaften auf.

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

Die in der url-Eigenschaft angegebene URL kann Parameter enthalten. Sie definieren Parameter, indem Sie den Parameternamen in geschweifte Klammern umschließen, z. B. {customer-id}. 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 die url als /customers/{customer-id} und die query als $.[?(@.id == {customer-id})]definieren, ersetzt Dev Proxy den {customer-id} Parameter in der Abfrage durch den Wert aus der Anforderungs-URL.

Wichtig

Dev Proxy implementiert JSONPath in der query-Eigenschaft mithilfe von Newtonsoft.Json. Es gibt einige Einschränkungen für die Verwendung, z. B. es unterstützt nur einzelne Anführungszeichen. Bevor Sie ein Problem übermitteln, müssen Sie Ihre Abfrage überprüfen.

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

Jeder Aktionstyp verfügt über eine standardmäßige HTTP-Methode. Sie können die Standardeinstellung überschreiben, indem Sie die eigenschaft method angeben. Beispielsweise verfügt der get Aktionstyp über eine Standardmethode von GET. Wenn Sie stattdessen POST verwenden möchten, geben Sie die eigenschaft method als POSTan.

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

Aktionen

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. Schlägt fehl, 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 keinem Element entspricht. 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 as-ishinzu.

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