ダウンロード用の検索オプションの構成

6 ダウンロード用の検索オプションの構成

レイアウトの検索オプションを構成できます。これは、ユーザーがOracle Visual Builderタブで「ダウンロード」をクリックしたときに使用されます。

検索オプション	使用可能対象:	厚生	制限事項
グラフィカル検索エディタ	「Oracle ADF RESTリソース」サービス、Oracle REST Data ServicesおよびNetSuite SuiteTalk REST Webサービス	検索を作成するためのグラフィカル・ユーザー・インタフェースを提供ビジネス・ユーザーに値の入力および検索の変更を許可	検索構文に制限がある
行検索	Oracle ADF RESTリソース	サービスによって定義された、強力で複雑な検索にアクセスできますビジネス・ユーザーに値の入力を許可	「Oracle ADF RESTリソース」サービスでのみ使用可能です
検索パラメータ	任意のサービス・タイプ	開発者は、サービスがサポートする任意の構文を使用できます	ビジネス・ユーザーは、ダウンロード時に値を指定したり検索を変更することができません

検索を使用した必要なデータの検索

ワークブックの各レイアウトを構成して、ユーザーがレイアウトへのデータのOracle Visual Builder Add-in for Excelダウンロードをフィルタリングするための検索値を指定できます。

検索は、「Oracle ADF RESTリソース」サービス、Oracle REST Data Servicesまたは「NetSuite SuiteTalk REST webサービス」と統合されたワークブックでサポートされます。

たとえば、フォーム内の購買オーダーおよび表内の関連明細を表示するフォーム・オーバー表レイアウトがある場合があります。このシナリオでは、ビジネス・ユーザーが表示する特定の購買オーダーのオーダー番号を入力できる検索を作成します。

レイアウトの検索を作成するには、1つ以上の検索条件を設定します。検索条件は、ビジネス・オブジェクト・フィールド、問合せ演算子、および値で構成されます。問合せ演算子は、指定された値に基づいてアイテムの照合方法を決定し、フィールド・データ型に基づきます。たとえば、文字列に使用できる演算子には、"starts with"、"contains"および"ends with"があります。数値の場合、"greater than"および"less than"があります。日付: 前におよび後。

たとえば、$95,000を超える従業員のデータをダウンロードするには、「給与」フィールドを選択し、「より大きい」演算子を選択し、値フィールドに「95000」と入力します。

複数の条件を構成する場合、アドインでは常に論理AND演算子が各条件の間に挿入されます。そのため、「Job Title = Software Developer」や「Salary > 95000,」などの2つの条件がある場合、アドインでは、これらの両方の条件に一致するアイテムのみがダウンロードされます。

アドインでは、検索エディタの動的フィルタを含む値リスト(LOV)がサポートされています。部門と職務名に基づいて従業員のデータをダウンロードし、部門フィールドと「役職名」フィールドを検索に追加して検索を実行するとします。部門フィールドにLOVがある場合は、リストから必要な部門を選択できます。 2番目のフィールド肩書に部門フィールドに基づく動的フィルタがある場合、肩書リストには、最初のフィールドで選択した部門に関連付けられている肩書のみが表示されます。

ビジネス・オブジェクト・フィールド・エディタには、検索に関連する2つのビジネス・オブジェクト・フィールド設定があります:

検索可能: フィールドに対して検索可能が選択されている場合は、フィールドを選択できます。ビジネス・オブジェクト・フィールド・エディタで「検索可能」を選択または選択解除することで、表示するフィールドを調整できます。フィールドを検索可能に設定する前に、サービスがそのフィールドでの検索をサポートしていることを確認してください。
検索に必須: データのダウンロード時にビジネス・ユーザーにフィールドの値の指定を要求する場合は、ビジネス・オブジェクト・フィールド・エディタのフィールドで検索に必須を選択します。必須フィールドは、検索エディタでアスタリスク(*)で示されます。
フィールドが必須の場合、ビジネス・ユーザーは続行する前に値を指定する必要があります。フィールドが必須ではなく、ビジネス・ユーザーがフィールドを空白のままにした場合、対応する条件は検索から除外されます。

詳細については、「ビジネス・オブジェクト・フィールドの構成」を参照してください。

レイアウトの検索問合せを作成するには:

