JSONtoXML 정책

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

Apigee Edge 문서 보기

대상

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

이 정책은 XSL을 사용하여 메시지를 변환하려는 경우에 특히 유용합니다. JSON 페이로드를 XML로 변환한 후 커스텀 스타일 시트와 함께 XSL Transform 정책을 사용하여 필요한 변환을 수행합니다.

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

참고: 소스 메시지의 HTTP Content-type 헤더가 application/json으로 설정되어 있어야 합니다. 그렇지 않으면 처리 중에 정책을 건너뛰어 정책이 적용되지 않습니다.

JSON 형식의 요청을 XML 형식 요청으로 변환한다고 가정하면 정책이 요청 흐름(예: Request / ProxyEndpoint / PostFlow)에 연결됩니다.

샘플

자세한 내용은 Apigee를 사용하여 XML 및 JSON 간 변환: 알아야 할 사항을 참조하세요.

요청 변환

<JSONToXML name="jsontoxml">
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
</JSONToXML>

이 구성은 JSON 형식의 요청 메시지를 소스로 받은 다음 request OutputVariable에 채워진 XML 형식 메시지를 만듭니다. Apigee는 자동으로 이 변수의 내용을 다음 처리 단계의 메시지로 사용합니다.

---

요소 참조

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

<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1">
    <DisplayName>JSON to XML 1</DisplayName>
    <Source>request</Source>
    <OutputVariable>request</OutputVariable>
    <Options>
        <OmitXmlDeclaration>false</OmitXmlDeclaration>
        <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
        <NamespaceSeparator>:</NamespaceSeparator>
        <AttributeBlockName>#attrs</AttributeBlockName>
        <AttributePrefix>@</AttributePrefix>
        <ObjectRootElementName>Root</ObjectRootElementName>
        <ArrayRootElementName>Array</ArrayRootElementName>
        <ArrayItemElementName>Item</ArrayItemElementName>
        <Indent>false</Indent>
        <TextNodeName>#text</TextNodeName>
        <NullValue>I_AM_NULL</NullValue>
        <InvalidCharsReplacement>_</InvalidCharsReplacement>
    </Options>
</JSONToXML>

<JSONToXML> 속성

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

속성	설명	기본값	Presence
name	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
enabled	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
async	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

기본값	해당 사항 없음 이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

<Source> 요소

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

참고: 소스 메시지의 HTTP Content-type 헤더가 application/json으로 설정되어 있어야 합니다. 그렇지 않으면 처리 중에 정책을 건너뛰어 정책이 적용되지 않습니다.

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

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

<Source>request</Source>

기본값	API 프록시 흐름에 추가되는 정책 위치에 따라 결정되는 요청 또는 응답
Presence	선택사항
유형	메시지

<OutputVariable> 요소

JSON에서 XML 형식으로 변환한 출력을 저장합니다. 이는 보통 소스와 동일한 값이며, 일반적으로 JSON 요청은 XML 요청으로 변환됩니다.

JSON 메시지의 페이로드는 파싱되어 XML로 변환되며 XML 형식 메시지의 HTTP Content-type 헤더는 text/xml;charset=UTF-8로 설정됩니다.

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

<OutputVariable>request</OutputVariable>

기본값	API 프록시 흐름에 추가되는 정책 위치에 따라 결정되는 요청 또는 응답
Presence	이 요소는 <Source> 요소에 정의된 변수가 유형 문자열일 때 필수입니다.
유형	메시지

<Options>/<OmitXmlDeclaration>

출력에서 XML 선언 줄을 생략하도록 지정합니다. XML 선언 줄은 선택적으로 XML 문서 위에 표시될 수 있습니다. 다음은 일반적인 예시입니다.

<?xml version="1.0" encoding="UTF-8"?>

일부 경우에는 이 정책의 출력에 이러한 줄을 포함하지 않아야 합니다. 한 가지 좋은 예시는 이 정책의 출력을 더 큰 XML 문서에 하나의 조각으로 삽입하도록 계획하는 것입니다. 선언은 문서 맨 위에 한 번만 나타나야 하므로 XML 프래그먼트에서 XML 선언 줄을 표시하지 않는 것이 중요합니다.

이 옵션의 기본값은 false이며 이는 정책이 출력에 XML 선언 줄을 포함함을 의미합니다. 다음 설정은 XML 선언을 생략하도록 정책을 구성합니다.

<OmitXmlDeclaration>true</OmitXmlDeclaration>

