対話Webサービスの操作

対話Webサービス・インタフェースは、Oracle Endeca Serverに問い合せる操作を提供します。

操作の説明

上位レベルでは、対話Webサービスはデータに関するユーザーとの対話を促進します。一般的なリクエストは、フィルタ状態と1つのコンテンツ要素構成で構成されます。次に、省略された例を示します。 
<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  ..
   <State>
   ...
   </State>
    <RecordListConfig>
    ...
   </RecordCountConfig>
</Request>
  • 状態は、リクエスト内のState要素によって表されます。これにより、リクエストによって選択するレコードを記述します。状態は空にするか、または、通常はユーザー・アクションの結果としてフィルタ状態を変更するかコンテンツ要素を再構成するコンポーネントを含めることができます。リクエストには、少なくとも1つの状態が含まれている必要があります。リクエストに複数の状態が含まれている場合は、各状態に名前が必要です。
  • レコードに関するサマリー情報は、対話WebサービスのContentElementConfig要素のタイプである要素の1つに含まれます。どのリクエストにもContentElementConfigベース・タイプ自体は含まれないことに注意してください。かわりに、例にあるRecordListConfigタイプなどのサブタイプが含まれます。このEndeca Serverドキュメントでは、これ以降、ContentElementConfigをコンテンツ要素構成と呼びます。コンテンツ要素構成は、状態に指定されたレコードや他の情報に関するサマリー情報を提供します。リクエストには、複数のContentElementConfig要素が含まれる場合があります。
Endeca Serverの他のWebサービスとは異なり、対話Webサービスでは、ユーザーが一連の関連するリクエストを作成して、データとのダイアログを作成します。対話Webサービス・ダイアログのアクションのシーケンスは次のとおりです。
  1. ユーザーがフロントエンド・アプリケーションを使用して問合せを発行します。

    対話Webサービスで、リクエストがRequest複合タイプに反映されます(WSDLでは、すべての複合タイプがComplexTypeとしてリストされます)。

    この問合せを使用して、初期フィルタ状態(空であるか、1つ以上のフィルタと1つのコレクション名を含む)および1つ以上のコンテンツ要素構成が構築されます。これらのフィルタ状態とコンテンツ要素構成は対話Webサービス・リクエストで送信されます。

  2. この初期リクエストに対するレスポンスは、1つ以上のコンテンツ要素構成の要素に元の状態とレコード(または他の情報)が含まれたResultsタイプを返します。
  3. ユーザーが特定のアクションを選択すると、フロントエンド・アプリケーションが対話Webサービスを通じて新しいリクエストを送信します。通常、この後続のリクエストは、対話Webサービス・リクエストの前回の呼出しで返された結果から構築されます。具体的には、このリクエストは、前回のレスポンスで返された状態と、ユーザー・アクションに対応する新しいフィルタまたはコンテンツ要素構成を送信します。
  4. レスポンスは、新しい状態および新しいコンテンツ要素構成とともに、変換された問合せを返します。

この対話の間、ユーザーは、まったく異なるタイプのアクションをリクエストできることに注意してください(その場合、新しい異なるリクエストが必要です)。

リクエスト

Request操作は、次のようなスキーマの複合タイプです。 
<complexType name="Request">
  <sequence>
    <element  minOccurs="0"  name="OuterTransactionId"  type="cs_v2_0:NonEmptyString" />
    <element  default="en"  minOccurs="0" name="Language"  type="cs_v2_0:NonEmptyString" />
    <element  maxOccurs="unbounded"  minOccurs="0"  name="State"  type="cs_v2_0:State" />
    <group    maxOccurs="unbounded"  minOccurs="0"  ref="cs_v2_0:ContentElementConfig" />
    <element  minOccurs="0" name="PinDataVersion"  type="cs_v2_0:NonEmptyString" />
    <element  minOccurs="0" name="DataVersionRequested"  type="cs_v2_0:NonEmptyString" />
  </sequence>
</complexType>
各リクエストでは次の内容を指定できます。
要素 説明
OuterTransactionId オプションです。使用する場合は、リクエスト内の最初の要素である必要があります。リクエストが外部トランザクション内で実行される場合にのみ指定する必要があります。外部トランザクションの詳細は、「トランザクションWebサービス・インタフェース」を参照してください。
Language オプションです。EQL文の解析時に生成されるエラー・メッセージの言語コードを指定します。この要素とそのサポートされる言語コードの詳細は、「EQLエラー・メッセージの言語コード」を参照してください。
State 必須です。操作するレコードのセットに影響する入力を含みます。たとえば、状態には、レコード・フィルタ(レコード検索フィルタ、選択した絞込みフィルタ、EQLレコード・フィルタなど)と検索するコレクションの名前が含まれます。リクエストには複数の状態を含めることができます(この場合は、各状態に名前が必要です)。リクエスト内に状態が1つしかない場合にのみ、名前のない状態を含めることができます。
ContentElementConfig オプションです。特定の状態から返されるレコードに関連するサマリー構成情報を表します。様々なタイプのContentElementConfigが存在します。タイプによって、フィルタ状態のサマリーまたは、ブレッドクラムのセット、ナビゲーション・メニュー、グリッドやチャートのデータなど、そこに含まれるデータを記述できます。タイプは次のとおりです。
  • AttributeGroupConfig
  • AvailableSearchKeysConfig
  • BreadcrumbConfig
  • EQLConfig
  • NavigationMenuConfig
  • PropertyListConfig
  • RecordCountConfig
  • RecordDetailsConfig
  • RecordListConfig
  • SearchAdjustmentsConfig
  • ValueSearchConfig
PinDataVersion オプションです。Endeca Serverによって現在のデータ・バージョンが維持される期間を示すタイムアウト値を指定します。このデータ・バージョンは固定され、タイムアウト期間が経過するまでメモリー内に維持されます。この要素で指定するタイムアウト値は、EndecaServer.propertiesファイルにリストされている最小値と最大値の範囲内である必要があります。固定されたバージョン番号は、PinDataVersionを使用するリクエストに対するレスポンスのX-Endeca-Served-Data-Versionヘッダーで返されます。
DataVersionRequested オプションです。固定されたバージョンの番号を指定します。DataVersionRequestedを含むリクエストは、バージョンの固定時に指定されたタイムアウト期間内に発行する必要があります。これにより、タイムアウトはリセットされます。このタイムアウト期間後にリクエストを発行した場合、固定されたバージョンが有効期限切れになっている可能性があります。

レスポンス

Request操作はResultsレスポンスを出力し、この中にはStateと、オプションで、リクエストのContentElementの結果である1つ以上のContentElementタイプ(たとえば、RecordListはRecordListConfigから返される)が含まれます。

対話Webサービスからの各レスポンスのヘッダーには、2つのバージョン番号(提供されたバージョン番号と最新のバージョン番号)が含まれます。 
X-Endeca-Served-Data-Version 
X-Endeca-Data-Version
X-Endeca-Served-Data-Versionは、固定されたデータ・バージョンの番号も表します(固定した場合)。

エラーの例

障害時には、SOAPフォルトがスローされます。そのfaultstring要素には、エラーの原因となったリクエストに関する情報が含まれ、detail要素には、リクエストのエラーの場所へのポインタが含まれます。