APIM JSON 스키마 유효성 검사가 쉬워졌습니다.

너무 오랫동안 변환 정책(<set-body> , throw new Exception , <on-error> )을 사용하여 JSON 스키마를 검증해야 했습니다.

더 이상 =)
드디어 content validation policies이 생겼습니다.

The policy validates the following content in the request or response against the schema:

• Presence of all required properties.
• Absence of additional properties, if the schema has the additionalProperties field set to false.
• Types of all properties. For example, if a schema specifies a property as an integer, the request (or response) must include an integer and not another type, such as a string.
• The format of the properties, if specified in the schema - for example, regex (if the pattern keyword is specified), minimum for integers, and so on.

그리고 "마침내"라는 말은 지금부터 몇 달 동안을 의미합니다. 그러나 나는 그것에 관한 많은 게시물을 보지 못하므로 여기에 있습니다 =)

API Management 인스턴스를 프로비저닝하는 APIM bicep template이 이미 있다고 가정해 보겠습니다.

이제 유효성 검사 및 정의에 사용할 스키마로 내 Bicep 템플릿을 확장하겠습니다.

JSON 스키마 정의

먼저 첫 번째 것들. 아래는 내 스키마 및 페이로드 예입니다.

메인.바이셉

var schemaExampleUser1 = 'john.doe@${tenantName}.onmicrosoft.com'

var schemaPersonRequired = [
  'firstName'
  'lastName'
]
var schemaPerson = {
  firstName: {
    type: 'string'
  }
  lastName: {
    type: 'string'
  }
  age: {
    type: 'integer'
    minimum: 0
  }
  email: {
    type: 'string'
    format: 'email'
    pattern: '^\\S+@\\S+\\.\\S+$'
  }
}
var personExample = {
  firstName: 'John'
  lastName: 'Doe'
  age: 25
  email: schemaExampleUser1
}

API 관리 리소스

정책

API에 따라 믹스 앤 매치하고 싶은 여러 정책이 있습니다. 일을 깔끔하게 유지하기 위해 별도의 변수에 보관하고 필요에 따라 최종 정의를 작성합니다.

메인.바이셉

var authorizationPolicy = '''
        <!-- Service Bus Authorization-->
        <authentication-managed-identity resource="https://servicebus.azure.net/" output-token-variable-name="msi-access-token" ignore-error="false" />
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (string)context.Variables["msi-access-token"])</value>
        </set-header>
        <set-header name="Content-Type" exists-action="override">
            <value>application/atom+xml;type=entry;charset=utf-8</value>
        </set-header>
        <set-header name="BrokerProperties" exists-action="override">
            <value>{}</value>
        </set-header>
'''

var mockResponse = '<mock-response status-code="200" content-type="application/json" />'

var validatePersonPolicy = '''
        <validate-content unspecified-content-type-action="detect" max-size="102400" size-exceeded-action="prevent" errors-variable-name="validationErrors">
          <content type="application/json" validate-as="json" action="prevent" schema-id="Portfolio" />
        </validate-content>
'''

var policySchema = '''
  <!--ADD {0}-->
  <policies>
      <inbound>
        <base />
        <!-- Validation -->
        {1}
        <!-- Authorization -->
        {2}
        <!-- Mock response -->
        {3}
      </inbound>
      <backend>
        <base />
      </backend>
      <outbound>
        <base />
      </outbound>
      <on-error>
        <base />
      </on-error>
    </policies>
'''

var personPolicy = format(policySchema, 'PORTFOLIO', validatePersonPolicy, authorizationPolicy, '<!-- N/A -->')

개요

이제 기존 API Management 인스턴스에서 정의schema를 생성할 차례입니다.

메인.바이셉

resource apiManagement 'Microsoft.ApiManagement/service@2021-08-01' existing = {
  name: serviceName
}

resource apiManagement_schemaPerson 'Microsoft.ApiManagement/service/schemas@2021-08-01' = {
  name: 'Person'
  parent: apiManagement
  properties: {
    schemaType: 'json'
    description: 'Schema for a Person Object'
    document: any({
      type: 'array'
      items: {
        type: 'object'
        properties: schemaPerson
        required: schemaPersonRequired
      }
    })
  }
}

