CrudApiPlugin

Symuluje interfejs API CRUD z magazynem danych w pamięci. Wysyła odpowiedzi JSON. Obsługuje mechanizm CORS do użycia między domenami z aplikacji po stronie klienta. Opcjonalnie symuluje interfejsy API CRUD zabezpieczone za pomocą usługi Microsoft Entra.

Definicja wystąpienia wtyczki

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

Przykład konfiguracji

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

Właściwości konfiguracji

Własność	Opis
apiFile	Ścieżka do pliku zawierającego definicję interfejsu API CRUD

Opcje wiersza polecenia

Żaden

Przykład pliku interfejsu API

Poniżej przedstawiono kilka przykładów plików interfejsu API, które definiują interfejs API CRUD dla informacji o klientach.

Anonimowy interfejs API CRUD

Poniżej znajduje się przykład pliku interfejsu API, który definiuje anonimowy interfejs API CRUD dla informacji o klientach.

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

Interfejs API CRUD zabezpieczony za pomocą usługi Microsoft Entra przy użyciu jednego zakresu

Poniżej znajduje się przykład pliku interfejsu API definiującego interfejs API CRUD na potrzeby informacji o klientach zabezpieczonych za pomocą usługi Microsoft Entra. Wszystkie akcje są zabezpieczone za pomocą jednego zakresu. CrudApiPlugin weryfikuje odbiorców, wystawcę i zakres tokenu.

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

Interfejs API CRUD zabezpieczony za pomocą firmy Microsoft Entra przy użyciu określonych zakresów

Poniżej znajduje się przykład pliku interfejsu API definiującego interfejs API CRUD na potrzeby informacji o klientach zabezpieczonych za pomocą usługi Microsoft Entra. Akcje są zabezpieczone za pomocą określonych zakresów. CrudApiPlugin weryfikuje odbiorców, wystawcę i zakres tokenu.

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

Właściwości pliku interfejsu API

Własność	Opis	Wymagane
actions	Lista akcji, które obsługuje interfejs API.	Tak
auth	Określa, czy interfejs API jest zabezpieczony, czy nie. Dozwolone wartości: none, entra. none domyślne	Nie
baseUrl	Podstawowy adres URL, w którym serwer proxy deweloperów uwidacznia adres URL. Serwer proxy dewelopera poprzedza podstawowy adres URL do adresów URL zdefiniowanych w akcjach.	Tak
dataFile	Ścieżka do pliku zawierającego dane interfejsu API.	Tak
entraAuthConfig	Konfiguracja uwierzytelniania firmy Microsoft Entra.	Tak, podczas konfigurowania auth do entra

Możesz odwołać się do dataFile przy użyciu ścieżki bezwzględnej lub względnej. Serwer proxy deweloperów rozpoznaje ścieżki względne stosunkowo do pliku definicji interfejsu API.

dataFile musi definiować tablicę JSON. Tablica może być pusta lub może zawierać początkowy zestaw obiektów.

Właściwości entraAuthConfig

Podczas konfigurowania właściwości auth do entranależy zdefiniować właściwość entraAuthConfig. Jeśli nie zdefiniujesz go, crudApiPlugin wyświetli ostrzeżenie i interfejs API będzie dostępny anonimowo.

Można zdefiniować entraAuthConfig w pliku interfejsu API i w każdej akcji interfejsu API. Podczas definiowania go w pliku interfejsu API ma zastosowanie do wszystkich akcji. Podczas definiowania jej akcji zastępuje konfigurację pliku interfejsu API dla tej konkretnej akcji.

Właściwość entraAuthConfig ma następujące właściwości.

Własność	Opis	Wymagane	Domyślny
audience	Określ prawidłową grupę odbiorców tokenu. Po określeniu crudApiPlugin porównuje odbiorców z tokenu z tym odbiorcą. Jeśli są one inne, crudApiPlugin zwraca odpowiedź 401 Brak autoryzacji.	Nie	Żaden
issuer	Określ prawidłowego wystawcę tokenu. Po określeniu crudApiPlugin porównuje wystawcę z tokenu z tym wystawcą. Jeśli są one inne, crudApiPlugin zwraca odpowiedź 401 Brak autoryzacji.	Nie	Żaden
scopes	Określ tablicę prawidłowych zakresów. Po określeniu crudApiPlugin kontroluje, czy którykolwiek z zakresów znajduje się na tokenie. Jeśli żaden z zakresów nie jest obecny, funkcja CrudApiPlugin zwraca odpowiedź 401 Brak autoryzacji.	Nie	Żaden
roles	Określ tablicę prawidłowych ról. Po określeniu crudApiPlugin kontroluje, czy którakolwiek z ról jest obecna w tokenie. Jeśli żadna z ról nie istnieje, funkcja CrudApiPlugin zwraca odpowiedź 401 Brak autoryzacji.	Nie	Żaden
validateLifetime	Ustaw wartość true dla crudApiPlugin, aby sprawdzić, czy token nie wygasł. Gdy crudApiPlugin wykryje wygasły token, zwraca odpowiedź 401 Brak autoryzacji.	Nie	false
validateSigningKey	Ustaw wartość true dla crudApiPlugin, aby sprawdzić, czy token jest uwierzytelniony. Gdy crudApiPlugin wykryje token z nieprawidłowym podpisem (na przykład z powodu ręcznego zmodyfikowania tokenu), zwraca odpowiedź 401 Brak autoryzacji.	Nie	false