이 정책의 구성을 통해 XML 선언 줄의 내용을 구성하거나 이에 영향을 주는 방법은 없습니다. 정책은 항상 UTF-8 인코딩 텍스트를 생성하고, 항상 XML 버전 1.0을 사용하며, 선언 줄이 포함된 경우 이를 반영합니다.

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

JSON에는 네임스페이스가 지원되지 않지만 XML 문서에는 종종 네임스페이스가 필요합니다. NamespaceBlockName을 사용하면 정책으로 생성된 XML의 네임스페이스 정의 소스 역할을 하는 JSON 속성을 정의할 수 있습니다. (즉, 소스 JSON은 결과 XML을 사용하는 애플리케이션에서 예상하는 네임스페이스에 매핑할 수 있는 속성을 제공해야 합니다.)

다음 설정을 예시로 들 수 있습니다.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
<NamespaceSeparator>:</NamespaceSeparator>

이 설정은 #namespaces라는 속성이 기본값으로 지정된 네임스페이스가 하나 이상 포함된 소스 JSON에 있음을 나타냅니다. 예를 들면 다음과 같습니다.

{
   "population": {
       "#namespaces": {
           "$default": "http://www.w3.org/1999/people",
           "exp": "http://www.w3.org/1999/explorers"
       },
       "person": "John Smith",
       "exp:person": "Pedro Cabral"
   }
}

다음으로 변환됩니다.

<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers">
  <person>John Smith</person>
  <exp:person>Pedro Cabral</exp:person>
</population>

<Options>/<ObjectRootElementName>

<ObjectRootElementName>은 이름이 지정된 루트 요소가 없는 JSON에서 변환할 때 루트 요소 이름을 XML로 지정합니다.

예를 들어 JSON이 다음과 표시되는 경우를 살펴보겠습니다.

{
  "abc": "123",
  "efg": "234"
}

그리고 <ObjectRootElementName>을 다음과 같이 설정합니다.

<ObjectRootElementName>Root</ObjectRootElementName>

결과 XML은 다음과 같이 표시됩니다.

<Root>
   <abc>123</abc>
   <efg>234</efg>
</Root>

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

<AttributeBlockName>을 사용하면 JSON 요소를 XML 요소가 아닌 XML 속성으로 변환하는 시점을 지정할 수 있습니다.

예를 들어 다음 설정은 #attrs라는 객체의 속성을 XML 속성으로 변환합니다.

<AttributeBlockName>#attrs</AttributeBlockName>

다음은 JSON 객체입니다.

{
    "person" : {
        "#attrs" : {
            "firstName" : "John",
            "lastName" : "Smith"
        },        
        "occupation" : "explorer",
    }
}

이 객체는 다음과 같은 XML 구조로 변환됩니다.

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<AttributePrefix>는 지정된 프리픽스로 시작하는 속성을 XML 속성으로 변환합니다. 여기서 속성 프리픽스가 @으로 설정된 다음 예시를 살펴보겠습니다.

<AttributePrefix>@</AttributePrefix>

다음과 같은 JSON 객체를 변환합니다.

{
"person" : {
   "@firstName" : "John",
   "@lastName" : "Smith"
   "occupation" : "explorer",

 }
}

다음과 같은 XML 구조로 변환됩니다.

<person firstName="John" lastName="Smith">
  <occupation>explorer</occupation>
</person>

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> 요소

JSON 배열을 지정된 상위 요소 및 하위 요소 이름이 있는 XML 요소의 목록으로 변환합니다.

다음 설정을 예시로 들 수 있습니다.

<ArrayRootElementName>Array</ArrayRootElementName>
<ArrayItemElementName>Item</ArrayItemElementName>

설정은 다음 JSON 배열을 변환합니다.

[
"John Cabot",
{
 "explorer": "Pedro Cabral"
},
"John Smith"
]

JSON 배열을 다음과 같은 XML 구조로 변환합니다.

<Array>
  <Item>John Cabot</Item>
  <Item>
    <explorer>Pedro Cabral</explorer>
  </Item>
  <Item>John Smith</Item>
</Array>

<Options>/<Indent>

XML 출력을 들여 쓰도록 지정합니다. 기본값은 false로 들여 쓰지 않는다는 의미입니다.

예를 들어 다음 설정은 출력을 들여 쓰도록 정책을 구성합니다.

<Indent>true</Indent>

JSON 입력이 다음과 같은 경우를 살펴보겠습니다.

{"n": [1, 2, 3] }

그런 다음 들여 쓰이지 않은 다음과 같은 출력이 표시됩니다.

<Array><n>1</n><n>2</n><n>3</n></Array>

