XMLtoJSON 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서. 정보

대상

이 정책은 메시지를 확장 가능한 마크업 언어(XML) 형식에서 JSON(JavaScript Object Notation) 형식으로 변환하여 메시지 변환 방법을 제어할 수 있는 여러 옵션을 제공합니다.

인텐트가 XML 형식의 응답을 JSON 형식의 응답으로 변환한다고 가정하면 정책이 응답 흐름(예: Response / ProxyEndpoint / PostFlow)에 연결됩니다.

정보

일반적인 미디에이션 시나리오에서 인바운드 요청 흐름의 JSON to XML 정책은 종종 아웃바운드 응답 흐름의 XML to JSON 정책과 결합됩니다. 이런 방식으로 정책을 결합하면 기본적으로 XML만 지원하는 백엔드 서비스에 JSON API를 노출시킬 수 있습니다.

JSON 또는 XML 중 하나를 필요로 할 수 있는 다양한 클라이언트 앱에서 API를 사용하는 시나리오의 경우, JSON to XML 및 XML to JSON 정책이 조건부로 실행되도록 구성하여 응답 형식을 동적으로 설정할 수 있습니다. 이 시나리오의 구현은 흐름 변수 및 조건을 참조하세요.

샘플

JSON 및 XML 간 변환에 대한 자세한 내용은 http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html을 참조하세요.

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다.

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

<XMLtoJSON> 속성

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1"> 

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<Source> 요소

JSON으로 변환할 XML 메시지가 포함된 변수, 요청, 응답입니다.

소스 메시지의 HTTP 콘텐츠 유형 헤더는 application/xml로 설정해야 합니다. 그렇지 않으면 정책이 시행되지 않습니다.

<Source>가 정의되어 있지 않으면 정책이 요청 흐름에 연결될 때 요청으로 확인하거나 정책이 응답 흐름에 연결될 때 응답으로 확인하는 메시지로 취급됩니다.

소스 변수를 확인할 수 없거나 메시지 유형이 아닌 것으로 확인될 경우 정책에 오류가 발생합니다.

<Source>response</Source>

<OutputVariable> 요소

XML to JSON 형식으로의 출력을 저장합니다. 이는 일반적으로 소스와 동일한 값으로 일반적으로 XML 응답이 JSON 응답으로 변환됩니다.

XML 메시지의 페이로드는 파싱되어 JSON으로 변환되며 XML 형식 메시지의 HTTP Content-type 헤더는 application/json로 설정됩니다.

OutputVariable을 지정하지 않으면 source가 OutputVariable으로 취급됩니다. 예를 들어 source가 response인 경우 OutputVariable의 기본값은 response입니다.

<OutputVariable>response</OutputVariable>

<Options>

옵션을 사용하면 XML to JSON 변환을 제어할 수 있습니다. 특정 전환 설정을 추가할 수 있는 <Options> 그룹 또는 사전 정의된 옵션의 템플릿을 참조할 수 있는 <Format> 요소를 사용합니다. <Options> 및 <Format>을 둘 다 사용할 수는 없습니다.

<Format>을 사용하지 않는 경우 <Options>이 필요합니다.

<Options>/<RecognizeNumber> 요소

true이면 XML 페이로드의 숫자 필드가 원래 형식을 유지합니다.

<RecognizeNumber>true</RecognizeNumber>

다음 XML 예시를 살펴보세요.

<a>
  <b>100</b>
  <c>value</c>
</a>

true이면 다음과 같이 변환합니다.

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

false이면 다음과 같이 변환합니다.

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

<Options>/<RecognizeBoolean> 요소

값을 문자열로 변환하지 않고 변환이 부울의 true/false 값을 유지하도록 합니다.

<RecognizeBoolean>true</RecognizeBoolean>

다음 XML 예시를 참조하세요.

<a>
  <b>true</b>
  <c>value</c>
</a>

true이면 다음과 같이 변환합니다.

{
    "a": {
        "b": true,
        "c": "value"
    }
}

false이면 다음과 같이 변환합니다.

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

<Options>/<RecognizeNull> 요소

빈 값을 null 값으로 변환할 수 있습니다.

<RecognizeNull>true</RecognizeNull>