배포 후에는 API/스키마에서 찾을 수 있습니다.

API

다음 단계는 API, 정의 및 작업을 만드는 것입니다. 첫 번째 단계에서 만든 스키마와 예제를 참조하고 있습니다.
이 예에서 Add Person 작업은 페이로드를 ServiceBus 대기열에 저장하므로 urlTemplate가 /${serviceBusQueueName1}/messages로 설정됩니다.
URL 끝에 있는 "메시지"에 대해 기억해야 한다는 점을 지적하기 위해 언급하는 것입니다. ;)

메인.바이셉

resource apiManagement_apiName 'Microsoft.ApiManagement/service/apis@2021-08-01' = {
  name: '${serviceName}/${apiName}'
  properties: {
    displayName: apiDisplayName
    subscriptionRequired: true
    path: 'person-schema-validation'
    protocols: [
      'https'
    ]
    isCurrent: true
    description: 'Personal data ingestion'
    subscriptionKeyParameterNames: {
      header: 'Subscription-Key-Header-Name'
      query: 'subscription-key-query-param-name'
    }
  }
}

resource apiManagement_apiName_apiSchemaGuid 'Microsoft.ApiManagement/service/apis/schemas@2021-08-01' = {
  parent: apiManagement_apiName
  name: apiSchemaGuid
  properties: {
    contentType: 'application/vnd.oai.openapi.components+json'
    document: any({
      components: {
        schemas: {
          Definition_Person: {
            type: 'object'
            properties: schemaPerson
            required: schemaPersonRequired
            example: personExample
          }
        }
      }
    })
  }
}
resource apiManagement_apiName_operation_addPerson 'Microsoft.ApiManagement/service/apis/operations@2021-08-01' = {
  parent: apiManagement_apiName
  name: operation_addPerson

  dependsOn: [
    apiManagement_apiName_apiSchemaGuid
  ]
  properties: {
    request: {
      headers: [
        {
          name: 'Content-Type'
          type: 'string'
          required: true
          values: [
            'application/json'
          ]
        }
      ]
      representations: [
        {
          contentType: 'application/json'
          schemaId: apiSchemaGuid
          typeName: 'Definition_Person'
        }
      ]
    }
    displayName: 'Add Person'
    description: 'Add Person Information to ServiceBus. \nThe Request Body is parsed to ensure correct schema.'
    method: 'POST'
    urlTemplate: '/${serviceBusQueueName1}/messages'
  }
}

스키마 검증

이제 모든 것이 준비되었으므로 스키마 유효성 검사를 사용할 수 있습니다. 드디어!

첫 번째 정책은 실제로 유효성 검사가 아닙니다. 모든 작업에 적용되며 백엔드 URL이 ServiceBus 끝점으로 설정되도록 합니다.

두 번째 정책은 페이로드 수신이 스키마 유효성 검사를 통과하도록 합니다.

메인.바이셉

resource serviceName_apiName_policy 'Microsoft.ApiManagement/service/apis/policies@2021-08-01' = {
  parent: apiManagement_apiName
  name: 'policy'
  properties: {
    value: '<!-- All operations-->\r\n<policies>\r\n  <inbound>\r\n    <base/>\r\n    <set-backend-service base-url="${serviceBusEndpoint}" />\r\n  <set-header name="Content-Type" exists-action="override">\r\n  <value>application/json</value>\r\n  </set-header>\r\n  </inbound>\r\n  <backend>\r\n    <base />\r\n  </backend>\r\n  <outbound>\r\n    <base />\r\n  </outbound>\r\n  <on-error>\r\n    <base />\r\n  </on-error>\r\n</policies>'
    format: 'rawxml'
  }
}
resource apiManagement_apiName_operation_addPerson_policy 'Microsoft.ApiManagement/service/apis/operations/policies@2021-08-01' = {
  parent: apiManagement_apiName_operation_addPerson
  name: 'policy'
  properties: {
    value: personPolicy
    format: 'rawxml'
  }
}

이두근 템플릿이 켜져 있습니다GitHub.