JSONtoXML ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

内容

このポリシーは、メッセージを JavaScript Object Notation（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> 属性

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

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの 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 が指定されていない場合、source は OutputVariable として扱われます。たとえば、source が request である場合、OutputVariable のデフォルトは request になります。

<OutputVariable>request</OutputVariable>

デフォルト	リクエストまたはレスポンス。ポリシーが API プロキシフローに追加されている場所によって決まります。
要否	`<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 を使用すると、JSON プロパティを定義できます。これはポリシーによって生成された XML で Namespace 定義のソースとして機能します。（つまりソース JSON は、生成される XML を利用するアプリケーションが期待する Namespace にマッピングできるプロパティを提供する必要があります）。

たとえば次の設定は、

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

デフォルトとして指定された Namespace を少なくとも 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 ポリシーを適用し、必要に応じて構成要素を繰り返し追加すると便利です。

JSON や XML が必要とされるさまざまなクライアントアプリで API が消費されるシナリオでは、JSON to XML ポリシーおよび XML to JSON ポリシーを条件付きで実行するようにレスポンスの形式を動的に構成できます。このシナリオの実装については、フロー変数と条件をご覧ください。

スキーマ

エラーリファレンス

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

ランタイムエラー

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

障害コード	HTTP ステータス	原因
`steps.jsontoxml.ExecutionFailed`	`500`	入力ペイロード（JSON）が空か、JSON to XML ポリシーに渡された入力（JSON）が無効または不正です。
`steps.jsontoxml.InCompatibleTypes`	`500`	このエラーは、`<Source>` 要素で定義された変数の型と、`<OutputVariable>` 要素で定義された変数の型が異なる場合に発生します。`<Source>` 要素に含まれる変数の型と `<OutputVariable>` 要素に含まれる変数の型は一致している必要があります。有効な型は `message` と `string` です。
`steps.jsontoxml.InvalidSourceType`	`500`	このエラーは、`<Source>` 要素の定義に使用される変数の型が無効な場合に発生します。有効な変数の型は `message` と `string` です。
`steps.jsontoxml.OutputVariableIsNotAvailable`	`500`	このエラーは、JSON to XML ポリシーの `<Source>` 要素で指定された変数が文字列型であり、`<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`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの 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>

JSONtoXML ポリシー

内容

サンプル

リクエストの変換

要素リファレンス

<JSONToXML> 属性

<DisplayName> 要素

<Source> 要素

<OutputVariable> 要素

<Options>/<OmitXmlDeclaration>

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

<Options>/<ObjectRootElementName>

<Options>/<AttributeBlockName> <Options>/<AttributePrefix> 要素

<Options>/<ArrayRootElementName> <Options>/<ArrayItemElementName> 要素

<Options>/<Indent>

<Options>/<TextNodeName> 要素

<Options>/<NullValue> 要素

<Options>/<InvalidCharsReplacement> 要素

使用上の注意

スキーマ

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

関連トピック

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> 要素

<Options>/<ArrayRootElementName>
<Options>/<ArrayItemElementName> 要素

エラーリファレンス

ランタイムエラー

エラーレスポンスの例