この章では、Oracle Portalに用意されている、精選されたAPIの概要を示します。これらの特別なAPIを使用して、コンテンツ管理タスクを実行するためのコードを作成できます。内容は、次のとおりです。
Oracle Portalは、図9-1に示すOracle Metadata Repository内のスキーマを使用して、ポータル・インスタンスに関連付けられたコンテンツとメタデータを格納します。このスキーマは、コンテンツ・リポジトリと呼ばれることもあります。たとえば、コントリビュータがファイル・アイテムをポータル・ページに追加すると、ファイルは、提供されたメタデータとともにMDS RepositoryのPortalスキーマ内の表にアップロードされます。
MDS RepositoryおよびOracle Portalアーキテクチャの一般的な詳細は、『Oracle Fusion Middleware管理者ガイド』を参照してください。
Oracle Portalには、WebブラウザからMDS RepositoryのPortalスキーマ内のコンテンツを直接管理する上で役に立つツールが多数組み込まれています。ただし、Oracle Portalのブラウザ・ベースのユーザー・インタフェース外の環境でコンテンツ管理が必要になることがあります。
管理が必要となる場合の例を次に示します。
製品のユーザー・インタフェースが要件を十分に満たしていない場合、別のユーザー・インタフェースを作成します。作成例は次のとおりです。
ウィザードのルック・アンド・フィールが独自の企業デザインに合うように変更します。
カスタム検証機能を追加します。
カスタム検索フォームまたは検索結果ページを提供します。
コンテンツとメタデータを一括ロードします。
外部アプリケーションおよびコンテンツ管理システムと統合します。
アイテムをアーカイブします(アイテムのアーカイブ・ページまたはオフライン記憶域への移動など)。
バージョンを管理します(古いバージョンの削除またはパージ、バージョン数の制限など)。
外部ワークフロー・システムと統合します。
コンテンツ管理APIを使用すると、Oracle Portalのユーザー・インタフェースを使用しないでプログラムにより、MDS RepositoryのPortalスキーマと対話できます。詳細は、9.2項「コンテンツ管理API」を参照してください。
また、一連のセキュア・ビューを使用してコンテンツ・リポジトリ内のデータを問い合せることもできます。詳細は、9.2.1項「セキュアなコンテンツ・リポジトリ・ビュー」を参照してください。
多くのコンテンツ管理タスク(アイテムの追加、ページの作成など)をプログラムにより実行するために、複数のパブリックAPIが用意されています。
コンテンツ管理用のAPIの大部分は、WWSBR_APIパッケージに含まれています。また、コンテンツ管理タスクを実行するためのコードを書く場合、次のAPIパッケージも役に立ちます。
WWSRC_APIパッケージ: MDS RepositoryのPortalスキーマのコンテンツを検索するためのAPIが含まれています。
WWSEC_APIパッケージ: MDS RepositoryのPortalスキーマでコンテンツへのアクセスを制御するためのAPIが含まれています。
WWCTX_APIパッケージ: 特定のユーザーのセッション・コンテキストを管理するためのAPIが含まれています。
WWPRO_API_INVALIDATIONパッケージ: Oracle Web Cacheのコンテンツを無効にするためのAPIが含まれています。
注意: コードにはパブリックAPIのみを使用してください。パブリック以外のAPIの使用はサポートされていません。このため、新しいリリースにアップグレードするとコードが作動しなくなる可能性があります。 |
これらのパッケージの詳細は、F.1項「サポートされているAPI」を参照してください。サポートされているPL/SQL 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」をクリックします。
Portalスキーマ内には、多くのコンテンツ・リポジトリ・ビューが用意されています。これらのビューを使用して、コンテンツ・リポジトリに格納されている文書およびアイテムのデータに問い合せることができます。セキュア・ビューのリストは、F.2項「セキュア・ビュー」を参照してください。
このマニュアルで説明するほとんどのコンテンツ管理APIでは、パラメータとしてオブジェクトIDを渡す必要があります。これを行うには、処理対象のオブジェクトIDを知る必要があります。ポータル・オブジェクトのIDを検索するには、セキュアなコンテンツ・リポジトリ・ビューを使用できます。詳細は、10.3項「オブジェクトIDの検索」を参照してください。
注意: MDS RepositoryのPortalスキーマの他の表およびビューについては、その定義がリリース間で異なることがあるため、これらの表およびビューへの直接アクセスはサポートされていません。 |
Oracle9iAS Portalリリース1(3.0.9)のコンテンツ領域用API/ビューとの下位互換性を保つため、APIのプロシージャ/パラメータ名やビュー/列名の多くにはリリース1の用語が使用されています。リリース1の用語と現在の用語との対応については、表9-1が役に立ちます。
Portalスキーマは、パブリックAPIおよびセキュア・ビューに対する必要なアクセス権を自動的に保持します。別のスキーマがパブリックAPIおよびセキュア・ビューにアクセスできるようにするには、次のスクリプトを使用します。
ORACLE_HOME/portal/admin/plsql/wwc/provsyns.sql
APIへのアクセスを可能にする手順は、次のとおりです。
provsyns.sql
スクリプトが含まれるディレクトリに変更します。
Windows: cd <ORACLE_HOME>\portal\admin\plsql\wwc Linux/Unix: cd <ORACLE_HOME>/portal/admin/plsql/wwc
Portalスキーマの所有者としてSQL*Plusにログインします。例:
sqlplus portal/oracle1
Portalスキーマの所有者としてprovsyns.sql
を実行する必要があります。デフォルトでは、PortalスキーマはPORTALという名前です。管理者は、次の手順でOracle Internet Directoryを使用して、Portalスキーマのパスワードを取得できます。
次にナビゲートします。
エントリ管理
cn=OracleContext
cn=製品
cn=IAS
cn=インフラストラクチャ・データベース
OrclReferenceName=インフラストラクチャ・データベース(iasdb.server.domain.comなど)
OrclResourceName=スキーマ名(PORTALなど)
このエントリをクリックします。
右側のパネルでorclpasswordattribute値を探します。これがスキーマのパスワードです。
provsyns.sql
スクリプトを実行します。
SQL>@provsyns.sql <schema>
schema
は、アクセス権限を付与するスキーマの名前です。
ヒント: provsyns.sql の実行時には、不足しているファイルに関するメッセージはすべて無視してください。 |
このマニュアルで説明するAPIを使用する場合、次の各項で説明するベスト・プラクティスのガイドラインに従う必要があります。
コンテンツ管理APIを使用するプロシージャおよびパッケージを作成する場合、Oracle Portalがインストールされている異なるデータベース・スキーマで作成します。Portalスキーマで作成しないでください。Portalスキーマでのプロシージャおよびパッケージの追加作成はサポートされていないので、新しいリリースへのアップグレード時に失われる場合があります。
プロシージャおよびパッケージに使用するスキーマを作成した後、APIおよびセキュアなコンテンツ・リポジトリ・ビューへのアクセス権をスキーマに付与する必要があります。この方法の詳細は、9.3項「APIおよびセキュア・ビューへのアクセスの提供」を参照してください。
すべてのAPIパッケージには、Oracle Portalのオブジェクトおよびメタデータを簡単に参照するための、事前に定義された定数が含まれています。たとえば、WWSBR_APIパッケージには、基本属性(ATTRIBUTE_AUTHORおよびATTRIBUTE_TEXTなど)、生成済アイテム・タイプ(ITEM_TYPE_FILEおよびITEM_TYPE_URLなど)、イメージの位置オプション(ALIGN_BOTTOMおよびALIGN RIGHTなど)の定数が含まれています。コードを堅牢なものにするには、可能なかぎりオブジェクトIDおよび属性値にこれらの定数を使用する必要があります。これにより、実際のIDまたは値が変更されても、定数名が同じであるため、コードは動作し続けます。
各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」をクリックします。
多くのAPIでは、変更の影響を受けるページについてキャッシュの無効化に関するメッセージが自動的に生成されます。このため、ルーチンの最後で常にwwpro_api_invalidation.execute_cache_invalidation
をコールし、これらのメッセージを処理する必要があります(この方法の例は、例11-3を参照してください)。このプロシージャをコールしない場合、影響を受けるページのキャッシュをその他の方法で無効化しないかぎり、変更内容は表示されません。
execute_cache_invalidation
は複数回コールする必要はありません。たとえば、1つのループ内で複数のアイテムを追加または更新する場合は、ループが完了した時点でexecute_cache_invalidation
をコールします。
各コンテンツ管理APIではコミットを発行しません。ただし、ブラウザ・セッションからPortalサービスを介してAPIをコールする場合、Portalサービスは、ブラウザに制御を返す前に自動コミットを実行します。
また、wwpro_api_invalidation.execute_cache_invalidation
APIもコミットを発行します。外部環境(SQL*PlusまたはWebプロバイダなど)からAPIをコールするときに、キャッシュの無効化を処理する前にコミットする必要がある場合、コード内でコミット文を明示的に発行する必要があります。同様に、ロールバックする必要がある場合も、execute_cache_invalidation
をコールする前に文を明示的に発行する必要があります。
コンテンツ管理APIをコンテンツ管理イベント・フレームワーク(CMEF)とともに使用している場合、各APIコールの前または後にCMEFグローバル変数を確実にリセットする必要があります。
ユーザーがこのユーザー・インタフェースを使用して操作を実行する場合、Oracle Portalは、様々なグローバル変数を使用して、ログに記録するCMEFメッセージを設定します。各操作後に、これらのグローバル変数は次の操作に備えて自動的にリセットされます。APIを使用してポータル操作を実行する場合、これらのグローバル変数は自動リセットされません。このため、CMEFメッセージが現在ログに記録されていることを確認するには、各APIコールの前または後にCMEFグローバル変数wwsbr_api.clear_cmef_context
APIをコールしてCMEF変数を明示的にリセットする必要があります。
たとえば、APIを使用してページ上で複数のアイテムを作成する場合、各add_item
コールの間にclear_cmef_context
APIをコールする必要があります(例9-1)。
例9-1 clear_cmef_context APIのコール
... l_new_item_master_id1 := wwsbr_api.add_item( p_caid => l_caid, p_folder_id => l_folder_id, ... ); wwsbr_api.clear_cmef_context; l_new_item_master_id2 := wwsbr_api.add_item( p_caid => l_caid, p_folder_id => l_folder_id, ... ); wwsbr_api.clear_cmef_context; ...
CMEFの詳細は、第16章「コンテンツ管理イベント・フレームワークの使用」を参照してください。
APIパッケージには、事前に定義された多くの例外が含まれています。コンテンツ管理APIを使用してコーディングする場合、すべてのエラーを捕捉するためにWHEN OTHERS例外を使用するのではなく適切な事前定義済の例外を含めることをお薦めします。このことには、コードによって生成されるエラー・メッセージが実際の問題をより明確に示すことができるという利点もあります。例9-2は、wwsbr_api.set_attribute
APIをコールするときに含めることができる例外をいくつか示しています。
例9-2 事前定義済の例外の使用
begin wwsbr_api.set_attribute( p_site_id => 37, p_thing_id => 8056, p_attribute_site_id => wwsbr_api.SHARED_OBJECTS, p_attribute_id => wwsbr_api.ATTRIBUTE_TITLE, p_attribute_value => 'New Display Name' ); -- Process cache invalidation messages. wwpro_api_invalidation.execute_cache_invalidation; exception when wwsbr_api.ITEM_NOT_FOUND_ERROR then dbms_output.put_line('Item does not exist'); when wwsbr_api.ATTRIBUTE_NOT_FOUND then dbms_output.put_line('Attribute does not exist'); when wwsbr_api.ITEM_NOT_FOR_UPDATE then dbms_output.put_line('Cannot update an item with a status of Rejected, Deleted or Marked for Delete'); when wwsbr_api.NOT_AUTHORIZED_USER then dbms_output.put_line('User trying to update the item is not the current user or the user who checked the item out'); when wwsbr_api.EDIT_CUSTOM_ATTR then dbms_output.put_line('Error while trying to update a custom attribute'); when OTHERS then dbms_output.put_line('Error '||to_char(sqlcode)||': '||sqlerrm); end; /
ヒント: 事前定義済の例外を使用する場合、これが含まれているパッケージ名(wwsbr_api.PAGE_NOT_FOUNDなど)を必ず含めるようにしてください。 |
各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」をクリックします。
このマニュアルで説明するセキュア・ビューを使用する場合、次の各項で説明するベスト・プラクティスのガイドラインに従う必要があります。
注意: このリリースでは、リポジトリのドキュメント表のビューはサポートされていません。ドキュメント表のセキュア・ビューは、将来のリリースで予定されています。 |
ほとんどのオブジェクトの主キーには、オブジェクトID、ページ・グループID(caid)および言語が含まれます。ビュー間を結合する場合、JOIN句で常にこれらの列を使用します。例9-3は、アイテムをページに結合するときのJOINを示します。
オブジェクトが翻訳可能である(翻訳が可能なページ・グループ内にオブジェクトがあり、そのキーに言語が含まれる)場合、次の規則に従う必要があります。
オブジェクト(つまり、その現行バージョン)を翻訳する場合は、翻訳が入る行を作成します。現在のセッション言語の行を選択するには、言語列の値をファンクションwwctx_api.get_nls_language()
と比較します。
オブジェクトを翻訳しない場合は、ページ・グループのデフォルト言語の行を選択します。
例9-4では、特定のページ・グループ内のすべてのページについて、翻訳されたページ表示名を選択しています。
select p.display_name title from wwsbr_all_folders p where p.caid = 53 and (p.language = wwctx_api.get_nls_language -- The current language. or (exists -- A row for the page in the page group default language. (select pg.id from wwsbr_all_content_areas pg where pg.id = p.caid and pg.default_language = p.language ) and not exists -- A row for the page in the current language. (select p2.id from wwsbr_all_folders p2 where p2.id = p.id and p2.language = wwctx_api.get_nls_language ) ) ) /
ヒント: 現在のセッション言語を参照するPL/SQLルーチンを作成する場合、wwctx_api.get_nls_language を1回コールし、これを変数に格納します。APIを複数回コールするのではなく次のSQL文の変数を参照すると、より効率的に実行されるコードを作成できます。 |
現行ユーザーのデータを選択するには、ファンクションwwctx_api.get_user
を使用します。例9-5では、現行ユーザーによって作成されたアイテムを選択しています。
次の数章で示すコード・サンプルは、コンテンツ管理とコンテンツ管理APIの使用方法の例をいくつか示すことを目的としています。これらのサンプル内では、すべてのAPIが使用されているわけではなく、また、APIで使用可能なすべてのパラメータ、定数、例外などが使用されているわけではありません。
Oracle Portalで使用可能なパブリック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」をクリックします。
これらの例は、SQL*Plusから実行するものとして作成されています。Portalサービスなど、他の環境から実行する場合は、コードを実行するコンテキストに応じて変更してください。
翻訳を扱う例(第14章「多言語コンテンツの作成」を除く)では、言語コンテキストが操作対象のページ・グループのデフォルト言語に設定されていることを前提としています。これにより、すべてのSQL文のWHERE句を簡略化できます。オブジェクトには常にデフォルト言語の翻訳があるため、問合せにより、該当する単一行が戻されます。
言語コードに関するこの前提がコードに当てはまらない場合は、9.5.2項「翻訳可能オブジェクトの問合せ」を参照してください。この項には、WHERE句を拡張し、特定の言語コンテキストで複数の翻訳が存在するケースや翻訳が存在しないケースに対応する方法の例が示されています。