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>
            <NamespaceBlockName>#namespaces</NamespaceBlockName>
            <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName>
            <NamespaceSeparator>:</NamespaceSeparator>
            <AttributeBlockName>#attrs</AttributeBlockName>
            <AttributePrefix>@</AttributePrefix>
            <ObjectRootElementName>Root</ObjectRootElementName>
            <ArrayRootElementName>Array</ArrayRootElementName>
            <ArrayItemElementName>Item</ArrayItemElementName>
            <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> 要素で定義された変数が string 型の場合は必須です。
メッセージ

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

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

たとえば次の設定は、

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

#namespaces というプロパティが、デフォルトして指定された少なくとも 1 つの名前空間を含むソース 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> / <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 to XML ポリシーを適用し、必要に応じて構成要素を繰り返し追加すると便利です。

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

スキーマ

エラー リファレンス

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

ランタイム エラー

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

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

デプロイエラー

なし

障害変数

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

変数 説明
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>
    

関連トピック