このページの内容は Apigee と Apigee ハイブリッドに該当します。
Apigee Edge のドキュメントを表示する。
概要
このポリシーは、メッセージを JavaScript Object Notation （JSON）形式から拡張マークアップ言語（XML）形式に変換します。このため、メッセージの変換方法を制御する選択肢が多彩になります。
このポリシーは、XSL を使用してメッセージを変換する場合に特に便利です。JSON ペイロードを XML に変換したら、XSL Transform ポリシーでカスタム スタイルシートを使用して、必要な変換を行います。
このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。
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 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
| デフォルト |
なし この要素を省略した場合、ポリシーの |
|---|---|
| 要否 | 省略可 |
| タイプ | 文字列 |
<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 で名前空間定義のソースとして機能します（つまりソース 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>
{"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 から XML への変換ポリシーを適用し、必要に応じて構成要素を繰り返し追加すると便利です。
JSON や XML が必要とされるさまざまなクライアント アプリで API が消費されるシナリオでは、JSON から XML への変換および XML から JSON への変換ポリシーを条件付きで実行するようにレスポンスの形式を動的に設定できます。このシナリオの実装については、フロー変数と条件をご覧ください。
スキーマ
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
| 障害コード | HTTP ステータス | 原因 | 修正 |
|---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 |
入力ペイロード（JSON）が空か、JSON to XML ポリシーに渡された入力（JSON）が無効または不正です。 | build |
steps.jsontoxml.InCompatibleTypes |
500 |
このエラーは、<Source> 要素で定義された変数の型と、<OutputVariable> 要素で定義された変数の型が異なる場合に発生します。<Source> 要素に含まれる変数の型と <OutputVariable> 要素に含まれる変数の型は一致している必要があります。有効な型は message と string です。 |
build |
steps.jsontoxml.InvalidSourceType |
500 |
このエラーは、<Source> 要素の定義に使用される変数の型が無効な場合に発生します。有効な変数の型は message と string です。 |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 |
このエラーは、JSON to XML ポリシーの <Source> 要素で指定された変数が文字列型であり、<OutputVariable> 要素が定義されていない場合に発生します。<Source> 要素で定義された変数が文字列型の場合、<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>関連トピック
- XML から JSON への変換: XMLtoJSON ポリシー
- XSL 変換: XSLTransform ポリシー