들여쓰기가 사용 설정되어 있으면 다음과 같이 출력됩니다.

  <Array>
    <n>1</n>
    <n>2</n>
    <n>3</n>
  </Array>

<Options>/<TextNodeName> 요소

JSON 속성을 지정된 이름의 XML 텍스트 노드로 변환합니다. 다음 설정을 예시로 들 수 있습니다.

<TextNodeName>age</TextNodeName>

다음과 같이 이 JSON을 변환합니다.

{
    "person": {
        "firstName": "John",
        "lastName": "Smith",
        "age": 25
    }
}

다음과 같이 이 XML 구조로 변환됩니다.

<person>
  <firstName>John</firstName>25<lastName>Smith</lastName>
</person>

TextNodeName을 지정하지 않으면 텍스트 노드에 대해 기본 설정을 사용하여 XML이 생성됩니다.

<person>
  <firstName>John</firstName>
  <age>25</age>
  <lastName>Smith</lastName>
</person>

<Options>/<NullValue> 요소

null 값을 나타냅니다. 기본값은 NULL입니다.

다음 설정을 예시로 들 수 있습니다.

<NullValue>I_AM_NULL</NullValue>

다음과 같은 JSON 객체를 변환합니다.

{"person" : "I_AM_NULL"}

다음과 같은 XML 요소로 변환됩니다.

<person></person>

Null 값에 아무런 값 또는 I_AM_NULL 이외의 값이 지정되지 않은 경우 동일한 페이로드가 다음과 같이 변환됩니다.

<person>I_AM_NULL</person>

<Options>/<InvalidCharsReplacement> 요소

파서에 문제를 일으킬 수 있는 잘못된 XML 처리를 지원하기 위해 이 설정은 잘못된 XML을 생성하는 JSON 요소를 문자열로 대체합니다. 다음 설정을 예시로 들 수 있습니다.

<InvalidCharsReplacement>_</InvalidCharsReplacement>

다음과 같이 이 JSON 객체를 변환합니다.

{
    "First%%%Name": "John"
}

다음과 같이 이 XML 구조로 변환됩니다.

<First_Name>John<First_Name>

---

사용 참고사항

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

이는 종종 기본(빈) JSON을 XML 정책에 적용하고 필요에 따라 반복적으로 구성 요소를 추가할 때 유용합니다.

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

스키마

샘플: 최신 스키마는 GitHub 저장소 샘플을 참조하세요.

오류 참조

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

런타임 오류

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

팁: 오류를 해결하는 데 도움이 필요하신가요? 해결 열의 를 클릭하여 자세한 문제해결 정보를 확인합니다.

오류 코드	HTTP 상태	원인	수정
steps.jsontoxml.ExecutionFailed	500	입력 페이로드(JSON)가 비어 있거나 JSON-XML 정책에 전달되는 입력(JSON)이 무효이거나 형식이 잘못되었습니다.
steps.jsontoxml.InCompatibleTypes	500	이 오류는 <Source> 요소 및 <OutputVariable> 요소에 정의된 변수 유형이 동일하지 않을 때 발생합니다. <Source> 요소 및 <OutputVariable> 요소 내에 포함된 변수는 유형이 일치해야 합니다. 유효한 message 유형은 string 및 입니다.
steps.jsontoxml.InvalidSourceType	500	이 오류는 <Source> 요소를 정의하기 위해 사용되는 변수 유형이 무효인 경우에 발생합니다. 유효한 변수 유형은 message 및 string입니다.
steps.jsontoxml.OutputVariableIsNotAvailable	500	이 오류는 <Source> JSON-XML 정책의 요소에 지정된 변수가 문자열 유형이고 <OutputVariable> 요소가 정의되지 않은 경우에 발생합니다. <Source> 요소에 정의된 변수가 문자열 유형인 경우 <OutputVariable> 요소는 필수입니다.
steps.jsontoxml.SourceUnavailable	500	이 오류는 JSON-XML 정책의 <Source> 요소에 지정된 메시지 변수가 다음 중 하나인 경우 발생합니다. 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음) 확인할 수 없는 경우(정의되지 않음)

배포 오류

없음.

오류 변수

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

변수	장소	예
fault.name="fault_name"	fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed	policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	jsontoxml.JSON-to-XML-1.failed = true

오류 응답 예시

참고: 오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

{
  "fault": {
    "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.json2xml.SourceUnavailable"
    }
  }
}

오류 규칙 예시

<FaultRule name="JSON To XML Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadJSON</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition>
</FaultRule>

관련 주제

• XML에서 JSON으로 변환: XML to JSON 정책
• XSL 변환: XSL Transform 정책