Właściwości akcji

Każda akcja na liście actions ma następujące właściwości.

Własność	Opis	Wymagane	Domyślny
action	Definiuje sposób, w jaki serwer proxy deweloperów współdziała z danymi. Możliwe wartości: getAll, getOne, getMany, create, merge, update, delete.	Tak	Żaden
auth	Określa, czy akcja jest zabezpieczona, czy nie. Dozwolone wartości: none, entra.	Nie	none
entraAuthConfig	Konfiguracja uwierzytelniania firmy Microsoft Entra.	Tak, podczas konfigurowania auth do entra	Żaden
method	Metoda HTTP używana przez serwer proxy dewelopera do uwidocznienia akcji.	Nie	Zależy od akcji
query	Newtonsoft zapytanie JSONPath używane przez serwer proxy dewelopera do znajdowania danych w pliku danych.	Nie	Pusty
url	Adres URL, w którym serwer proxy deweloperów uwidacznia akcję. Serwer proxy deweloperów dołącza adres URL do podstawowego adresu URL.	Nie	Pusty

Adres URL określony we właściwości url może zawierać parametry. Parametry można zdefiniować, opakowując nazwę parametru w nawiasach klamrowych, na przykład {customer-id}. Podczas kierowania żądania serwer proxy deweloperów zastępuje parametr wartością z adresu URL żądania.

W zapytaniu można użyć tego samego parametru. Jeśli na przykład zdefiniujesz url jako /customers/{customer-id}, a query jako $.[?(@.id == {customer-id})], serwer proxy dewelopera zastępuje parametr {customer-id} w zapytaniu wartością z adresu URL żądania.

Ważny

Serwer proxy deweloperów implementuje ścieżkę JSONPath we właściwości query przy użyciu pliku Newtonsoft.Json. Istnieją pewne ograniczenia dotyczące korzystania z niego, takie jak obsługuje tylko pojedyncze cudzysłowy. Przed przesłaniem problemu upewnij się, że zapytanie zostanie zweryfikowane.

Gdy wtyczka nie może znaleźć danych w pliku danych przy użyciu zapytania, zwraca 404 Not Found odpowiedź.

Każdy typ akcji ma domyślną metodę HTTP. Możesz zastąpić wartość domyślną, określając właściwość method. Na przykład typ akcji get ma domyślną metodę GET. Jeśli zamiast tego chcesz użyć POST, określ właściwość method jako POST.

Tablica actions zdefiniowała kolekcję akcji, które chcesz wyśmiewać. Można zdefiniować wiele akcji dla tej samej metody HTTP i typu akcji. Można na przykład zdefiniować dwie akcje getOne, jedną, która pobiera klienta według ich identyfikatora, a drugą przez adres e-mail. Pamiętaj, aby zdefiniować unikatowe adresy URL dla każdej akcji.

Akcje

Serwer proxy deweloperów obsługuje następujące akcje dla interfejsów API CRUD.

Akcja	Opis	Metoda domyślna
getAll	Zwraca wszystkie elementy z pliku danych.	GET
getOne	Zwraca pojedynczy element z pliku danych. Niepowodzenie, gdy zapytanie pasuje do wielu elementów.	GET
getMany	Zwraca wiele elementów z pliku danych. Zwraca pustą tablicę, jeśli zapytanie nie jest zgodne z żadnymi elementami.	GET
create	Dodaje nowy element do kolekcji danych.	POST
merge	Scala dane z żądania z danymi z pliku danych.	PATCH
update	Zastępuje dane w pliku danych danymi z żądania.	PUT
delete	Usuwa element z pliku danych.	DELETE

Podczas tworzenia nowego elementu przy użyciu akcji create wtyczka nie weryfikuje jego kształtu i dodaje go do kolekcji danych as-is.

Przykład pliku danych

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