SOAPMessageValidation 정책

이 페이지는 ApigeeApigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

정책 아이콘

SOAPMessageValidation 정책은 다음을 수행합니다.

  • XSD 스키마에 대해 XML 메시지 유효성 검사
  • WSDL 정의에 대해 SOAP 메시지 유효성 검사
  • JSON 및 XML 메시지의 형식이 올바른지 확인

UI에서 이 정책 이름은 SOAPMessageValidation이지만 정책은 SOAP 메시지만 검증하는 것은 아닙니다. 이 섹션에서는 이 정책을 MessageValidation 정책이라고 부릅니다.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 모든 사용자가 정책 및 환경 유형에 대해 알아야 할 필요는 없습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

<MessageValidation> 요소

MessageValidation 정책을 정의합니다.

기본값 아래의 기본 정책 탭을 참조하세요.
필수 여부 선택사항
유형 복합 객체
상위 요소 해당 사항 없음
하위 요소 <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

구문

<MessageValidation> 요소는 다음 구문을 사용합니다.

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

기본 정책

다음 예시에서는 Apigee UI의 흐름에 MessageValidation 정책을 추가할 때의 기본 설정을 보여줍니다.

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성 기본 필수 여부 설명
name 해당 없음 필수

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

continueOnError false 선택 정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:
enabled true 선택 정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async   false 지원 중단됨 이 속성은 지원이 중단되었습니다.

예시

다음 예시는 MessageValidation 정책을 사용할 수 있는 몇 가지 방법을 보여줍니다.

1: XSD 유효성 검사

메시지 유효성 검사 정책을 사용하여 XSD 스키마에 대한 XML 메시지 요청 페이로드의 유효성 검사를 할 수 있습니다.

  1. 새 XSD 리소스 파일을 만듭니다. 예를 들어 note-schema.xsd입니다.
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="note">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="to" type="xs:string"/>
            <xs:element name="from" type="xs:string"/>
            <xs:element name="heading" type="xs:string"/>
            <xs:element name="body" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  2. 프록시 엔드포인트의 사전 흐름에 SOAP 메시지 유효성 검사 정책을 추가합니다.
    1. <ResourceURL> 요소로 XSD 리소스 파일의 위치를 지정합니다. 예를 들면 다음과 같습니다.
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. 정책 정의에서 <SOAPMessage><Element> 요소를 삭제합니다.

    정책 정의는 다음과 같아야 합니다.

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. 다음 예에 표시된 것처럼 XML을 메시지 페이로드로 사용하여 API 프록시에 POST 요청을 보냅니다.
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<note>
      <to>Fred Rogers</to>
      <from>Nick Danger</from>
      <heading>Greetings from my neighborhood</heading>
      <body>Just writing to say hello.</body>
    </note>'

    Content-type 헤더가 application/xml으로 설정되어 있습니다.

    또한 페이로드에 대한 데이터 파일을 만들고 다음과 비슷한 명령어로 참조할 수 있습니다.

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

HTTP 200 응답이 수신됩니다. 대상 엔드포인트에 따라 요청에 대한 추가 세부정보가 전송될 수 있습니다. 예를 들어 http://httpbin.org/post를 대상 엔드포인트로 사용하고 -v(세부정보) 출력을 지정하면 응답은 다음과 유사합니다.

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

XSD 유효성 검사가 제대로 작동하는지 확인하려면 요청 본문에 다른 태그를 삽입해 보세요. 예를 들면 다음과 같습니다.

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

유효성 검사 오류가 표시되어야 합니다.

2: SOAP 유효성 검사

메시지 유효성 검사 정책을 사용하여 WSDL에 대한 SOAP 메시지 요청의 페이로드를 확인할 수 있습니다.

  1. 새 WSDL 리소스 파일을 만듭니다. 예를 들어 'example-wsdl.wsdl'입니다.
  2. 프록시 엔드포인트의 사전 흐름에 SOAP 메시지 유효성 검사 정책을 추가합니다.
    1. <SOAPMessage> 요소의 version 유효성을 검사할 SOAP 프로토콜의 버전으로 설정합니다. 예를 들면, '1.1'입니다.
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. <Element> 요소의 값을 유효성을 검사할 요소로 설정합니다.
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element>는 SOAP 요청 메일에 있는 <Body> 요소의 첫 번째 하위 요소를 지정합니다.

      namespace 속성을 해당 하위 요소의 네임스페이스로 설정합니다.

    3. <ResourceURL> 요소로 WSDL 리소스 파일의 위치를 지정합니다. 예를 들면 다음과 같습니다.
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    정책 정의는 다음과 같아야 합니다.

    <MessageValidation continueOnError="false"
        enabled="true" name="validateSOAPRequest">
      <DisplayName>My SOAP Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <SOAPMessage version="1.1"/>
      <Element namespace="https://example.com/gateway">getID</Element>
      <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
    </MessageValidation>
  3. 다음 예시와 같이 SOAP 메일을 API 페이로드로 사용하여 API 프록시에 POST 요청을 보냅니다.
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
      <soapenv:Header/>
      <soapenv:Body>
        <prox:getID>
          <typ:MyType>
            <typ:ID>42</typ:ID>
          </typ:MyType>
        </prox:getID>
      </soapenv:Body>
    </soapenv:Envelope>'

    Content-type 헤더가 'application/xml'로 설정되어 있습니다.

    또한 페이로드에 대한 데이터 파일을 만들고 다음과 비슷한 명령어로 참조할 수 있습니다.

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

