CrudApiPlugin

아티클
04/08/2024

메모리 내 데이터 저장소를 사용하여 CRUD API를 시뮬레이션합니다. JSON 응답을 보냅니다. 클라이언트 쪽 애플리케이션에서 도메인 간 사용을 위한 CORS를 지원합니다. 필요에 따라 는 Microsoft Entra 사용하여 보호된 CRUD API를 시뮬레이션합니다.

플러그 인 instance 정의

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

구성 예

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

구성 속성

속성	Description
`apiFile`	CRUD API의 정의를 포함하는 파일의 경로

명령줄 옵션

없음

API 파일 예제

다음은 고객에 대한 정보에 대한 CRUD API를 정의하는 API 파일의 몇 가지 예입니다.

익명 CRUD API

다음은 고객에 대한 정보를 위해 익명 CRUD API를 정의하는 API 파일의 예입니다.

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

단일 scope 사용하여 Microsoft Entra 사용하여 보호되는 CRUD API

다음은 Microsoft Entra 보안이 유지되는 고객에 대한 정보에 대한 CRUD API를 정의하는 API 파일의 예입니다. 모든 작업은 하나의 scope 사용하여 보호됩니다. CrudApiPlugin은 토큰 대상 그룹, 발급자 및 scope 유효성을 검사합니다.

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

특정 범위를 사용하여 Microsoft Entra 보안이 설정된 CRUD API

다음은 Microsoft Entra 보안이 유지되는 고객에 대한 정보에 대한 CRUD API를 정의하는 API 파일의 예입니다. 작업은 특정 범위로 보호됩니다. CrudApiPlugin은 토큰 대상 그룹, 발급자 및 scope 유효성을 검사합니다.

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

API 파일 속성

속성	Description	필수
`actions`	API에서 지원하는 작업 목록입니다.	Yes
`auth`	API의 보안 여부를 확인합니다. 허용되는 값: `none`, `entra`. 기본 `none`	No
`baseUrl`	개발자 프록시가 URL을 노출하는 기본 URL입니다. 개발 프록시는 작업에서 정의하는 URL 앞에 기본 URL을 추가합니다.	Yes
`dataFile`	API에 대한 데이터를 포함하는 파일의 경로입니다.	Yes
`entraAuthConfig`	Microsoft Entra 인증을 위한 구성입니다.	예, 를 로 구성할 `auth` 때 `entra`

절대 경로 또는 상대 경로를 사용하여 를 참조 dataFile 할 수 있습니다. 개발 프록시는 API 정의 파일에 상대적으로 상대 경로를 확인합니다.

는 dataFile JSON 배열을 정의해야 합니다. 배열은 비어 있거나 초기 개체 집합을 포함할 수 있습니다.

EntraAuthConfig 속성

속성을 로 auth 구성할 때는 속성을 entra정의 entraAuthConfig 해야 합니다. 정의하지 않으면 CrudApiPlugin에 경고가 표시되고 API를 익명으로 사용할 수 있습니다.

API 파일 및 각 API 작업에서 정의 entraAuthConfig 할 수 있습니다. API 파일에서 정의하면 모든 작업에 적용됩니다. 작업에서 정의하면 이 특정 작업에 대한 API 파일 구성을 재정의합니다.

속성에는 entraAuthConfig 다음 속성이 있습니다.

속성	Description	필수	기본값
`audience`	토큰에 유효한 대상 그룹을 지정합니다. 지정된 경우 CrudApiPlugin은 토큰의 대상 그룹을 이 대상과 비교합니다. 다른 경우 CrudApiPlugin은 401 권한 없음 응답을 반환합니다.	예	None
`issuer`	유효한 토큰 발급자를 지정합니다. 지정된 경우 CrudApiPlugin은 토큰의 발급자를 이 발급자와 비교합니다. 다른 경우 CrudApiPlugin은 401 권한 없음 응답을 반환합니다.	예	None
`scopes`	유효한 범위의 배열을 지정합니다. 지정된 경우 CrudApiPlugin은 토큰에 범위 중 하나가 있는지 제어합니다. 두 범위가 모두 없는 경우 CrudApiPlugin은 401 권한 없음 응답을 반환합니다.	예	None
`roles`	유효한 역할의 배열을 지정합니다. 지정된 경우 CrudApiPlugin은 토큰에 역할 중 하나가 있는지 제어합니다. 두 역할이 모두 없는 경우 CrudApiPlugin은 401 권한 없음 응답을 반환합니다.	예	None
`validateLifetime`	`true` 토큰이 만료되지 않았는지 유효성을 검사하려면 CrudApiPlugin에 대해 를 로 설정합니다. CrudApiPlugin이 만료된 토큰을 검색하면 401 권한 없음 응답을 반환합니다.	No	`false`
`validateSigningKey`	`true` 토큰이 인증되었는지 유효성을 검사하려면 CrudApiPlugin에 대해 를 로 설정합니다. CrudApiPlugin이 잘못된 서명이 있는 토큰을 검색하면(예: 토큰을 수동으로 수정했기 때문에) 401 권한 없음 응답이 반환됩니다.	No	`false`

