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 klientských aplikací. 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 pomocí 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é pomocí jednoho oboru. CrudApiPlugin ověří 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é pomocí konkrétních oborů. CrudApiPlugin ověří 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	Požadovaný
actions	Seznam akcí, které rozhraní API podporuje	Ano
auth	Určuje, jestli je rozhraní API zabezpečené nebo ne. Povolené hodnoty: none, entra. Výchozí none	Ne
baseUrl	Základní adresa URL, kde dev proxy zveřejňuje adresu URL. Dev Proxy předloží základní adresu URL adres URL, které definujete v akcích.	Ano
dataFile	Cesta k souboru, který obsahuje data pro rozhraní API.	Ano
entraAuthConfig	Konfigurace pro ověřování Microsoft Entra	Ano, když nakonfigurujete auth na entra

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

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

Vlastnosti EntraAuthConfig

Při konfiguraci vlastnosti auth na entraje nutné definovat entraAuthConfig vlastnost. Pokud ho nedefinujete, crudApiPlugin zobrazí upozornění a rozhraní API je k dispozici 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 pro akci, přepíše konfiguraci souboru rozhraní API pro tuto konkrétní akci.

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

Vlastnost	Popis	Požadovaný	Výchozí
audience	Zadejte platnou cílovou skupinu tokenu. Po zadání crudApiPlugin porovná cílovou skupinu z tokenu s touto cílovou skupinou. Pokud se liší, vrátí CrudApiPlugin neautorizovanou odpověď 401.	Ne	Žá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 neautorizovanou odpověď 401.	Ne	Žádný
scopes	Zadejte pole platných oborů. Pokud je zadáno, CrudApiPlugin řídí, pokud se v tokenu nachází některý z oborů. Pokud žádný z oborů není k dispozici, vrátí CrudApiPlugin neautorizovanou odpověď 401.	Ne	Žádný
roles	Zadejte pole platných rolí. Pokud je zadáno, CrudApiPlugin řídí, pokud se v tokenu nachází některý z rolí. Pokud žádná z rolí není k dispozici, vrátí CrudApiPlugin neautorizovanou odpověď 401.	Ne	Žádný
validateLifetime	Nastavte true pro CrudApiPlugin a ověřte, jestli nevypršela platnost tokenu. Když CrudApiPlugin zjistí token s vypršenou platností, vrátí neautorizovanou odpověď 401.	Ne	false
validateSigningKey	Nastavte na true pro CrudApiPlugin, aby se ověřilo, 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.	Ne	false

Vlastnosti akce

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

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

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

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

Důležitý

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

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

Každý typ akce má výchozí metodu HTTP. Výchozí nastavení můžete přepsat zadáním vlastnosti method. Například typ akce get má výchozí metodu GET. Chcete-li místo toho použít POST, zadejte vlastnost method 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 druhé pomocí e-mailové adresy. Nezapomeňte definovat jedinečné adresy URL pro každou akci.

Akce

Dev Proxy 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. Selže, když dotaz odpovídá více položkám.	GET
getMany	Vrátí více položek z datového souboru. Vrátí prázdné pole, pokud dotaz neodpovídá žádným položkám.	GET
create	Přidá do kolekce dat novou položku.	POST
merge	Sloučí data z požadavku s daty z datového souboru.	PATCH
update	Nahradí data v datovém souboru daty daty z požadavku.	PUT
delete	Odstraní položku z datového souboru.	DELETE

Když vytvoříte novou položku pomocí akce create, modul plug-in neověří jeho tvar a přidá ji do kolekce dat as-is.

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