CrudApiPlugin

Simuluje rozhraní CRUD API s úložištěm dat v paměti. Odesílá odpovědi JSON. Podporuje CORS pro použití mezi doménami z aplikací na straně klienta. Volitelně simuluje rozhraní CRUD API zabezpečená pomocí Microsoft Entra.

Definice instance modulu plug-in

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

Příklad konfigurace

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

Vlastnosti konfigurace

Vlastnost	Popis
apiFile	Cesta k souboru, který obsahuje definici rozhraní CRUD API

Možnosti příkazového řádku

Žádné

Příklad souboru rozhraní API

Následuje několik příkladů souborů rozhraní API, které definují rozhraní CRUD API pro informace o zákaznících.

Anonymní rozhraní CRUD API

Následuje příklad souboru rozhraní API, který definuje anonymní rozhraní CRUD API pro informace o zákaznících.

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

Rozhraní CRUD API zabezpečené pomocí Microsoft Entra s použitím jednoho oboru

Následuje příklad souboru rozhraní API, který definuje rozhraní CRUD API pro informace o zákaznících zabezpečených pomocí Microsoft Entra. Všechny akce jsou zabezpečené s jedním oborem. CrudApiPlugin ověřuje cílovou skupinu tokenů, vystavitele a obor.

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

Rozhraní CRUD API zabezpečené pomocí Microsoft Entra s využitím konkrétních oborů

Následuje příklad souboru rozhraní API, který definuje rozhraní CRUD API pro informace o zákaznících zabezpečených pomocí Microsoft Entra. Akce jsou zabezpečené s konkrétními obory. CrudApiPlugin ověřuje cílovou skupinu tokenů, vystavitele a obor.

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

Vlastnosti souboru rozhraní API

Vlastnost	Popis	Povinné
actions	Seznam akcí, které rozhraní API podporuje	Yes
auth	Určuje, jestli je rozhraní API zabezpečené, nebo ne. Povolené hodnoty: none, entra. Výchozí none	No
baseUrl	Základní adresa URL, kde dev proxy zveřejňuje adresu URL. Dev Proxy předefinuje základní adresu URL na adresy URL, které definujete v akcích.	Yes
dataFile	Cesta k souboru, který obsahuje data pro rozhraní API.	Yes
entraAuthConfig	Konfigurace pro ověřování Microsoft Entra.	Ano, pokud nakonfigurujete authentra

Můžete odkazovat na dataFile absolutní nebo relativní cestu. Dev Proxy překládá relativní cesty relativně k definičnímu souboru rozhraní API.

Musí dataFile definovat pole JSON. Pole může být prázdné nebo může obsahovat počáteční sadu objektů.

Vlastnosti EntraAuthConfig

Při konfiguraci auth vlastnosti na entramusíte definovat entraAuthConfig vlastnost. Pokud ho nedefinujete, CrudApiPlugin zobrazí upozornění a rozhraní API je dostupné anonymně.

Můžete definovat entraAuthConfig v souboru rozhraní API a při každé akci rozhraní API. Když ho definujete v souboru rozhraní API, platí pro všechny akce. Když ji definujete u akce, přepíše konfiguraci souboru rozhraní API pro tuto konkrétní akci.

Vlastnost entraAuthConfig má následující vlastnosti.

Vlastnost	Popis	Povinné	Default
audience	Zadejte platnou cílovou skupinu tokenu. Při zadání crudApiPlugin porovná cílovou skupinu z tokenu s touto cílovou skupinou. Pokud se liší, vrátí CrudApiPlugin odpověď 401 Neautorizováno.	No	Žádné
issuer	Zadejte platného vystavitele tokenu. Pokud je zadáno, CrudApiPlugin porovná vystavitele z tokenu s tímto vystavitelem. Pokud se liší, vrátí CrudApiPlugin odpověď 401 Neautorizováno.	No	Žádné
scopes	Zadejte pole platných oborů. Pokud je zadáno, CrudApiPlugin řídí, jestli je v tokenu některý z oborů. Pokud není k dispozici žádný z oborů, CrudApiPlugin vrátí odpověď 401 Neautorizováno.	No	Žádné
roles	Zadejte pole platných rolí. Pokud je zadáno, CrudApiPlugin řídí, jestli je v tokenu nějaká z rolí. Pokud není k dispozici žádná z rolí, CrudApiPlugin vrátí odpověď 401 Neautorizováno.	No	Žádné
validateLifetime	Pokud chcete ověřit, jestli platnost tokenu nevypršela, nastavte na hodnotu true CrudApiPlugin. Když CrudApiPlugin zjistí token, jehož platnost vypršela, vrátí odpověď 401 Neautorizováno.	No	false
validateSigningKey	Nastavte na true pro CrudApiPlugin a ověřte, jestli je token autentický. Když CrudApiPlugin zjistí token s neplatným podpisem (například proto, že jste token upravili ručně), vrátí odpověď 401 Neautorizováno.	No	false