작업 속성

목록의 actions 각 작업에는 다음과 같은 속성이 있습니다.

속성	Description	필수	기본값
`action`	개발자 프록시가 데이터와 상호 작용하는 방법을 정의합니다. 가능한 값은 `getAll`, , `getOne`, `getMany`, `mergecreate`, , `deleteupdate`입니다.	예	없음
`auth`	작업이 보호되는지 여부를 확인합니다. 허용되는 값: `none`, `entra`.	No	`none`
`entraAuthConfig`	Microsoft Entra 인증을 위한 구성입니다.	예, 를 로 구성할 `auth` 때 `entra`	없음
`method`	개발자 프록시가 작업을 노출하는 데 사용하는 HTTP 메서드입니다.	No	작업에 따라 다름
`query`	개발자 프록시가 데이터 파일에서 데이터를 찾는 데 사용하는 Newtonsoft JSONPath 쿼리입니다.	No	Empty
`url`	개발자 프록시가 작업을 노출하는 URL입니다. 개발자 프록시는 기본 URL에 URL을 추가합니다.	No	Empty

속성에 지정된 URL에는 매개 변수가 url 포함될 수 있습니다. 매개 변수 이름을 중괄호로 래핑하여 매개 변수를 정의합니다(예: {customer-id}). 요청을 라우팅할 때 Dev Proxy는 매개 변수를 요청 URL의 값으로 바꿉니다.

쿼리에서 동일한 매개 변수를 사용할 수 있습니다. 예를 들어 를 로 정의 url 하고 query 를 로 $.[?(@.id == {customer-id})]정의하는 경우 Dev Proxy는 쿼리의 {customer-id} 매개 변수를 요청 URL의 값으로 /customers/{customer-id} 바꿉니다.

중요

개발자 프록시는 Newtonsoft.Json을 사용하여 속성에 query JSONPath를 구현합니다. 작은따옴표만 지원하는 등의 몇 가지 제한 사항이 있습니다. 문제를 제출하기 전에 쿼리의 유효성을 검사해야 합니다.

플러그 인이 쿼리를 사용하여 데이터 파일에서 데이터를 찾을 수 없는 경우 응답을 반환합니다 404 Not Found .

각 작업 형식에는 기본 HTTP 메서드가 있습니다. 속성을 지정하여 기본값을 재정의할 method 수 있습니다. 예를 들어 작업 형식에는 get 의 기본 메서드가 있습니다 GET. 대신 사용 POST 하려면 속성을 로 POST지정 method 합니다.

배열은 actions 모의하려는 작업 컬렉션을 정의했습니다. 동일한 HTTP 메서드 및 작업 유형에 대해 여러 작업을 정의할 수 있습니다. 예를 들어 ID로 고객을 검색하고 다른 하나는 이메일 주소로 검색하는 두 가지 getOne 작업을 정의할 수 있습니다. 각 작업에 대해 고유한 URL을 정의해야 합니다.

동작

개발 프록시는 CRUD API에 대해 다음 작업을 지원합니다.

작업	Description	Default 메서드
`getAll`	데이터 파일의 모든 항목을 반환합니다.	`GET`
`getOne`	데이터 파일에서 단일 항목을 반환합니다. 쿼리가 여러 항목과 일치하면 실패합니다.	`GET`
`getMany`	데이터 파일에서 여러 항목을 반환합니다. 쿼리가 항목과 일치하지 않는 경우 빈 배열을 반환합니다.	`GET`
`create`	데이터 컬렉션에 새 항목을 추가합니다.	`POST`
`merge`	요청의 데이터를 데이터 파일의 데이터와 병합합니다.	`PATCH`
`update`	데이터 파일의 데이터를 요청의 데이터로 바꿉니다.	`PUT`
`delete`	데이터 파일에서 항목을 삭제합니다.	`DELETE`

작업을 사용하여 create 새 항목을 만들 때 플러그 인은 셰이프의 유효성을 검사하지 않고 데이터 컬렉션에 있는 그대로 추가합니다.

데이터 파일 예제

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

다음을 통해 공유