JSONtoXML ポリシー

概要

このポリシーは、メッセージを JavaScript Object Notation （JSON）形式から拡張マークアップ言語（XML）形式に変換します。このため、メッセージの変換方法を制御する選択肢が多彩になります。

このポリシーは、XSL を使用してメッセージを変換する場合に特に便利です。JSON ペイロードを XML に変換したら、カスタム スタイルシートとともに XSL Transform ポリシーを使用して、必要な変換を行います。

JSON 形式のリクエストを XML 形式のリクエストに変換する意図であるとして、ポリシーはリクエスト フロー（たとえば Request / ProxyEndpoint / PostFlow）に添付されます。

サンプル

JSON と XML の間の変換について詳しくは、http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html をご覧ください。

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

要素リファレンス

このポリシーで構成できる要素と属性は次のとおりです。

<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> 属性

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

<Source> 要素

XML に変換する JSON メッセージが含まれる変数、リクエスト、またはレスポンスです。

<Source> が定義されていない場合は、メッセージとして処理されます（ポリシーがリクエスト フローに接続されている場合はリクエスト、ポリシーがレスポンス フローに接続されている場合はレスポンスに解決される）。

ソース変数を解決できない場合、あるいはメッセージ以外のタイプに解決される場合、ポリシーはエラーを返します。

<Source>request</Source>

<OutputVariable> 要素

JSON to XML 形式変換の出力を格納します。これは通常、ソースと同じ値です。つまり、通常は JSON リクエストが XML リクエストに変換されます。

JSON メッセージのペイロードが解析されて XML に変換され、XML 形式のメッセージの HTTP Content-type ヘッダーは text/xml;charset=UTF-8 に設定されます。

OutputVariable が指定されていない場合、source は OutputVariable として扱われます。たとえば、source が request である場合、OutputVariable のデフォルトは request になります。

<OutputVariable>request</OutputVariable>

<Options>/<OmitXmlDeclaration>

出力から XML 名前空間を省略するように指定します。デフォルト値は false で、出力に名前空間が含まれます。

たとえば、次の設定は名前空間を省略するようにポリシーを構成します。

<OmitXmlDeclaration>true</OmitXmlDeclaration>

<Options>/<NamespaceBlockName> 要素
<Options>/<DefaultNamespaceNodeName> 要素
<Options>/<NamespaceSeparator> 要素

JSON は名前空間をサポートしていませんが、XML 文書では多くの場合必要になります。 NamespaceBlockName を使用すると、JSON プロパティを定義できます。これはポリシーによって生成された XML で名前空間定義のソースとして機能します（つまりソース JSON は、生成される XML を利用するアプリケーションが期待する名前空間にマッピングできるプロパティを提供する必要があります）。

たとえば次の設定は、

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

デフォルトとして指定された名前空間を少なくとも 1 つ含む #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"
]

次の 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>

{"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 ポリシーを、送信レスポンス フローでの XML to JSON ポリシーとペアにします。ポリシーをこのように組み合わせることで、XML のみをネイティブにサポートするサービスに対して JSON API を公開できます。

多くの場合、デフォルトの（空の）JSON to XML ポリシーを適用し、必要に応じて構成要素を繰り返し追加すると便利です。

API が、JSON と XML のどちらかを必要とするさまざまなクライアント アプリで使用されるシナリオでは、条件付きで実行するように JSON to XML ポリシーと XML to JSON ポリシーを構成することで、レスポンスのフォーマットを動的に設定できます。このシナリオの実装については、フロー変数と条件をご覧ください。

スキーマ

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 to JSON: XML to JSON ポリシー
• XSL 変換: XSL Transform ポリシー