Vlastnosti akce

Každá akce v actions seznamu má následující vlastnosti.

Vlastnost	Popis	Povinné	Default
action	Definuje, jak dev proxy interaguje s daty. Možné hodnoty: getAll, getOne, getMany, create, merge, , update, . delete	Yes	Žádné
auth	Určuje, jestli je akce zabezpečená, nebo ne. Povolené hodnoty: none, entra.	No	none
entraAuthConfig	Konfigurace pro ověřování Microsoft Entra.	Ano, pokud nakonfigurujete authentra	Žádné
method	Metoda HTTP, kterou dev proxy používá ke zveřejnění akce.	No	Závisí na akci.
query	Newtonsoft JSONPath dotaz, který dev Proxy používá k vyhledání dat v datovém souboru.	No	Prázdné
url	Adresa URL, na které dev proxy zveřejňuje akci. Dev Proxy připojí adresu URL k základní adrese URL.	No	Prázdné

Adresa URL zadaná ve url vlastnosti může obsahovat parametry. Parametry definujete zabalením názvu parametru do složených závorek, {customer-id}například . Při směrování požadavku proxy vývojářů nahradí parametr hodnotou z adresy URL požadavku.

V dotazu můžete použít stejný parametr. Pokud například definujete url jako /customers/{customer-id} a query jako $.[?(@.id == {customer-id})], dev Proxy nahradí {customer-id} parametr v dotazu hodnotou z adresy URL požadavku.

Důležité

Dev Proxy implementuje JSONPath ve query vlastnosti pomocí Newtonsoft.Json. Jeho použití má určitá omezení, například podporuje pouze jednoduché uvozovky. Před odesláním problému nezapomeňte ověřit dotaz.

Pokud modul plug-in nemůže pomocí dotazu najít data v datovém 404 Not Found souboru, vrátí odpověď.

Každý typ akce má výchozí metodu HTTP. Výchozí nastavení můžete přepsat zadáním method vlastnosti . Například get typ akce má výchozí metodu GET. Pokud chcete místo toho použít POST , zadejte method vlastnost jako POST.

Pole actions definovalo kolekci akcí, které chcete napodobenit. Pro stejnou metodu HTTP a typ akce můžete definovat více akcí. Můžete například definovat dvě getOne akce, jednu, která načte zákazníka podle jeho ID a druhou podle jeho e-mailové adresy. Nezapomeňte pro každou akci definovat jedinečné adresy URL.

Akce

Proxy vývoj podporuje následující akce pro rozhraní CRUD API.

Akce	Popis	Výchozí metoda
getAll	Vrátí všechny položky z datového souboru.	GET
getOne	Vrátí jednu položku z datového souboru. Pokud dotaz odpovídá více položkám, selže.	GET
getMany	Vrátí více položek z datového souboru. Pokud dotaz neodpovídá žádným položkám, vrátí prázdné pole.	GET
create	Přidá novou položku do kolekce dat.	POST
merge	Sloučí data z požadavku s daty z datového souboru.	PATCH
update	Nahradí data v datovém souboru daty z požadavku.	PUT
delete	Odstraní položku z datového souboru.	DELETE

Když pomocí create akce vytvoříte novou položku, modul plug-in neověří její tvar a nepřidá ho do shromažďování dat tak, jak je.

Příklad datového souboru

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