検索を作成するレイアウトを選択し、Excelリボンから「デザイナ」をクリックします。
「レイアウト・デザイナ問合せ」タブで、検索プロパティの横にある編集アイコン()をクリックします。
検索条件が定義されていない場合、アドインは「使用可能なビジネス・オブジェクト・フィールド」ウィンドウを開きます。
検索条件を構成するには:
1. 「使用可能なビジネス・オブジェクト・フィールド」ウィンドウから、ユーザーが検索語を入力できるようにするビジネス・オブジェクト・フィールドを選択します。このウィンドウが開いていない場合は、最初に「検索エディタ」から「フィールドの追加」をクリックします。
  たとえば、次に示すように、ユーザーが部門で従業員を検索できるようにする場合は、「学部名」を選択します:
  
  「図vb-search-fields.pngの説明」
2. フィールド名の横にあるリストから問合せ演算子を選択します。たとえば、値フィールドの値と一致する部門から従業員を返す場合は"equals"を選択し、他の部門の従業員のみを返す場合は"not equals"を選択します。
  使用可能な演算子はデータ型によって異なります。たとえば、文字列フィールドには、"starts with"、"contains"、"ends with"などのフィルタがあります。
3. 必要に応じて、ダウンロード時のアイテムの照合に使用する値フィールドの値を選択または入力します。たとえば、研究部門から従業員をダウンロードするには、"Research"を選択します。このフィールドに指定できる値は1つのみです。
  ビジネス・ユーザーに値を指定する場合は、値フィールドを空白のままにできます。ここで値を指定すると、ビジネス・ユーザーはダウンロード時に常に値を変更または消去できます。
複雑な検索用のフィールドをさらに追加するには、「フィールドの追加」をクリックし、「使用可能なビジネス・オブジェクト・フィールド」ダイアログからフィールドを選択します。
たとえば、職務名がSoftware Developerの従業員を検索する場合、$95,000を超える従業員のみを検索できます。この場合、最初に「役職名」を選択し、次に「フィールドの追加」をクリックして「給与」を選択します。最後に、次のように検索パラメータを定義します:

「図search_fields_complex.pngの説明」

ノート:
検索を構成する場合は、動的リストを含むフィールドを追加する前に、動的値リストが基準とするフィールドが追加されていることを確認します。そのため、部門の値に基づいて「役職名」リストをフィルタするには、検索エディタの「役職名」フィールドの前に部門フィールドを追加します。「動的パラメータを使用したフィルタの構成」を参照してください。
ビジネス・ユーザーがデータのダウンロード時に検索を編集できるようにするには、「ダウンロード時にエディタが有効になりました」を選択します。簡易検索プロンプトを表示するには、このチェック・ボックスの選択を解除します。
このチェック・ボックスが選択されている場合、ビジネス・ユーザーは左に示すように、検索フィールドを追加および削除したり、検索フィルタを変更できます:

図search-edit-filters.pngの説明

チェック・ボックスの選択を解除すると、右側に示すように、値のみが編集可能になります。
「OK」をクリックします。

ダウンロードするデータを制限するための行検索の使用

「Oracle ADF RESTリソース」サービスと統合されるワークブックの場合は、レイアウトのビジネス・オブジェクトに関連付けられている行検索の1つを選択できます。

Excelのリボンで、「デザイナ」をクリックします。
「レイアウト・デザイナ問合せ」タブで、行検索プロパティの横にある編集アイコンをクリックして、使用可能な行検索ウィンドウにサービス用に構成された行検索を表示します:

図finder-table-property.pngの説明
アドインでの行ファインダの表示方法(行ファインダおよび変数のタイトルおよびヘルプ・テキストの追加方法を含む)の変更の詳細は、「ビジネス・オブジェクトの行検索の構成」を参照してください。
行検索を選択し、OKをクリックします。
ワークブックにデータをダウンロードすると、行検索では、フィルタ基準に基づいてデータがフィルタ処理されます。行検索でユーザーからの入力が必要な場合は、行検索パラメータの値を指定するよう求められます。

ファインダをサポートするOracle ADF RESTリソースサービスの構成の詳細は、Oracle Application Development FrameworkによるFusion Webアプリケーションの開発の次のリソースを参照してください:

ダウンロードされたデータを制限するための検索パラメータの使用