다음 XML의 경우:

<a>
  <b></b>
  <c>value</c>
</a>

true이면 다음과 같이 변환합니다.

{
  "a": {
    "b": null,
    "c": "value"
  }
}

false이면 다음과 같이 변환합니다.

{
  "a": {
    "b": {},
    "c": "value"
  }
}

<Options>/<NullValue> 요소

소스 메시지에서 인식된 null 값이 변환되어야 하는 값을 나타냅니다. 기본값은 null입니다. 이 옵션은 RecognizeNull이 true인 경우에만 적용됩니다.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> 요소

다음 요소를 함께 사용하세요.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

다음 XML 예시를 살펴보세요.

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

NamespaceSeparator가 지정되지 않으면 다음 JSON 구조가 생성됩니다.

{
    "a": {
        "b": "value"
    }
}

NamespaceBlockName, DefaultNamespaceNodeName, NamespaceSeparator 요소가 각각 #namespaces, &, ***로 지정되면 다음 JSON 구조가 생성됩니다.

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName> 요소

다음 요소를 함께 사용하세요.

true로 설정하면 XML 요소의 콘텐츠가 문자열 속성으로 변환됩니다.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

다음 XML의 경우:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

TextAlwaysAsProperty가 true로 설정되고 TextNodeName이 TEXT로 지정되면 다음 JSON 구조가 생성됩니다.

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

TextAlwaysAsProperty가 false로 설정되고 TextNodeName이 TEXT로 지정되면 다음 JSON 구조가 생성됩니다.

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> 요소

다음 요소를 함께 사용하세요.

값을 JSON 블록으로 그룹화하고 속성 이름에 프리픽스를 추가할 수 있습니다.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

다음 XML 예시를 살펴보세요.

<a attrib1="value1" attrib2="value2"/>

속성(AttributeBlockName 및 AttributePrefix)이 XML to JSON 예시에서 정의된 것처럼 지정된 경우 다음과 같은 JSON 구조가 생성됩니다.

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

AttributeBlockName만 지정되면 다음 JSON 구조가 생성됩니다.

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

AttributePrefix만 지정되면 다음 JSON 구조가 생성됩니다.

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

모두 지정하지 않으면 다음 JSON 구조가 생성됩니다.

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

<Options>/<OutputPrefix>
<Options>/<OutputSuffix> 요소

다음 요소를 함께 사용하세요.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

다음 XML 예시를 살펴보세요.

<a>value</a>

속성(OutputPrefix 및 OutputSuffix)이 XML to JSON 예시에서 정의된 것처럼 지정된 경우 다음과 같은 JSON 구조가 생성됩니다.

PREFIX_{
    "a": "value"
}_SUFFIX

OutputPrefix만 지정되면 다음 JSON 구조가 생성됩니다.

PREFIX_{
  "a" : "value"
}

OutputSuffix만 지정되면 다음 JSON 구조가 생성됩니다.

{
  "a" : "value"
}_SUFFIX

OutputPrefix와 OutputSuffix를 모두 지정하지 않으면 다음 JSON 구조가 생성됩니다.

{
    "a": "value"
}

<Options>/<StripLevels> 요소

<Options>
    <StripLevels>4</StripLevels>
</Options>

때로는 SOAP와 같은 XML 페이로드에 변환된 JSON에 포함하지 않을 상위 단계가 여러 개 있을 수 있습니다. 다음은 여러 단계를 포함하는 SOAP 응답의 예시입니다.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

주, 도시, 설명, 온도까지 4단계가 있습니다. <StripLevels>를 사용하지 않을 경우 JSON 응답이 다음과 같이 변환됩니다.

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

JSON 응답에서 처음 4단계를 제거하려면 <StripLevels>4</StripLevels>를 설정합니다. 그러면 다음과 같은 JSON이 제공됩니다.

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

하위 요소가 여러 개 포함된 첫 번째 요소까지 단계를 제거할 수 있습니다. 무엇을 뜻하나요? 좀 더 복잡한 JSON 예시를 살펴보겠습니다.

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

이 예시의 3단계는 하나의 하위 항목만 있는 GetCityForecastByZIPResponse입니다. <StripLevels>3</StripLevels>(처음 3개 단계를 삭제)를 사용하면 JSON은 다음과 같이 표시됩니다.

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