HTTP 200 응답이 수신됩니다. 대상 엔드포인트에 따라 요청에 대한 추가 세부정보가 전송될 수 있습니다. 예를 들어 http://httpbin.org/post을 대상 엔드포인트로 사용할 경우 응답은 다음과 비슷합니다.

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: 올바른 형식의 XML/JSON

메시지 유효성 검사 정책을 사용하여 JSON 또는 XML 메시지 페이로드가 올바른 형식인지 확인할 수 있습니다(유효성 검사와 다름). 이 정책은 구조 및 콘텐츠가 다음과 같은 허용되는 표준을 충족하게 합니다.

  • 단일 루트 요소가 있습니다.
  • 콘텐츠에 유효하지 않은 문자가 없습니다.
  • 객체와 태그가 올바르게 중첩됩니다.
  • 시작 및 종료 태그가 일치합니다.

올바른 형식의 XML 또는 JSON 페이로드를 확인하려면 다음 안내를 따르세요.

  1. 프록시 엔드포인트의 사전 흐름에 SOAP 메시지 유효성 검사 정책을 추가합니다.
  2. 정책 정의에서 <ResourceURL>, <SOAPMessage>, <Element> 요소를 제거합니다.

    정책 정의는 다음과 같아야 합니다.

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. 다음 예시와 같이 API 프록시에 POST 요청을 보냅니다.
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
      -d '{
    "note": {
      "to": "Fred Rogers",
      "from": "Nick Danger",
      "header": "Greetings from my neighborhood",
      "body": "Just writing to say hello."
      }
    }'

    Content-type 헤더가 application/json으로 설정되어 있습니다.

    XML 파일의 형식이 올바른지 확인하려면 XML을 메시지 페이로드로 사용하고 Content-typeapplication/xml로 설정합니다.

HTTP 200 응답이 수신됩니다. 올바른 형식의 XML 또는 JSON이 포함되지 않은 메시지 페이로드를 전송하면 steps.messagevalidation.Failed 오류가 발생합니다.

하위 요소 참조

이 섹션에서는 <MessageValidation>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값 해당 사항 없음
필수 여부 선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형 문자열
상위 요소 <PolicyElement>
하위 요소 없음

<DisplayName> 요소는 다음 구문을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예시

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<Element>

유효성을 검사할 메시지의 요소를 지정합니다. 이것은 SOAP 요청 메일에 있는 <Body> 요소의 첫 번째 하위 요소입니다.

기본값 sampleObject
필수 여부 선택사항
유형 문자열
상위 요소 <MessageValidation>
하위 요소 없음

<Element> 요소는 다음 구문을 사용합니다.

구문

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

예시 1

다음 예에서는 유효성을 검사할 단일 요소를 정의합니다.

...
<Element namespace="https://example.com/gateway">getID</Element>
...

예시 2

여러 <Element> 요소를 추가하여 검사할 요소를 2개 이상 지정할 수 있습니다.

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

<Element> 요소에는 다음과 같은 속성이 있습니다.

속성 기본 필수 여부 설명
namespace "http://sample.com" 선택사항 검사할 요소의 네임스페이스를 정의합니다.

<ResourceURL>

소스 메시지의 유효성을 검사하는 데 사용할 XSD 스키마 또는 WSDL 정의를 식별합니다.

기본값 wsdl://display_name.wsdl
필수 여부 선택사항
유형 문자열
상위 요소 <MessageValidation>
하위 요소 없음

<ResourceURL> 요소는 다음 구문을 사용합니다.

구문

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

예시

XML 파일의 경우:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

WSDL의 경우:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

<ResourceURL> 값은 API 프록시의 리소스 파일을 가리켜야 합니다. HTTP 또는 HTTPS를 통해 외부 리소스를 참조할 수 없습니다.

<ResourceURL> 값을 지정하지 않는 경우 메시지는 올바른 형식의 JSON 또는 XML에서 Content-type 헤더가 application/json 또는 application/xml인지 확인됩니다.

<ResourceURL> 요소에 하위 요소나 속성이 없습니다.

유효성 검사에 XSD 사용

MessageValidation 정책을 통해 확인하는 XML 페이로드가 다른 스키마를 참조하는 경우 포함된 XSD 파일을 schemaLocation 속성에 있는 xsd에 프리픽스로 추가해야 합니다.