ビジネス・ユーザーがダウンロードを起動したときにRESTサービスから返されるデータを決定する検索問合せを作成します。たとえば、ユーザーが特定のロケーションのレコードのみにアクセスする必要がある場合は、そのロケーションの検索パラメータを含む問合せを作成できます。

たとえば、managerIdフィールドが空である従業員アイテムを取得するには、検索パラメータmanagerIdがnullである「従業員」ビジネス・オブジェクトに検索を作成します。 GETリクエストでは、URLの問合せ文字列部分に次が含まれます:

GET…/Employees?q=managerId+is+null

説明:

qは、Employeesサービスでサポートされる問合せパラメータです
managerIdは、問合せパラメータをサポートするフィールドの名前です
nullは検索値です

ユーザーが「データのダウンロード」ボタンをクリックすると、アドインによって、GETリクエストのRESTエンドポイントURLに検索問合せが追加されます。検索または行ファインダの設定も構成されている場合、ユーザーは、返された結果をさらにフィルタする構成済パラメータの値を指定するよう求められます。

ノート:

検索パラメータ・プロパティは、他の2つのプロパティ(該当する場合)と組み合せて機能します。これらは相互に排他的ではありません。ただし、一部の組合せは他の組合せが動作しない場合があります。複数の検索オプションを構成する場合は、サービスがその組合せをサポートしていることを確認する必要があります。

たとえば、「Oracle ADF RESTリソース」サービスなどの一部のサービスでは、RESTコールで複数の"q"パラメータの使用がサポートされていません。レイアウトに"q"検索パラメータを定義すると、検索エディタを使用して検索がすでに定義されている場合には機能しないことがあります。

サービスで複雑な検索がサポートされている場合は、次の例に示すように、レイアウトに複雑な検索を作成できます:

q=((firstName LIKE '*es*') or ((hireDate< "2001-01-13") and (department = 10)))

各サービスは、検索に使用できるパラメータを定義します。同様に、各サービスは、代入演算子(=)の右側に表示される式の必須およびサポートされている構文を定義します。

このエディタで、またはダウンロード時に検証がありません。アドインでは、検索に役立つパラメータを判別できません。同様に、アドインではパラメータ値の適切な構文を判断できません。無効な情報を入力すると、不正なリクエスト・エラーが発生する場合があります。パラメータ名に「q」を使用するかどうか、および検索式を正しく作成する方法を識別するには、使用しているサービスのAPIドキュメントを参照してください。

アドインは、ダウンロード時にパラメータ値にURLエンコーディングを適用します。 URLエンコード値を入力しないでください。検索パラメータ名がエンコードされていません。

ノート:

依存レイアウトのセット内の各レイアウトの検索パラメータを構成できます。「依存レイアウト・セットのデータのフィルタ」を参照してください。

レイアウトに検索パラメータを追加するには:

Excelのリボンで、「デザイナ」をクリックします。
「レイアウト・デザイナ問合せ」タブで、検索パラメータ・プロパティの横にある検索パラメータの追加または検索パラメータの編集アイコンをクリックして、検索パラメータを追加または編集する検索パラメータ・エディタを開きます。

「図excel-search-parameters.pngの説明」
ワークブック・パラメータを参照する式を「パラメータ値」フィールドに含める場合は、「パラメータ値の式を許可」を選択します。「検索でのワークブック・パラメータの使用」を参照してください。
このチェック・ボックスを選択すると、Oracle Visual Builder Add-in for Excelによって値が式として評価されます。
「OK」をクリックし、エディタを閉じます。

ヒント:

検索設定の特定の組み合わせのトラブルシューティングを行うには、ネットワーク・モニターを開き、データをダウンロードします。次に、ネットワーク・モニター・ウィンドウでリクエストの詳細を検査します。この情報は、検索設定の調整に役立つ場合があります。

検索でのワークブック・パラメータの使用

ワークブックに格納されている「ワークブック・パラメータ」を参照する検索問合せを作成できます。ワークブック・パラメータは、通常、web開発者がワークブックにプログラムで埋め込む名前と値のペアです。

組織は、コンテキストに基づいてダウンロードされるときなど、統合ワークブックに異なる値を埋め込むことを選択できます。次に例を示します。組織に「従業員」ページを含むwebアプリケーションがあり、このページに統合ワークブックをダウンロードするためのボタンが含まれているとします。 web開発者は、サーバー側のメカニズムを使用して、Webアプリケーションでビジネス・ユーザーが使用するワークブックに同じフィルタ値を書き込むことができます。

