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> 要素

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

<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 ポリシーを構成することで、レスポンスのフォーマットを動的に設定できます。このシナリオの実装については、フロー変数と条件をご覧ください。

スキーマ

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 解決方法
steps.jsontoxml.ExecutionFailed 500 入力ペイロード(JSON)が空か、JSON to XML ポリシーに渡された入力(JSON)が無効または不正です。
steps.jsontoxml.InCompatibleTypes 500 このエラーは、<Source> 要素で定義された変数の型と、<OutputVariable> 要素で定義された変数の型が異なる場合に発生します。<Source> 要素に含まれる変数の型と <OutputVariable> 要素に含まれる変数の型は一致している必要があります。有効な型は messagestring です。
steps.jsontoxml.InvalidSourceType 500 このエラーは、<Source> 要素の定義に使用される変数の型が無効な場合に発生します。有効な変数の型は messagestring です。
steps.jsontoxml.OutputVariableIsNotAvailable 500 このエラーは、JSON to XML ポリシーの <Source> 要素で指定された変数が String 型であり、<OutputVariable> 要素が定義されていない場合に発生します。<Source> 要素で定義された変数が文字列型の場合、<OutputVariable> 要素は必須です。
steps.jsontoxml.SourceUnavailable 500 このエラーは、JSON to XML ポリシーの <Source> 要素で指定された message 変数が、次のいずれかである場合に発生します。
  • 範囲外(ポリシーが実行されている特定のフローで使用できない)または
  • 解決できない(定義されていない)

デプロイエラー

なし。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "SourceUnavailable"
jsontoxml.policy_name.failed policy_name は、障害が発生したポリシーのユーザー指定の名前です。 jsontoxml.JSON-to-XML-1.failed = true

エラー レスポンスの例

{
  "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>

関連トピック