Webサービスのスキーマ・ノードおよび属性

RESTインバウンドWebサービス(IWS)操作は、単一のスキーマ・ベースのオブジェクト(ビジネス・オブジェクト、ビジネス・サービスまたはサービス・スクリプト)を起動します。オブジェクトには、デフォルトで要求スキーマと応答スキーマの両方として機能するスキーマが1つあります。この製品では、外部向けコンシューマの基礎となる内部スキーマのビューを表すWebサービス操作の明示的なスキーマを定義できます。操作スキーマは内部スキーマの厳密なビューであるため、構造の変更は発生しないことに注意してください。

操作スキーマの定義はオプションですが、次のような利点があります。

  • 要素が要求スキーマ、応答スキーマまたは両方の一部であるかどうか、またはどちらの一部でもないかについて、要素の使用を宣言します。 

  • 外部要素名を内部要素に割り当てます。この目的のためにのみ内部サービスをクローニングすることを避けるために役立ちます。

  • GET操作の参照の管理と可視性が向上します。

  • 内部スキーマ外でHATEOASスタイルの構造をサポートします。これにより、シームレスな内部処理が可能になります。

  • 個々の要素のヘルプ・テキストを提供します。

次のドキュメントは、インバウンドWebサービス操作スキーマの構成時に使用可能な属性の全リストです。

内容

操作スキーマ定義

特殊な要素

Open API仕様

操作スキーマ定義

次の属性は、操作の要求スキーマおよび応答スキーマを確立する外部向け操作スキーマを定義します。

ニーモニック 有効値 摘要 例
usage= "REQ"

要素が要求スキーマにのみ含まれることを示します。

グループまたはリスト要素に指定すると、値はコンテナ全体に適用されます。コンテナ内の特定の要素は、コンテナのデフォルトを上書きできます。

 
<customerName usage="REQ" />
"RESP"

要素が応答スキーマにのみ含まれることを示します。

グループまたはリスト要素に指定すると、値はコンテナ全体に適用されます。コンテナ内の特定の要素は、コンテナのデフォルトを上書きできます。

 
<customerId usage="RESP" />
"BOTH"

要素が要求スキーマ定義と応答スキーマ定義の両方に含まれることを示します。これはデフォルト値です

グループまたはリスト要素に指定すると、値はコンテナ全体に適用されます。コンテナ内の特定の要素は、コンテナのデフォルトを上書きできます。

 
<customerName usage="BOTH" />
"EXCL"

要素が要求スキーマ定義または応答スキーマ定義に含まれていないことを示します。

グループまたはリスト要素に指定すると、値はコンテナ全体に適用されます。コンテナ内の特定の要素は、コンテナのデフォルトを上書きできます。

 
<httpMethod usage="EXCL" />
mapTo= "内部要素名"

Webサービス要素を内部要素にマップします。デフォルトでは、内部要素名はWebサービス要素名と同じであるとみなされます。この属性を使用して、操作スキーマの外部向け要素名を割り当て、対応する内部要素にマップします。

これはXPath式ではなく、拡張された内部スキーマの構造に対応する有効な要素名への参照であることに注意してください。

要素の所有者は、Webサービス・スキーマの所有者と同じである必要があります。操作の基礎となるスキーマが(動的データ領域拡張を使用して)拡張された場合、拡張所有者は、その操作のWebサービス・スキーマ拡張の要素のみを参照できます。

内部スキーマ要素:

<toDoPriority .../>

操作スキーマ要素:

<priority mapTo="toDoPriority"/>
role= "FKGP"

エンティティへの外部キーを表すグループ構造を確立します。

要素自体は内部スキーマに存在しません。外部キー値要素と、実行時にそのエンティティのGET操作のエンドポイントURLを提供する対応する_​link要素をグループ化します。Webサービスのコンシューマは、リンクを使用してエンティティのデータを取得できます。

内部スキーマ要素:

<user .../>

操作スキーマ・グループ:

<user role="FKGP">
   <user>
   <_link getOperation="mo:'USER';pk1:user;"/>
</user>
"COLL"

内部サービス・リストに対応するエンティティのコレクションを表すグループ構造を確立します。

要素自体は内部スキーマに存在しません。_​data要素にマップされた内部リストと、実行時にコレクションのGET操作のエンドポイントURLを提供する対応する_​link要素をグループ化します。Webサービスのコンシューマは、リンクを使用して、リスト内の各エンティティのより詳細な情報セットを取得できます。

デフォルトでは、参照リスト内のすべての要素が操作スキーマに含まれます。必要に応じて、特定の要素の属性を明示的に参照および定義できます。

内部スキーマ要素:

<alerts type="list">
     <alert/>
     <startDate />
     <endDate />
     <version />
   </_data> </alerts>

操作スキーマ・グループ:

<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
        <version usage="EXCL"/>
   </_data>