たとえば、ビジネス・ユーザーは、webアプリケーションの従業員リストをフィルタ処理して、給与が$7000以上の営業部門の従業員のみを表示できます。このユーザーがページのダウンロード・ボタンをクリックすると、webサーバーは、統合ワークブックにフィルタ値(Dept=SalesおよびMinSal=7000)を埋め込んでから、ユーザーに送信します。

ワークブックに、これらのワークブック・パラメータを参照する検索パラメータがある場合は、ダウンロードしたワークブックを開いて「データのダウンロード」をクリックすると、webページと同じデータが表示されます。

これらのワークブック・パラメータを参照する"q"問合せの検索パラメータは次のようになります:

DepartmentId={ Workbook.Parameters['Dept'].Value } AND Salary >= { Workbook.Parameters['MinSal'].Value }

ダウンロード時に、Oracle Visual Builder Add-in for Excelは、検索パラメータ値プロパティの式を解決してGET URLを構築します。ワークブックのDeptおよびMinSalパラメータの値がそれぞれ"80"および"7000"の場合、結果として得られるGETリクエストURLは次のようになります:

.../Employees?q=DepartmentId=80 AND Salary >=7000

ノート:

特定のGET URL問合せ文字列構文は、RESTサービスによって管理されます。必要に応じて、サービス所有者に連絡してください。

これらのワークブック・パラメータがワークブックにどのように書き込まれるかは、ユーザー次第です。ただし、組織でこのテクノロジを利用する予定がある場合、web開発者は、これらのワークブック・パラメータをどこで、どの形式で記述するかを知る必要があります。これらの詳細は、「ワークブックへのワークブック・パラメータの埋込み」に指定できます。

ワークブック・パラメータを参照する検索パラメータを作成するには、「埋込み値を使用した検索の作成」を参照してください。

埋込み値を使用した検索の作成

ワークブックにワークブック・パラメータが含まれている場合は、これらのパラメータに格納されている値に基づいて検索問合せを作成できます。

たとえば、従業員ワークブックには、部門と給与の値を保存するためのワークブック・パラメータをいくつか含めることができます: Dept=SalesおよびMinSal=7000。これらのワークブック・パラメータが含まれている場合は、これらの値に基づいてアイテムを返す検索問合せを作成できます。

ワークブック・パラメータを参照するには、次の構文を使用: Workbook.Parameters['name'].Value。nameはワークブック・パラメータの名前です。

"q"問合せを使用して、給与が$7000以上の営業従業員を返し、次のように検索パラメータを構成します:

DepartmentId={ Workbook.Parameters['Dept'].Value } AND Salary >= { Workbook.Parameters['MinSal'].Value }

パラメータは中カッコ({および})内にある必要があります。中カッコ文字をプロパティ値のリテラルとして使用するには、バックスラッシュ(\)を使用してエスケープします。詳細は、「式について」を参照してください。

検索パラメータでワークブック・パラメータを使用するには:

Excelのリボンで、「デザイナ」をクリックします。
「レイアウト・デザイナの問合せ」タブで、「検索パラメータ」プロパティの横にある「検索パラメータの追加」アイコン()をクリックして、検索パラメータ・エディタを開きます。
検索パラメータのパラメータ名およびパラメータ値を入力します。

このイメージでは、検索パラメータは、2つのワークブック・パラメータDeptおよびMinSalを参照する検索値とともにq検索パラメータを使用します。

図workbook-parameter-config.pngの説明
アドインが値を式として評価するようにするには、「パラメータ値の式を許可」を選択します。

警告:
このチェック・ボックスが有効になっていない場合、アドインがGET URLを作成するときに、パラメータ値が詳細文字列として使用されます。この例では、400 Bad Requestエラーが発生します。
「OK」をクリックし、エディタを閉じます。

レイアウトのダウンロード中に、Oracle Visual Builder Add-in for Excelは「検索パラメータ」値プロパティの式を解決し、GET URLを構築します。ワークブックにワークブック・パラメータがない場合、または構文が正しくない場合、アドインは式を評価できません。これにより、400 Bad Requestエラーが発生する可能性があります。

