| Oracle® Fusion Middleware Oracle Portal開発者ガイド 11gリリース1 (11.1.1) B61384-04 |
|
 前 |
 次 |
この章では、Oracle Portal付属のパブリック検索APIを使用する方法について説明します。検索APIは、WWSRC_APIパッケージに含まれています。
パブリック検索APIを使用して、ポータルをプログラムで検索し、検索結果をコンテンツ・レコードまたはXML文書として返すことができます。これらのAPIを使用して、Oracle Portalページとシームレスに統合できるカスタム検索フォームを完全に設計できます。また、ポータルの検索結果をページ上に表示する方法をカスタマイズすることもできます。つまり、Oracle Portalに用意されている検索結果ポートレットにはもう制限されません。パブリック検索APIは結果をXMLで返すことができるため、必要に応じて検索結果を処理またはフォーマットできます。
また、検索APIを使用して、ポータル・コンテンツを任意のカスタム・アプリケーションで表示することもできます。たとえば、Webベースのアプリケーションがある場合、簡単にアプリケーション内に検索フォームを作成しOracle Portalからの検索結果もフォームに表示できます。
WWSRC_APIパッケージには、次の2つのタイプのAPIが用意されています。
検索送信/実行API
アイテム検索
ページ検索
カテゴリ検索
パースペクティブ検索
検索結果API
アイテム結果をXMLドキュメントとして取得
ページ結果をXMLドキュメントとして取得
検索APIが返す検索結果の構造を確認するには、表13-1に示すように、適切なセキュア・コンテンツ・リポジトリ・ビューを参照してください。
表13-1 検索結果とセキュアなビューの対応
| 検索API | セキュアなコンテンツ・リポジトリ・ビュー |
|---|---|
|
wwsrc_api.item_search |
WWSBR_ALL_ITEMS |
|
wwsrc_api.page_search |
WWSBR_ALL_FOLDERS |
|
wwsrc_api.category_search |
WWSBR_ALL_CATEGORIES |
|
wwsrc_api.perspective_search |
WWSBR_ALL_PERSPECTIVES |
たとえば、item_search APIが返す結果は、WWSBR_ALL_ITEMSビューと同じ構造を持ちます。セキュアなビューの構造の詳細は、第F章「コンテンツ管理のAPIおよびビュー」を参照してください。
この章の内容は、次のとおりです。
次の各項の例については、SQL*Plusで出力を有効にする必要があります。これを行うには、Portalスキーマの所有者としてSQL*Plusにログインし、次のコマンドを入力します。
SQL> SET SERVEROUTPUT ON
パブリック検索APIの詳細は、Portal Centerの『Oracle Portal PL/SQL API Reference』を参照してください。
http://portalcenter.oracle.com
「Portal Focus Areas」セクションで、「Portlet Development」をクリックし、「APIs and References」セクション内の「PL/SQL API Reference」をクリックします。
|
ヒント: Webブラウザまたは外部アプリケーションからAPIをコールする場合、最初にセッション・コンテキストを設定する必要があります。詳細は、10.1項「セッション・コンテキストの設定」を参照してください。 |
例13-1では、item_search APIを使用して、文字列portalを含むアイテムでポータルのすべてのページ・グループを検索しています。
例13-1 すべてのページ・グループからの検索(item _search API)
declare
l_results wwsrc_api.items_result_array_type;
l_count number;
l_scores wwsrc_api.number_list_type;
begin
l_results := wwsrc_api.item_search(
p_mainsearch => 'portal',
p_out_count => l_count,
p_out_scores => l_scores
);
dbms_output.put_line('Number of results: ' || l_count);
exception
...
end;
/
p_mainsearch: 検索対象のキーワードまたは文字列です。これには、Oracle Textの問合せ式を含む任意の値を指定できます。
p_out_count: 検索のヒット数です。
p_out_scores: 検索結果スコアの配列です。これはOracle Textの関連スコアで、各結果が検索文字列(または他の任意のテキスト検索基準)と一致する割合の評価です。配列のインデックスは、ファンクションが返す結果配列のインデックスと一致します。
例13-1では、返される検索結果の最大数は、wwsrc_apiの定数MAX_ROWS(デフォルトは1000)によって設定されます。この設定により、特定の行数を指定しない場合に、検索問合せのヒット数が多くて時間がかかり実行不可能となるのを避けることができます。返される行数の指定方法の例は、例13-2を参照してください。
例13-2では、page_search APIを使用して、文字列Oracleを含むページで2つの特定のページ・グループ(MyPageGroupおよびShared)内を検索しています。この例では、最初の10の結果のみが返されています。
例13-2 特定のページ・グループからの検索(page_search API)
declare
l_results wwsrc_api.pages_result_array_type;
l_count number;
l_scores wwsrc_api.number_list_type;
l_pggroups wwsrc_api.number_list_type;
begin
l_pggroups(1) := 0; -- Page group 0 (shared).
l_pggroups(2) := 33; -- Page group 33 (mypagegroup).
l_results := wwsrc_api.page_search(
p_mainsearch => 'Oracle',
p_page_groups => l_pggroups,
p_rows => 10,
p_out_count => l_count,
p_out_scores => l_scores
);
dbms_output.put_line('Number of results:' || l_count);
exception
...
end;
/
p_mainsearch: 検索対象のキーワードまたは文字列です。これには、Oracle Textの問合せ式を含む任意の値を指定できます。
p_page_groups: 検索するページ・グループのIDの配列です。このパラメータを含めない場合、値はwwsrc_api.EMPTY_NUMBER_LIST(すなわち、すべてのページ・グループ)にデフォルト設定されます。
p_rows: 返される検索結果の最大数です。この値は、wwsrc_apiの定数値MAX_ROWSにデフォルト設定されます。
p_out_count: 検索のヒット数です。
p_out_scores: 検索結果スコアの配列です。これはOracle Textの関連スコアで、各結果が検索文字列(または他の任意のテキスト検索基準)と一致する割合の評価です。配列のインデックスは、ファンクションが返す結果配列のインデックスと一致します。
例13-3では、specify_attributesおよびitem_search APIを使用して、2004年1月1日以降にJoe Bloggsによって作成された、文字列Oracleを含むすべてのファイル・アイテムを検索しています。
例13-3 特定の属性の検索(specify_attributes API)
declare
l_results wwsrc_api.items_result_array_type;
l_count number;
l_scores wwsrc_api.number_list_type;
l_attributes wwsrc_runtime_attr_varray;
l_createdate_attrid wwsbr_attributes.id%type;
l_createdate_caid wwsbr_attributes.caid%type;
l_createdate_type wwsbr_attributes.data_type%type;
begin
-- Build up attribute object with author criteria.
wwsrc_api.specify_attributes(
p_id => wwsbr_api.ATTRIBUTE_AUTHOR,
p_siteid => wwsbr_api.SHARED_OBJECTS,
p_value => 'Joe Bloggs',
p_operator => wwsrc_api.CONTAINS_ALL,
p_datatype => wwsrc_api.DATA_TYPE_TEXT,
p_in_out_attr_varray => l_attributes
);
-- Build up attribute object with create date criteria
-- using wwsbr_attributes view.
select id, caid, data_type
into l_createdate_attrid, l_createdate_caid, l_createdate_type
from wwsbr_attributes
where name = 'createdate'
and rownum = 1; -- Ignore translations.
wwsrc_api.specify_attributes(
p_id => l_createdate_attrid,
p_siteid => l_createdate_caid,
p_value => '01-JAN-2004',
p_operator => wwsrc_api.GREATER_THAN,
p_datatype => l_createdate_type,
p_in_out_attr_varray => l_attributes
);
-- Perform the search.
l_results := wwsrc_api.item_search(
p_mainsearch => 'Oracle',
p_itemtypeid => wwsbr_api.ITEM_TYPE_FILE,
p_itemtypesiteid => wwsbr_api.SHARED_OBJECTS,
p_attributes => l_attributes,
p_out_count => l_count,
p_out_scores => l_scores
);
dbms_output.put_line('Number of results: ' || l_count);
exception
...
end;
/
specify_attributesのパラメータ:
p_id: 属性のIDです。wwsbr_api定数を使用するか、WWSBR_ATTRIBUTESビューを問い合せてこのIDを検索します。
p_siteid: 属性が属しているページ・グループのIDです。
p_value: 検索基準として含める属性値です。テキスト値である必要があります。
p_operator: 使用する検索演算子です。
p_datatype: 属性値のデータ型です。
p_in_out_attr_varray: 属性の既存のVARRAYです(存在する場合)。
item_searchのパラメータ:
p_mainsearch: 検索対象のキーワードまたは文字列です。これには、Oracle Textの問合せ式を含む任意の値を指定できます。
p_itemtypeid: 検索対象のアイテム・タイプのIDです。wwsbr_api定数を使用するか、WWSBR_ITEM_TYPESビューを問い合せてこのIDを検索します。これは、基本アイテム・タイプではなく実際のアイテムのサブタイプです。
p_itemtypesiteid: アイテム・タイプが属しているページ・グループのIDです。
p_attributes: 演算子および値とともに検索する属性の配列です。このパラメータの値を設定するには、specify_attributes APIをコールします。
p_out_count: 検索のヒット数です。
p_out_scores: 検索結果スコアの配列です。これはOracle Textの関連スコアで、各結果が検索文字列(または他の任意のテキスト検索基準)と一致する割合の評価です。配列のインデックスは、ファンクションが返す結果配列のインデックスと一致します。
これまでに説明したAPIは、検索結果を配列で戻します。検索結果をより柔軟に表示できるように、Oracle Portalには、検索結果をXMLとして返すAPIも複数用意されています。これらのAPIは、XMLの結果をCLOBとして返します。
次の各項では、検索APIによって出力されたCLOBから物理的なXMLファイルを生成し、そのXMLファイルをOracle Portal中間層のディレクトリに格納する方法について説明します。
これらの例では、データベースがOracle Portal中間層と同じマシン上にあることを前提としています。
検索結果をXMLファイルに変換する場合、最初に複数の設定タスクを実行し、ファイルを書き込む物理ディレクトリを定義する必要があります。
Oracle Portal中間層でディレクトリを作成する手順は、次のとおりです。
SQL*Plusで、SYSTEMまたはSYSとして接続し、次のコマンドを入力します。
create directory <dirname> as '<physical_location>';
例:
create directory RESULTDIR as '/u02/ora/OraHome_101202_PortalMF/Apache/Apache/htdocs/searchapi';
この例では、Oracle Portal中間層のhtdocsディレクトリを使用します。次の形式でHTTPを介してXML結果ファイルにアクセスできるので、この場所は使用するのに便利です:
http://<Portal_Mid_Tier>:<Port>/<directory>/<XML_Output_File>
例:
http://my.portal.com:7778/searchapi/results.xml
次に、これを使用して、XMLファイルをOmniPortletのデータ・ソースとして指定できます。この方法の例は、13.5.1項「OmniPortletでのXML検索結果の表示」を参照してください。
さらにSQL*Plusで、PL/SQLプログラムからディレクトリへの書込み権限を付与します。この例では、次のコマンドを入力して実行しています。
grant write on directory RESULTDIR to public;
次のプロシージャを実行し、新しいディレクトリにファイルを書き込めることを確認します。
declare
2 v_output_file1 utl_file.file_type;
3 begin
4 v_output_file1 := utl_file.fopen('RESULTDIR', 'NEW.txt', 'a');
5 utl_file.put_line(v_output_file1, 'NATURE and Beauty');
6 utl_file.fclose_all;
7 end;
8 /
PL/SQL procedure successfully completed.
これで、ファイル・システム上のディレクトリにアクセスすると、NEW.txtファイルが表示されます。
XML出力の場所を指定した場合、XML出力を生成するプロシージャを作成できます。例13-4は、get_all_items_xml APIによって作成されたCLOBを使用し、XMLファイルを特定の場所に書き込む一般的なプロシージャを示します。これは、ファイル名とCLOBの2つの入力パラメータを使用します。
例13-4 特定のファイル・システムに対するXMLファイルの書込み
create or replace procedure results_xml_to_file(xml_filename varchar2, result_xml clob) as
l_amount binary_integer;
l_offset number := 1;
l_text varchar2(32767);
l_file utl_file.file_type;
l_clob clob;
begin
l_clob := result_xml;
l_file := utl_file.fopen(
location => 'RESULTDIR', -- Directory name is case-sensitive.
filename => xml_filename,
open_mode => 'w'
);
l_amount := 32767;
l_offset := 1;
begin
dbms_lob.open(l_clob, dbms_lob.file_readonly);
loop
dbms_lob.read(l_clob, l_amount, l_offset, l_text);
utl_file.put(
file => l_file,
buffer => l_text
);
l_offset := l_offset + l_amount;
exit when l_amount < 32767;
end loop;
utl_file.new_line(file => l_file);
dbms_lob.close(l_clob);
end;
utl_file.fclose(file => l_file);
exception
...
end;
/
APIを使用して検索結果をXMLとして作成する場合、例13-4のプロシージャをコールし、結果のCLOBをファイル・システム上のXMLファイルに書き込むことができます。例13-5にその方法を示します。
例13-5 XMLでの検索結果の生成(get_all_items_xml API)
declare
l_results wwsrc_api.items_result_array_type;
l_scores wwsrc_api.number_list_type;
l_count number;
l_clob clob;
begin
l_results := wwsrc_api.item_search(
p_mainsearch => 'portal',
p_out_count => l_count,
p_out_scores => l_scores
);
l_clob := wwsrc_api.get_all_items_xml(l_results);
results_xml_to_file('results12.xml', l_clob);
exception
...
end;
/
例13-5で使用されているitem_search APIの詳細は、13.1項「すべてのページ・グループからのアイテムの検索」を参照してください。
このAPIによって生成されるXMLファイルをOmniPortletのデータ・ソースとして使用できます。この実行方法の例は、13.5.1項「OmniPortletでのXML検索結果の表示」を参照してください。
get_item_xmlを使用して検索結果をXMLに変換すると、検索結果ごとに<?xml version="1.0" ?>要素が作成されます。これにより、無効なXMLが作成されます。例13-6は、これらのタグを削除すると同時に、<ResultSet>の開始タグと終了タグを追加してROWSET/ROW構造を持ったXMLファイルを作成することによる回避策を示します。同様の処理は、XMLファイルをOmniPortletのデータ・ソースとして使用する場合にも実行する必要があります。
|
注意: 例13-6では、すべての検索結果をループ処理によりXMLに書き込んでいます( |
例13-6 get_item_xmlを使用したファイルへの検索結果の書込み
declare
l_amount binary_integer;
l_offset number := 1;
l_text varchar2(32767);
l_file utl_file.file_type;
l_clob clob;
l_results wwsrc_api.items_result_array_type;
l_scores wwsrc_api.number_list_type;
l_count number;
begin
l_results := wwsrc_api.item_search(
p_mainsearch => 'portal',
p_out_count => l_count,
p_out_scores => l_scores
);
l_file := utl_file.fopen(
location => 'RESULTDIR', -- Directory name is case-sensitive.
filename => 'results14.xml',
open_mode => 'w'
);
utl_file.put(
file => l_file,
buffer => '<ResultSet>'
);
for i in 1..l_results.count loop
l_amount := 32767;
l_offset := 1;
begin
l_clob := wwsrc_api.get_item_xml(l_results(i));
dbms_lob.open(l_clob, dbms_lob.file_readonly);
loop
dbms_lob.read(l_clob, l_amount, l_offset, l_text);
-- Workaround for XML generated with get_item_xml.
if instr(l_text, '?>') != 0 then
l_text := substr(l_text, instr(l_text, '?>') + 2);
end if;
-- End of workaround.
utl_file.put(
file => l_file,
buffer => l_text
);
l_offset := l_offset + l_amount;
exit when l_amount < 32767;
end loop;
utl_file.new_line(file => l_file);
dbms_lob.close(l_clob);
end;
end loop;
utl_file.put(
file => l_file,
buffer => '</ResultSet>'
);
utl_file.fclose(file => l_file);
exception
...
end;
/
検索問合せを役立つものにするには、結果をどこかに表示する必要があります。たとえば、動的ページに、検索結果を配列から直接表示するよう選択できます。また、より柔軟に処理するため、検索結果を最初にXMLに変換してからOmniPortletなどに表示することもできます。
この項の手順では、検索APIによって生成されたXMLをOmniPortletのデータ・ソースとして使用する方法の例を示します。たとえば、APIを定期的に実行して検索結果をXMLとして作成し、この結果を自動的にOmniPortletに表示するジョブをスケジュールできます。
OmniPortletの詳細は、第3章「OmniPortletを使用したポートレットの作成」を参照してください。
|
注意: 検索APIによって作成されたXMLは、CLOBで返されます。このため、XMLをOmniPortletのデータ・ソースとして使用する場合、最初にCLOBをファイルに書き込む必要があります。この実行方法の例は、13.4項「検索結果のXMLへの変換」を参照してください。 |
OmniPortletでXML検索結果を表示する手順は、次のとおりです。
最初に、新しいOmniPortletインスタンスをページに追加する必要があります。
|
ヒント: 通常、OmniPortletは、ポートレット・リポジトリの「ポートレット・ビルダー」領域で使用できます。 |
「定義」リンクをクリックし、OmniPortletウィザードを起動します。
ウィザードの「タイプ」ページで、「XML」を選択してから、「次へ」をクリックします。
「ソース」ページの「XML URL」フィールドで、XMLファイルのURLを入力します。例:
http://my.portal.com:7778/searchapi/results.xml
検索APIによって作成されるXMLデータはROWSET/ROW構造を使用するため、XSLフィルタを指定する必要はありません。
「次へ」をクリックします。
「表示」ページで、「レイアウト・スタイル」として「表」を選択してから、「次へ」をクリックします。
「レイアウト」ページで、ポートレットに表示する列とその表示方法を選択します。
「終了」をクリックし、OmniPortletインスタンスを作成します。
次の2つの例は、検索結果を動的ページ・ポートレットに表示する方法を示しています。この例を使用することで、ユーザーはこのポートレットをポータル内の任意のページに追加できます。これを行うには、次の手順を実行します:
検索を実行するために動的ページによってコールされるプロシージャを作成します。
例13-7のプロシージャでは、item_search APIを使用して、特定の文字列(searchterm)を検索し、特定の値(score)を超えるスコアを持つ結果のみを表示します。
|
注意: このプロシージャは、ポータルがあるデータベースで作成する必要があります。 |
例13-7 検索を実行するプロシージャ
create or replace procedure search_results(searchterm varchar2, score number) as
x varchar2(100);
y number;
l_results wwsrc_api.items_result_array_type;
l_count number;
l_scores wwsrc_api.number_list_type;
begin
x := searchterm;
y := score;
l_results := wwsrc_api.item_search(
p_mainsearch => x,
p_out_count => l_count,
p_out_scores => l_scores
);
htp.p('Number of total hits: ' || l_count);
htp.p('<br>');
htp.p('<br>');
for i in 1..l_results.count loop
if (l_scores(i) > y) then
htp.p('<b>' || i || '</b> - <a href="' || l_results(i).url ||
'">' || l_results(i).display_name || '</a>');
htp.p('<br>');
htp.p('score = ' || l_scores(i));
htp.p('<br>');
end if;
end loop;
exception
...
end;
/
grant execute on search_results to public;
例13-7で使用されているitem_search APIの詳細は、13.1項「すべてのページ・グループからのアイテムの検索」を参照してください。
動的ページを作成します。
動的ページは、Oracle Portalのポートレット・ビルダーを使用して構築できるポートレットの1つです。ポートレット・ビルダーの詳細は、『Oracle Fusion Middleware Oracle Portal開発者ガイド』を参照してください。動的ページの構築の詳細は、Oracle Portalのオンライン・ヘルプを参照してください。
例13-8は、動的ページに使用するコードを示します。
|
ヒント:
|
HTMLコードで定義されている2つのバインド変数にデフォルト値を指定し、動的ページに結果が表示されるようにします(図13-1)。
動的ページがポートレットとして使用できることを確認します。
これで、この動的ページ・ポートレットをポータル内の任意のページに追加できます。
|
ヒント: ポートレットは、ポートレット・リポジトリの「ステージング」領域でポートレットの作成先のプロバイダ名の下で見つけてください。 |
動的ページ・ポートレットには、図13-2のように、動的ページを作成したときに指定したデフォルト値に基づいて検索結果が表示されます。
ユーザーは、このポートレットをパーソナライズし、図13-3に示すように、独自の検索文字列および最小スコアを指定できます。
図13-4に、ポートレットをパーソナライズして最小スコアを70に変更したときに検索結果がどう変更されるかを示します。