</alerts>
getOperation=

"式"

式コンポーネント:

  • mo:'<メンテナンス・オブジェクト>';

  • pk1:<内部スキーマ内の要素への相対xpath>;

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

パラメータpk2から5は、メンテナンス・オブジェクトの主キー定義と一致している必要があります。

_​self要素および_​link要素でのみ有効です。この属性は、メンテナンス・オブジェクトまたはビジネス・オブジェクトで定義されているエンティティのデフォルトのGET操作を参照するために使用されます。

アプリケーションは、使用するGET操作を次のように決定します。

  • エンティティのビジネス・オブジェクトがGET操作オプションを使用して操作を参照する場合は、それが使用されます。

  • エンティティのメンテナンス・オブジェクトがGET操作オプションを使用して操作を参照する場合は、それが使用されます。

  • メンテナンス・オブジェクトを参照するGET操作が見つかった場合は、それが使用されます。

エンティティに対するGET操作を決定できない場合は、かわりに、リンクを使用できないことを示す標準テキストが返されます。
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"式"

式コンポーネント:

  • iws:'<インバウンドWebサービス名>';

  • operation:'<操作名>';

  • parms:[<GET操作レコードで定義されている外部参照>:<値を保持する内部スキーマ内の要素名の相対xpath>; <別の外部参照名>:<別の相対xpath>;...];

_​self要素および_​link要素でのみ有効です。この属性は、特定のGET操作とそのパス・パラメータの構成に必要な情報を参照するために使用されます。

 
<_self getOperation="iws:'F1-ToDoEntry'; operation:'getToDoEntry'; parms:[toDoEntryId:toDoEntryId;]"/>

特殊な要素

操作スキーマ定義では、Hypermedia as the Engine of Application State (HATEOAS)標準としてハイパーメディアのスタイルで特殊な要素名が使用されます。これらの要素は内部操作サービスとは関係がなく、内部操作サービスによって管理する必要もないため、操作スキーマによってのみ定義される必要があります。

次のリストでは、各要素とその使用方法について説明します。

要素名 摘要 例
<_​self .../>

応答ペイロードには、応答で返されるエンティティに関連するGET操作のエンドポイントURLを含む"_​self"要素を含めることができます。

これはオプションの要素であり、操作スキーマには1つのみ含めることができます。

詳細は、getOperation=スキーマ定義属性を参照してください。

 
<_self getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​link .../>

応答ペイロードには外部キーを含めることができ、それらのエンティティについて、応答にはそのエンティティに対するGET操作のエンドポイントURLを含む"_​link"要素が含まれます(存在する場合)。

詳細は、role=およびgetOperation=スキーマ定義属性を参照してください。

 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​data .../>

内部スキーマ内のエンティティのリストへの標準参照を提供します。

詳細は、role="COLL"スキーマ定義属性を参照してください。

 
<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
   </_data>
</alerts>

ドキュメント属性

次の属性は、WebサービスのOpen API仕様の一部として含まれる個々の要素に関する追加のドキュメントを提供します。

ニーモニック 有効値 摘要 例
helpText= "ヘルプ・テキスト・フィールド名"

インバウンドWebサービスに対して定義された特定のヘルプ・テキスト・レコードに要素を関連付けます。要素が要求スキーマと応答スキーマの両方に含まれている場合は、両方で同じヘルプ・テキストが使用されます。

この属性が指定されず、内部要素に関連付けられたフィールドのヘルプ・テキスト・フィールド・レコードが1つ存在する場合は、そのヘルプ・テキスト・レコードが使用されます。このようなヘルプ・テキスト・フィールド・レコードが複数存在する場合は、ヘルプ・テキスト名がフィールド名と同じレコードが使用されます。

内部要素は、mdField=属性(存在する場合)を介してフィールド名に関連付けられ、それ以外の場合はmapField=属性を介してフィールド名に関連付けられることに注意してください。

_​self要素および_​link要素では無効です。

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY"/>

この例では、インバウンドWebサービスは、この要素のヘルプ・テキストを提供するヘルプ・テキスト・フィールド名"TD_​ENTRY"を定義します。要求スキーマと応答スキーマの両方の要素に同じヘルプ・テキストが含まれています。
helpTextResponse= "ヘルプ・テキスト・フィールド名"

要求スキーマと応答スキーマの両方に含まれる要素を、応答スキーマのコンテキストで使用される特定のヘルプ・テキスト・レコードに関連付けます。

helpText=属性と同じルールに従います。

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
この例では、インバウンドWebサービスは、次のヘルプ・テキスト・レコードを定義します。

  • ヘルプ・テキスト・フィールド名"TD_​ENTRY"は、要求スキーマで送信される要素を示します。

  • ヘルプ・テキスト・フィールド名"TD_​ENTRY_​RESP"は、応答スキーマに移入される要素を示します。