ワークブックを配布する前に、ネットワーク・モニターを開き、Oracle Visual Builderリボンの「データのダウンロード」ボタンをクリックして、検索動作をテストすることをお薦めします。ネットワーク・モニターには、検索パラメータを使用してアドインが構築するURLが表示されます。「ネットワーク・モニター」を参照してください。

問題が発生した場合は、ワークブック・パラメータの値を変更してから、「データのダウンロード」を再度クリックします。次のダウンロードには、これらのパラメータに加えられた変更が反映されます。

テスト目的でワークブック・パラメータを表示または変更するには、「上級」メニューから「ワークブック・パラメータの編集」ウィンドウを開きます:

ノート:

「ワークブック・パラメータの編集」メニュー・コマンドは、デザイナ・ツールが有効になっている場合にのみ使用できます。

edit-workbook-parameters.pngの説明は以下のとおりです

図edit-workbook-parameters.pngの説明

値を変更するには、リストからワークブック・パラメータを選択し、「編集」アイコン()をクリックします。

ワークブックへのワークブック・パラメータの埋込み

J2EEサーブレットやブラウザベースのJavaScriptなどのカスタム・ソリューションを使用して、ワークブックにワークブック・パラメータを記述します。ワークブック・パラメータは、パックされた文字列-値形式を使用して、ワークブックの非表示のワークシートに格納される名前と値のペアです。ワークブック開発者は、これらのパラメータを参照する検索問合せを作成できます。

ワークブック・パラメータは、ワークブックがwebアプリケーションからダウンロードされたときに渡されるURL引数に対応する名前と値のペアである場合があります。また、webアプリケーション・ページの状態を表す場合もあります。または、任意の名前付きの値である可能性があります。

Oracle Visual Builder Add-in for Excelには、ワークブック・パラメータをプログラムで埋め込む機能は含まれていません。この機能を使用する組織は、特定のワークブックにこれらのパラメータを埋め込むための独自のカスタム・ソリューションを提供する必要があります。このトピックは、このソリューションをコーディングするプログラマまたはweb開発者を対象としています。

ワークブック・パラメータは、特定のロケーションに特定の形式で記述する必要があります。続行する前に、パラメータ要件を慎重に確認して、ワークブック・パラメータを正しく埋め込んでいることを確認してください。

サンプル・メソッド

次に、ソリューションを計画する際に考慮するいくつかのメソッドを示します:

J2EEサーブレットまたはフィルタを使用して、ダウンロード中にワークブックを調査および更新するサーバー側のメカニズム
サーバーから取得した後、およびローカル・コンピュータ・ファイル・システムに書き込まれる前にワークブックの内容を確認および更新できる、クライアント側/ブラウザベースの(JavaScript)メカニズム

ロケーション

すべてのワークブック・パラメータは、セル・アドレス$B$15の_VBCS_WorkbookInfoという名前の非表示のワークシートに文字列として格納されます。

書式

パックされた文字列の形式は次のとおりです:

<paramName1>=<paramValue1>/<paramName2>=<paramValue2>/...

次の条件を使用します:

各paramNameおよびparamValueは、URLで個別にエンコードする必要があります。
各名前は、等号文字(=)を使用して値から分離する必要があります。
文字列に複数の名前と値のペアがある場合、名前と値のペアはそれぞれスラッシュ(/)文字で区切られます。
等号( =)およびスラッシュ( /)の文字はエンコードできません。
名前部分は空にできません。また、検索パラメータ式で使用される名前と一致する必要があります。「検索でのワークブック・パラメータの使用」を参照してください。

ノート

埋込みパラメータのセットのパック文字列形式の合計サイズは、32,759文字に制限されています。
特定のワークシート・セル(_VBCS_WorkbookInfo!$B$15)は、次のようになります:
- 空(パラメータなし)
- 1つ以上のパラメータ名と値のペアのパックされた文字列が含まれます
- 特殊なプレースホルダー文字列$$VbafeWorkbookParameters$$が含まれます
  この値は、ワークブックが最初にアドインを使用して統合されるとき、およびワークブックが公開されるときにも、デフォルトで設定されます。
  
  アドインでは、この値が見つかった場合、空の文字列と同様に処理されます(使用可能なパラメータはありません)