Udostępnij za pośrednictwem

CrudApiPlugin

  • Artykuł

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ą Microsoft Entra.

Zrzut ekranu przedstawiający wiersz polecenia z serwerem proxy deweloperów symulującym interfejs API CRUD.

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łaściwość Opis
apiFile Ścieżka do pliku zawierającego definicję interfejsu API CRUD

Opcje wiersza polecenia

Brak

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 przedstawiono przykładowy plik interfejsu API, który definiuje anonimowy interfejs API CRUD dla informacji o klientach.

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

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

Poniżej przedstawiono przykładowy plik interfejsu API, który definiuje interfejs API CRUD w celu uzyskania informacji o klientach zabezpieczonych za pomocą Microsoft Entra. Wszystkie akcje są zabezpieczone z jednym zakresem. CrudApiPlugin weryfikuje odbiorców tokenów, wystawcę i zakres.

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

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

Poniżej przedstawiono przykładowy plik interfejsu API, który definiuje interfejs API CRUD w celu uzyskania informacji o klientach zabezpieczonych za pomocą Microsoft Entra. Akcje są zabezpieczone za pomocą określonych zakresów. CrudApiPlugin weryfikuje odbiorców tokenów, wystawcę i zakres.

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

Właściwości pliku interfejsu API

Właściwość 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. Domyślny none Nie
baseUrl Podstawowy adres URL, w którym serwer proxy deweloperów uwidacznia adres URL. Serwer proxy deweloperów poprzedza podstawowy adres URL adresów URL zdefiniowanych w akcjach. Tak
dataFile Ścieżka do pliku zawierającego dane interfejsu API. Tak
entraAuthConfig Konfiguracja uwierzytelniania Microsoft Entra. Tak, podczas konfigurowania authentra

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

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

Właściwości entraAuthConfig

Podczas konfigurowania auth właściwości na entrawartość należy zdefiniować entraAuthConfig właściwość . Jeśli nie zdefiniujesz go, crudApiPlugin wyświetli ostrzeżenie, a interfejs API jest dostępny anonimowo.

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

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

Właściwość Opis Wymagane Default
audience Określ prawidłową publiczność dla tokenu. Po określeniu crudApiPlugin porównuje odbiorców z tokenu z tą publicznością. Jeśli są one inne, CrudApiPlugin zwraca odpowiedź 401 Brak autoryzacji. Nie Brak
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 Brak
scopes Określ tablicę prawidłowych zakresów. Po określeniu crudApiPlugin kontroluje, czy któryś z zakresów znajduje się w tokenie. Jeśli żaden z zakresów nie jest obecny, funkcja CrudApiPlugin zwraca odpowiedź 401 Brak autoryzacji. Nie Brak
roles Określ tablicę prawidłowych ról. Po określeniu crudApiPlugin kontroluje, czy któraś z ról znajduje się na tokenie. Jeśli żadna z ról nie jest obecna, funkcja CrudApiPlugin zwraca odpowiedź 401 Brak autoryzacji. Nie Brak
validateLifetime Dla crudApiPlugin ustaw wartość na true wartość , aby sprawdzić, czy token nie wygasł. Gdy crudApiPlugin wykryje wygasły token, zwraca odpowiedź 401 Brak autoryzacji. Nie false
validateSigningKey Dla crudApiPlugin ustaw wartość na true wartość , aby sprawdzić, czy token jest uwierzytelniony. Gdy crudApiPlugin wykryje token z nieprawidłowym podpisem (na przykład dlatego, że token został zmodyfikowany ręcznie), zwraca odpowiedź 401 Brak autoryzacji. Nie false

Właściwości akcji

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

Właściwość Opis Wymagane Default
action Definiuje sposób interakcji serwera proxy dev z danymi. Możliwe wartości: getAll, , getManygetOne, createmerge, , update, delete. Tak Brak
auth Określa, czy akcja jest zabezpieczona, czy nie. Dozwolone wartości: none, entra. Nie none
entraAuthConfig Konfiguracja uwierzytelniania Microsoft Entra. Tak, podczas konfigurowania authentra Brak
method Metoda HTTP używana przez serwer proxy dewelopera do uwidocznienia akcji. Nie Zależy od akcji
query Zapytanie Newtonsoft JSONPath używane przez serwer proxy dewelopera do znajdowania danych w pliku danych. Nie Pusty
url Adres URL, pod którym serwer proxy dewelopera uwidacznia akcję. Serwer proxy dewelopera dołącza adres URL do podstawowego adresu URL. Nie Pusty

Adres URL określony we url właściwości 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 dewelopera 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 parametr jako /customers/{customer-id} i query jako $.[?(@.id == {customer-id})], serwer proxy dewelopera {customer-id} zastępuje parametr w zapytaniu wartością z adresu URL żądania.

Ważne

Serwer proxy dev implementuje ścieżkę query JSONPath we właściwości przy użyciu pliku Newtonsoft.Json. Istnieją pewne ograniczenia dotyczące używania go, takie jak, obsługuje tylko pojedyncze cudzysłowy. Przed przesłaniem problemu upewnij się, że zapytanie jest weryfikowane.

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. Wartość domyślną można zastąpić, określając method właściwość . Na przykład get typ akcji ma domyślną metodę GET. Jeśli zamiast tego chcesz użyć POST , określ method właściwość 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 getOne akcje, jedną, która pobiera klienta według 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 pasuje do żadnych elementów. GET
create Dodaje nowy element do zbierania danych. POST
merge Scala dane z żądania z danymi z pliku danych. PATCH
update Zamienia dane w pliku danych na dane z żądania. PUT
delete Usuwa element z pliku danych. DELETE

Podczas tworzenia nowego elementu przy użyciu create akcji wtyczka nie weryfikuje jego kształtu i dodaje go do kolekcji danych w takiej postaci, w jakim jest.

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