다음 스키마 예시는 여러 XSD로 구성됩니다.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

유효성 검사를 위해 WSDL 사용

WSDL은 반드시 하나 이상의 스키마를 정의해야 합니다. 최소 1개의 스키마를 참조하지 않으면 MessageValidation 정책이 실패합니다.

스키마의 최대 가져오기 깊이는 10입니다. 중첩된 가져오기 수를 초과하면 MessageValidation 정책이 실패합니다.

<SOAPMessage>

MessageValidation 정책이 검증하는 대상에 대한 SOAP 버전을 정의합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 해당 사항 없음
상위 요소 <MessageValidation>
하위 요소 없음

<SOAPMessage> 요소는 다음 구문을 사용합니다.

구문

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

예시

...
<SOAPMessage version="1.1"/>
...

<SOAPMessage> 요소에는 다음과 같은 속성이 있습니다.

속성 기본 필수 여부 설명
version 없음 선택사항 이 정책이 SOAP 메시지를 확인하는 데 사용하는 SOAP 버전입니다.

유효한 값은 다음과 같습니다.

  • '1.1'
  • '1.2'
  • "1.1/1.2"

자세한 내용은 9포인트의 SOAP/1.1에서 SOAP 버전 1.2까지를 참조하세요.

<Source>

유효성을 검사할 소스 메시지를 식별합니다. 이 요소의 값은 유효성을 검사할 메시지의 이름입니다.

<Source>를 설정하지 않으면 이 정책의 기본값은 message이며 모든 페이로드를 포함하여 전체 요청 메시지(요청 흐름) 또는 응답 메시지(응답 흐름)를 참조합니다. request 또는 response로 명시적으로 설정하여 요청이나 응답을 참조할 수도 있습니다.

기본값 요청
필수 여부 선택사항
유형 문자열
상위 요소 <MessageValidation>
하위 요소 없음

<Source> 요소는 다음 구문을 사용합니다.

구문

...
  <Source>message_to_validate</Source>
...

예시

...
<Source>request</Source>
...

message, request, response 외에도 <Source> 값을 흐름의 모든 메시지 이름으로 설정할 수 있습니다. 하지만 이렇게 하는 경우에는 이 정책이 실행되기 전에 흐름에 해당 이름의 커스텀 메시지를 만들어야 합니다. 그렇지 않으면 오류가 발생합니다.

<Source> 값을 메시지 흐름에서 해결할 수 없거나 메시지 외 유형으로 해결할 수 없는 경우 다음 중 하나가 발생합니다.

  • null 값인 경우: Apigee에서 steps.messagevalidation.SourceMessageNotAvailable 오류가 발생합니다.
  • 메시지 외 유형인 경우: Apigee에서 steps.messagevalidation.NonMessageVariable 오류가 발생합니다.

<Source> 요소에 속성 또는 하위 요소가 없습니다.

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 원인 해결
steps.messagevalidation.SourceMessageNotAvailable 500

이 오류는 정책의 <Source> 요소에 지정된 변수가 다음 중 하나인 경우에 발생합니다.

  • 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음)
  • 또는
  • 확인할 수 없는 경우(정의되지 않음)
steps.messagevalidation.NonMessageVariable 500

이 오류는 SOAPMessageValidation 정책의 <Source> 요소가 메시지 유형이 아닌 변수로 설정된 경우 발생합니다.

메시지 유형 변수는 전체 HTTP 요청 및 응답을 나타냅니다. 기본 제공 Apigee 흐름 변수 request, response, message는 메시지 유형입니다. message 변수에 대한 자세한 내용은 변수 참조를 확인하세요.

steps.messagevalidation.Failed 500 이 오류는 SOAPMessageValidation 정책이 XSD 스키마 또는 WSDL 정의에 대해 입력 메시지 페이로드의 유효성을 검사하는 데 실패하는 경우 발생합니다. 페이로드 메시지에 잘못된 JSON 또는 XML이 있는 경우에도 이 오류가 발생합니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 원인 수정
InvalidResourceType SOAPMessageValidation 정책의 <ResourceURL> 요소는 정책에서 지원하지 않는 리소스 유형으로 설정됩니다.
ResourceCompileFailed SOAPMessageValidation 정책의 <ResourceURL> 요소에서 참조하는 리소스 스크립트에 컴파일하지 못하도록 하는 오류가 포함되어 있습니다.
RootElementNameUnspecified SOAPMessageValidation 정책의 <Element> 요소에 루트 요소의 이름이 포함되지 않습니다.
InvalidRootElementName SOAPMessageValidation 정책의 <Element> 요소에는 유효한 요소 이름을 지정할 때 XML 규칙을 준수하지 않는 루트 요소 이름이 포함되어 있습니다.

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

관련 주제