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 メッセージが含まれる変数、リクエスト、またはレスポンスです。

注: ソースメッセージの HTTP Content-type ヘッダーが application/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 で名前空間定義のソースとして機能します（つまりソース 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 ポリシーを適用し、必要に応じて構成要素を繰り返し追加すると便利です。

JSON や XML が必要とされるさまざまなクライアントアプリで API が消費されるシナリオでは、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 Apigee 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
`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

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

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

使用上の注意

スキーマ

エラー リファレンス

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

関連トピック

JSONtoXML ポリシー

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

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

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

エラーリファレンス