GetCityForecastByZIPResult에는 여러 하위 요소가 있습니다. 이 요소는 여러 하위 요소를 포함하는 첫 번째 요소이므로 <StripLevels>4</StripLevels>를 사용하여 마지막 단계를 제거할 수 있습니다. 그러면 다음과 같은 JSON이 생성됩니다.

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

4단계는 여러 하위 요소를 포함하는 첫 번째 단계이므로 이보다 낮은 단계 제거할 수 없습니다. 스트립 단계를 5, 6, 7 등으로 설정하면 위의 응답이 계속 표시됩니다.

<Options>/<TreatAsArray>/<Path> 요소

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

이 요소 조합을 사용하면 XML 문서의 값이 JSON 배열에 들어가는 것을 확인할 수 있습니다. 이 방법은 하위 요소 수가 1개에서 여러 개로 달라질 수 있고 값이 항상 배열에 있는지 확인하려는 경우에 유용합니다. 이렇게 하면 매번 같은 방식으로 배열에서 데이터를 가져올 수 있으므로 코드를 안정적으로 유지하는 데 도움이 됩니다. 예를 들어 $.teachers.teacher.studentnames[0]는 배열의 값 수에 관계없이 배열의 첫 번째 학생 이름 값을 가져옵니다.

한 발 물러서서 XML to JSON의 기본 동작을 살펴보고 <TreatAsArray>/<Path>를 사용하여 출력을 제어하는 방법을 살펴보겠습니다.

XML 문서에 여러 하위 값이 있는 요소(일반적으로 이 요소가 maxOccurs='unbounded'인 스키마를 기반으로 함)가 포함된 경우, XML to JSON 정책은 해당 값을 배열에 자동으로 배치합니다. 예를 들어 다음 XML 블록의 경우

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

특별한 정책 구성 없이도 자동으로 다음 JSON으로 변환됩니다.

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

두 학생 이름이 배열에 들어가는 것을 확인할 수 있습니다.

그러나 XML 문서에 학생 한 명만 표시되면 다음 예시에서 보여주듯이 XML to JSON 정책은 자동으로 값을 문자열의 배열이 아닌 단일 문자열로 취급합니다.

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

앞의 예시에서는 유사한 데이터가 하나는 배열로, 다른 하나는 단일 문자열로 다르게 변환되었습니다. 여기에서 <TreatAsArray>/<Path> 요소를 사용하여 출력을 제어할 수 있습니다. 예를 들어 값이 하나만 있는 경우에도 학생 이름이 항상 배열에 들어가는 것을 확인할 수 있습니다. 다음과 같이 배열에 값을 배치할 요소의 경로를 식별하여 이를 구성합니다.

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

위 구성은 JSON을 다음과 같이 작성합니다.

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

이제 student1은 배열에 놓인 상태입니다. 이제 학생이 한 명인지 다수인지에 상관없이 다음 JSONPath를 사용하여 코드의 JSON 배열에서 학생을 검색할 수 있습니다. $.teachers.teacher.studentnames.name[0]

<Path> 요소에는 다음 섹션에서 설명하는 unwrap 속성도 있습니다.

속성

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

더 많은 예시와 기능 둘러보기는 Apigee 커뮤니티 문서(https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html)를 참조하세요.

<Format>

형식을 사용하면 XML에서 JSON으로의 변환을 제어할 수 있습니다. 이 주제에서 설명하는 옵션 요소의 특정 조합을 포함하는 사전 정의된 템플릿의 이름을 입력합니다. 사전 정의된 형식은 xml.com, yahoo, google, badgerFish입니다.

<Format> 요소 또는 <Options> 그룹을 사용하세요. <Format> 및 <Options>를 둘 다 사용할 수는 없습니다.

다음은 사전 정의된 각 템플릿의 Format 정의입니다.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

google

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

요소 문법:

<Format>yahoo</Format>

스키마

오류 참조

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

런타임 오류

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

배포 오류

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

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

오류 응답 예시

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

오류 규칙 예시

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

관련 주제

JSON to XML: JSON to XML 정책