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>

この構成では、JSON 形式のリクエスト メッセージをソースとして受け取り、request OutputVariable に入力される XML 形式のメッセージを作成します。Edge はこの変数の内容を、自動的に次の処理ステップのメッセージとして使用します。


要素リファレンス

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

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

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

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<Source> 要素

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

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

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

<Source>request</Source>
デフォルト リクエストまたはレスポンス。ポリシーが API プロキシフローに追加されている場所によって決まります。
要否 省略可
メッセージ

<OutputVariable> 要素

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

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

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

<OutputVariable>request</OutputVariable>
デフォルト リクエストまたはレスポンス。ポリシーが API プロキシフローに追加されている場所によって決まります。
要否 <Source> 要素で定義された変数が文字列型の場合、この要素は必須です。
メッセージ

<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>
次の 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 ポリシーを、送信レスポンス フローでの 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.

Fault code HTTP status Cause Fix
steps.jsontoxml.ExecutionFailed 500 The input payload (JSON) is empty or the input (JSON) passed to JSON to XML policy is invalid or malformed.
steps.jsontoxml.InCompatibleTypes 500 This error occurs if the type of the variable defined in the <Source> element and the <OutputVariable> element are not the same. It is mandatory that the type of the variables contained within the <Source> element and the <OutputVariable> element matches. The valid types are message and string.
steps.jsontoxml.InvalidSourceType 500 This error occurs if the type of the variable used to define the <Source> element is invalid. The valid types of variable are message and string.
steps.jsontoxml.OutputVariableIsNotAvailable 500 This error occurs if the variable specified in the <Source> element of the JSON to XML Policy is of type string and the <OutputVariable> element is not defined. The <OutputVariable> element is mandatory when the variable defined in the <Source> element is of type string.
steps.jsontoxml.SourceUnavailable 500 This error occurs if the message variable specified in the <Source> element of the JSON to XML policy is either:
  • out of scope (not available in the specific flow where the policy is being executed) or
  • can't be resolved (is not defined)

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.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. jsontoxml.JSON-to-XML-1.failed = true

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>

関連トピック