| Oracle® Fusion Middleware Oracle WebCenter PortalおよびOracle JDeveloperでのポータルの開発 11gリリース1 (11.1.1.9.0) E49666-05 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle WebCenter PortalおよびOracle JDeveloperでのポータルの開発 11gリリース1 (11.1.1.9.0) E49666-05 |
|
前 |
次 |
この章では、サーバー・データを取得、追加、変更および削除できるようにするWebCenter PortalのREST APIについて説明します。
この章の内容は、次のとおりです。
この章には、WebCenter Portal REST APIの使用方法を示すいくつかのサンプルが含まれています。他のサンプルについては、次の場所にある、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページを参照してください:
http://www.oracle.com/technetwork/middleware/webcenter/ps3-samples-176806.html
REpresentational State Transfer (REST)とは、分散型のリソースを均一なインタフェースで使用可能にするためのアーキテクチャ・スタイルであり、この均一なインタフェースには、Uniform Resource Identifier (URI)、明確に定義された操作、ハイパーメディア・リンクおよび制限された一連のメディア・タイプが含まれます。通常、これらの操作には読取り、書込み、編集および削除が含まれ、メディア・タイプにはJSONおよびXML/ATOMが含まれます。
RESTコマンドでは、リクエストとして標準HTTPメソッドを使用して、使用するリソースを指定します。すべてのリクエストは、操作のステータスを含むレスポンスを返します。リクエストによりオブジェクトが取得、作成または更新されると、レスポンスにはそのオブジェクトの標準表現が格納されます。
RESTは、クライアント・マシンからもその他のサーバーからも複数のクライアントをサポートし、どのクライアントまたは開発テクノロジ(Java、JavaScript、Ruby on Rails、PHP、.Netなど)からも使用できます。
|
ヒント: RESTの概要を理解するには、WikipediaのRepresentational State Transferに関する記事(http://en.wikipedia.org/wiki/Representational_State_Transfer)を参照してください。 |
RESTは、通常、クライアント側でスクリプトされ、サーバー側アプリケーションからのデータをやり取りする機能が必要なリッチ・インターネット・アプリケーション(RIA)で使用されます。たとえば、WebCenter iPhone AppはWebCenter Portal REST APIを使用して、WebCenter Portalアプリケーションとやり取りします。ネイティブのiPhoneクライアントはObjective-Cで作成されており、REST APIにより、クライアントはアプリケーション・データを送信および取得できます。
セキュリティを向上するために、すべてのURIには、hrefとtemplateのどちらの属性でも、認証ユーザー名に基づくセキュリティ・トークン・パラメータ(utoken)が含まれています。
セキュリティ生成アルゴリズムは、ユーザー名とともにランダムに生成されたsaltを使用します。saltにより、暗号化で使用したパラメータのセキュリティが侵害されても、既存のトークンを無効化し、新しいトークンを生成できます。最も重要なことは、ユーザー・トークンの生成アルゴリズムの一部としてユーザー名が使用されているため、セキュリティ侵害の発生時に、saltにより、すべてのユーザー名を変更しなくて済むことです。
saltは、マップo.webcenter.jf.csf.map内の資格証明ストア・フレームワーク(CSF)にキーuser.token.saltに対して格納されます。このキー(およびトークンの暗号化で使用した他のキー)の値は、Oracle Enterprise ManagerでCSFにアクセスすることによって変更できます。
|
注意: 暗号化キーの値を変更すると、ユーザー名ベースの既存のすべてのセキュリティ・トークンがただちに無効になります。アルゴリズムのパラメータがセキュリティ侵害された場合など、特別な事情がある場合のみ、これらの値を変更します。 |
RESTおよびRESTfulスタイルのソフトウェア・アーキテクチャのメリットについて、多くの優れた記事が公開されています。このようなメリットの一部を、次に示します。
Hypermedia As The Engine Of Application State (HATEOAS)リンクを使用したREST APIへのアクセスは、APIの堅牢性の向上に役立ちます。クライアントはサーバーから返されるURIのみを使用するため、サーバーがURIの形式を変更しても、クライアントは引き続き正しく動作します。第53.5項「リンク・モデルの理解」も参照してください。
標準のHTTPプロトコルの使用により、ネットワーク・インフラストラクチャは必要に応じてRESTリクエストをキャッシュでき、クライアントとサーバーの両方の負荷が低減されます。第53.11項「キャッシュの管理」も参照してください。
ステートレスなRESTリクエストにより、各リクエストは任意の数の異なるサーバーによって処理され、スケーラビリティに役立ちます。
標準のHTTPプロトコルの使用により、多様なクライアントが、特殊なライブラリを必要とすることなく、REST APIを操作できます。
モバイル・アクセスの有効化に加え、WebCenter Portal REST APIを使用すると、Ajax、JavaScript、JSONなどのWeb 2.0テクノロジを使用して、豊富でインタラクティブなブラウザベースのユーザー・インタフェースを作成したり、Oracle WebCenter Portal FrameworkおよびWebCenter Portalのデータにアクセスし変更したりできます。一般に、WebCenter RESTコマンドは、より自然で使いやすい、SOAPスタイルWebサービス・アプローチの代替を提供します。
表53-1では、WebCenter Portalのツールとサービス機能用に提供されているOracle WebCenter Portal REST APIについて説明しています。
|
注意: Portal Frameworkアプリケーションでは、REST APIナビゲーションのみをサポートしています。その他すべてのREST APIは、WebCenter Portalアプリケーションのみによってサポートされています。 |
表53-1 REST APIでサポートされるWebCenterツールとサービス機能の一覧
| REST API | 説明 | 章 |
|---|---|---|
|
ディスカッション |
クライアントが、ディスカッション・フォーラム、トピックおよびメッセージを投稿、読取り、更新および削除できます。 |
|
|
リスト |
クライアントが、指定されたポータルに関連付けられたすべてのリストの参照、検索条件によるリスト列の検索、新規リストの作成、リスト行の追加、更新および削除、および同様のリスト関連タスクを実行できます |
|
|
ピープル・コネクション |
クライアントが、プロファイル・データの表示、コネクション・リスト、フィードバックおよびメッセージの管理、ユーザー、リストおよびポータルでの新規アクティビティの作成とアクティビティの表示を実行できます。 |
|
|
WebCenter Portal |
クライアントが、ポータル・メタデータの取得、およびポータル・リストとリスト・アイテムの表示、作成、更新および削除を実行できます。開発者はポータル・メンバーシップ情報も取得できます。 |
第56.2項「WebCenter Portal REST APIの使用」 |
|
コンテンツ管理 |
Content Management Interoperability Services (CMIS) RESTfulサーバー・バインディングを使用して、Content Management Virtual Content Repository (CM VCR)へのアクセスを提供します。 |
第31章「Content Management REST API」 |
|
アクティビティ・グラフ |
基になるアクティビティ・グラフ・エンジンを使用して、接続、ポータルおよびアイテムに関する推奨事項を取得できます。 |
|
|
イベント |
指定されたポータルに関連付けられたカレンダ・イベントにアクセスできます。 |
|
|
フィードバック |
クライアントが、ソーシャル・ネットワーク・アプリケーションでフィードバックを作成、読取りおよび削除できます。 |
|
|
検索 |
検索を投稿、確認、更新および削除します。検索のキーワードと範囲を指定できます。たとえば、iPhoneではすべてのポータル、ドキュメントおよびWikiページ内の「smith」を検索できます。 |
|
|
タグ |
クライアントが、タグおよびタグ付けしたアイテムをポスト、読取り、更新および削除できます。 |
|
|
ナビゲーション |
ナビゲーションREST APIを使用して、ナビゲーションを表示する独自のインタフェースを作成します。 注意: ナビゲーションREST APIは、この章に記載されているリソース索引を共有しません。 |
|
|
パーソナライズ |
パーソナライズ・コンダクタにアクセスできます。 |
|
|
ページレット |
リモートWebサービスは、リソースとページレットに関する情報を取得できます。ページレットをプロキシ設定されていないページに注入して、「ページレット・プロデューサ」がOracle WebCenter Interaction、Oracle WebLogic Portal、またはその他のサードパーティ・ポータルのポートレット・プロバイダとして動作できるようにします。 |
第62.7.2.2項「RESTを使用したページレットへのアクセス」 |
|
注意: 次のURNに対するXSDファイルを示します。urn:oracle:webcenter:activities:stream -> activitystream.xsd urn:oracle:webcenter:messageBoard -> wall.xsd urn:oracle:webcenter:people -> people.xsd urn:oracle:webcenter:people:invitations -> people.xsd urn:oracle:webcenter:people:person -> people.xsd urn:oracle:webcenter:search:results -> search.xsd urn:oracle:webcenter:spaces -> spaces.xsd
|
ハイパーメディアは、2つの最も成功したWebベースの形式、HTMLとATOMのコアです。HTMLとATOMを使用して、消費者は、たとえば、ニュース記事へのリンクをクリックするなどして、リンクを介して他のハイパーメディア・ドキュメントへ移動できます。
ハイパーメディアは、RESTfulアプリケーションの状態を扱います(HATEOAS: Hypermedia As The Engine Of Application Stateと呼ばれています)。
|
注意: アプリケーションの状態を定義するHATEOASの例え:お気に入りのブラウザで確定申告しているものとします。ブラウザが機能停止したときには、W-2データの入力を終え、控除へ移動したところでした。失われた状態(控除の画面にいたがまだデータを入力する必要があったという事実)は、入力したw-2データではなく、アプリケーションの状態です(つまり、現在の状態から変更された状態)。 HATEOASによって、この状態(アプリケーションの状態)が完全にハイパーメディアに取得されます。アプリケーションの状態とはアプリケーション内での場所であり、アプリケーションに入力したデータではありません。この方法のメリットの1つは、クライアントとサーバーが自分の状態を意識する必要がないため、単純化されることです。リクエストを処理するために必要なすべての状態情報がリンクに含まれるため、ブラウザが再起動してリンクに戻ったときに、ユーザーは税金プロセスの同じ場所にいます。 |
RESTfulサービスへの一連の最上位レベルURIエントリ・ポイントがある場合、これらのエントリ・ポイントを超えたすべてのやり取りは、レスポンス形式で返されるハイパーメディア・リンクで行われます。このリンク中心の方法により、クライアントとサーバーURLとの結付きがあまり密接にならずにすみます。クライアントはサーバーから与えられたURLを使用しているため、サーバーURLが形式を変更しても、クライアント・コードが中断することはありません。
このリンク・モデルを理解することで、サービスから返されるデータを使用したREST APIのナビゲーション方法を理解できます。
この項では、WebCenterのRESTfulサービスが使用するハイパーメディア・リンク・モデルについて説明します。次のサブセクションが含まれます:
WebCenterでは、リソース索引が、すべての認証アクセスの出発点です。リソース索引によって、一連の最上位レベルURIエントリ・ポイントへのアクセスが提供されます。これによって、使用可能なすべてのWebCenter RESTfulサービスへとつながります。リソース索引URIは、理解する必要がある唯一のURIです。
|
ヒント: RESTクライアントは、カスタムRESTリクエストの生成に役立ちます。たとえば、Firefox RESTClientアドオンは次の場所で入手できます。
他の類似のRESTクライアントも容易に取得できます。 |
WebCenterリソース索引URIは、次のとおりです。
http://host:port/rest/api/resourceIndex
|
注意: リソース索引へのアクセスには、常に認証が必要です。ただし、次のURIを使用して、(必要に応じて)CMISリソース・エントリ・ポイントに匿名でアクセスできます。
第53.9項「CMIS REST APIのセキュリティに関する考慮事項」および第53.8項「WebCenter Portal REST APIのセキュリティに関する考慮事項」も参照してください。 |
WebCenter Portal REST APIを使用する場合は、まず最初に、GETリクエストをリソース索引に送信します。レスポンスは、使用可能なサービスとリクエストのメディア・タイプによってそれぞれ異なります。例53-1は、JavaScript(および場合によりクライアント側のDojoなどのスクリプト・ライブラリ)を使用してリソース索引用のJSONデータを取得するAjaxリクエストを作成した場合に、レスポンスがどのように見えるかを示しています。これは簡略化したサンプル・レスポンスであり、実際のレスポンスに実在するすべてのリンクが含まれているわけではありません。
例53-1 リソース索引のGETへのレスポンス
{
"resourceType": "urn:oracle:webcenter:resourceindex",
"links": [
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:messageBoard",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"resourceType": "urn:oracle:webCenter:cmis",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:discussions:forums",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"resourceType": "urn:oracle:webcenter:resourceindex",
"rel": "self",
"href": "http://host:port/rest/api/resourceIndex",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:activities:stream",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:people:person",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:feedback",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:spaces",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
},
{
"template": "opaque-template-uri",
"resourceType": "urn:oracle:webcenter:people",
"href": "opaque-uri",
"capabilities": "urn:oracle:webcenter:read"
}
]
}
リソース索引データで返されるリンクを調べることによって、使用するリソース・タイプのURIを見つけて、個々のサービスのURIエントリ・ポイントを取得できます。目的の操作を実行できるようになるまで、ハイパーメディア内を移動し続けることが可能です。例53-2は、リソース索引のJSONデータを指定して得られるURIを見つけるメソッドを示しています。
例53-2 リソース索引内の特定のサービスのURIの検出
/* Parse the resourceIndex to find the specified URL and
* return it.
*
* @Param jsonData the JSON data retrieved from calling
* the /rest/api/resourceIndex URL.
* @Param strResourceType the resource type of the URL
* you want to retrieve from the resourceIndex data.
* E.g., 'urn:oracle:webcenter:activities:stream'
*/
function getResourceURL(jsonData, strResourceType)
{
// Using the HATEOAS model, we browse the returned links
// looking for the one with the correct resource type.
for (var i = 0; i < data.links.length; i++) {
if (data.links[i].resourceType == strResourceType) {
return data.links[i].href;
}
}
}
ハイパーメディア・リンクのresourceType、relおよびcapabilities属性は、クライアントがURIを直接解析する必要なく、使用するURI (hrefまたはtemplate)を決定できるようにするメタデータを提供します。URIは不透明で、メタデータによって特定の環境でどのリンクが役立つかが決まります。
例53-3および例53-4は、それぞれXMLとしてハイパーメディア・リンクの構造とJSONドキュメント・フラグメント内のハイパーメディア・リンクの構造を示しています。
例53-3 XMLドキュメント・フラグメント内のリンク
<links> <link href="opaque-URI" template="opaque-template-URI (optional)" rel="rel-name" title="human-readable-title (optional)" type="media-type (optional)" resourceType="resource-type" capabilities="operation"/> ...repeat as needed... </links>
例53-4 JSONドキュメント・フラグメント内のリンク
"links": [
{
"href":"opaque-URI",
"template":"opaque-template-URI (optional)",
"rel":"rel-name",
"title":"human-readable-title (optional)",
"type":"media-type (optional)",
"resourceType":"resource-type",
"capabilities":"operation"
},
...repeat as needed...
]
複合語のフィールド名、要素名および属性名は、サービス作成者の直接管理下にない仕様に準拠する場合を除いて、キャメル・ケースで書式設定されます。頭字語は、大文字と小文字が必要に応じて調整されて、通常の単語として扱われます(たとえば、fooXmlまたはxmlFoo)。例53-5および例53-6を参照してください。
この項では、ハイパーメディア・リンクの様々な属性について説明します。この項の内容は、次のとおりです。
resourceTypeリンク属性は、リンクが指すリソースのタイプを指定します。クライアントは、resourceTypeを使用して、GETとPOSTの予期されるレスポンス本文およびPOSTとPUTの受入可能なリクエスト本文を決定する必要があります。
詳細は、第53.7項「HTTPを使用したハイパーメディアのナビゲーション」を参照してください。
relリンク属性は、リンク・オブジェクトと現在のオブジェクト(リンクのリストが含まれるオブジェクト)の関係を指定します。この属性の値は、現在サポートされている次の値が空白で区切られたリストです。
self: リンク・オブジェクトは現在のオブジェクトです
related: リンク・オブジェクトは現在のオブジェクトに関係します
via: リンク・オブジェクトは現在のオブジェクトの情報ソースです
alternate: リンク・オブジェクトは現在のオブジェクトの代替です(通常、現在のオブジェクトを表示するHTMLページなど、別の形式の同じオブジェクト)
urn:oracle:webcenter:parent: リンク・オブジェクトは現在のオブジェクトの親です。つまり、リンク・オブジェクトが現在のオブジェクトを所有します
|
注意: 一部のWebCenter機能のREST APIによっては、relリンク属性が追加で含まれる場合があります。詳細は、特定の各機能のREST APIに関する説明を参照してください。 |
capabilitiesリンク属性は、リンク・リソースでサポートされるメソッドを指定します。
クライアントがそのリソースにアクセスできる場合のみ、リンクが返されます。レスポンス形式で返されるリンクでクライアントが実行できる機能は、ユーザー認証の影響を受ける可能性があります。通常、現在の認証ユーザーが実行権限を持ち、リソースがサポートしている機能のみが返されます。
リンクがない場合、クライアントはリソースにアクセスできません。リンクに機能がない場合は、クライアントに返らないため、クライアントにはそのリンクで何かを(読取りさえ)実行する権限がありません。
ハイパーメディア・リンクの機能ベース表現は、クライアントが実行できると予想される操作の範囲を明確に示します。これによって、クライアントは、関連するUIを動的に構成して、最適な全体のユーザーの操作性を提供できます。
この属性の値は、次の値が空白で区切られたリストです。
urn:oracle:webcenter:create: HTTP動詞のPOSTにマップします
urn:oracle:webcenter:read: HTTP動詞のGETにマップします
urn:oracle:webcenter:update: HTTP動詞のPUTにマップします
urn:oracle:webcenter:delete: HTTP動詞のDELETEにマップします
|
注意: 最上位レベルのresourceIndexリンクは、ユーザーが別の機能で認証されている場合でも、read機能のみを返します。 |
|
注意: OPTIONSを使用して許可されたHTTP動詞のリソースを問合せると、一般にリソースがサポート可能な動詞が返され、ユーザーのアクセス権は考慮されません。リンクの機能属性は、現在のユーザーが現在のリソースに対して実行できることを正確に示します。OPTIONSは、現在のユーザーに許可されているより多くのHTTP動詞を返すことがあります。 |
typeリンク属性は、リンク・オブジェクトがサポートするメディア・タイプを指定します。
CMISを除くすべてのRESTサービスは、XML (application/xml)とJSON (application/json)の両メディア・タイプをサポートします。CMISが現在サポートしているのは、ATOMのみです。CMIS REST APIの詳細は、第31章「コンテンツ管理REST API」を参照してください。
templateリンク属性は、クライアントがhref URIではなくURIテンプレートを使用して、リンク・オブジェクトのパラメータ化した値を提供できることを指定します。リンクは、少なくともhrefまたはtemplate URIを含む必要がありますが、両方を含むこともできます。
一部のハイパーメディア・リンクではリクエスト問合せパラメータがサポートされており、これを使用して、クライアントは異なる方法でリンクを構成できます。クライアントがURI形式を理解し、手動でURIを作成する必要はなく、URIテンプレートが使用されます。これらのテンプレートにより、クライアント・コードでは、URIの動作を正確に理解しなくても、URIにデータを簡単に挿入できます。これによってハイパーメディアURIの不透明性が維持され、URI形式の変更からクライアントが保護されます。
例53-7は、様々なリクエスト問合せパラメータを含むURIテンプレートを示しています。
例53-7 URIテンプレート
http://host:port/.../lists?startIndex={startIndex}&itemsPerPage={itemsPerPage}&q={searchTerms}&projection={projection]
WebCenter Portal REST APIでは、多くの業界URIテンプレート・スキームに従う、単純なスロット置換構文を使用します。
たとえば、例53-7のテンプレートを使用して1ページ目に10リスト・アイテム(デフォルト)を表示するには、例53-8に示すように、クライアントはstartIndexパラメータに値1を、itemsPerPageパラメータに値10を入力します。
|
注意: テンプレートを使用可能にするには、事前に未使用のパラメータをすべて削除する必要があります。クライアントは未処理のテンプレートを、それを生成したサービスへ送信できない場合があります。送信すると、未定義の動作が生じ、一般にステータス・コード500が返されます。クライアントは、サーバーに送信する前に、テンプレートを処理して有効なURI形式にする必要があります。クライアントは、スロット・トークンに置き換わる値を正しくURIエンコードして、スロットを適切な値に置換する必要があります。クライアントが、テンプレート内の1つ以上のスロットに対して適切な値を持たない場合は、スロット・トークンを空の文字列で置換する必要があります。 |
パラメータ値内の特殊文字または予約文字は、URLエンコードする必要があります。たとえば、Günterという名前のユーザーをリストで検索するには、例53-9に示すように、üをURLエンコードする必要があります。
共通のリクエスト問合せパラメータ
多くのリソースは、共通のリクエスト問合せパラメータ・セットをサポートしています。たとえば、エンティティのコレクションを取得する場合は、結果の数量または詳細を制限することによって、結果セットの内容を変更することが一般的です。RESTフレームワークでは、次のリクエスト・パラメータを使用して結果の範囲を指定し、セキュリティを提供します。
startIndex: 結果セットに含める、最初に一致する結果のインデックスを指定します(0-n ... 0から始まる)。これはページ区切りに使用されます。
itemsPerPage: レスポンスで返す結果の最大数を指定します(1-n)。これはページ区切りに使用されます。
q: 実装固有の検索を指定します。検索は次の形式で指定できます(角カッコ[]はオプション値を表します)。
[[field1:[operand]][:]value1[;field2:operand:value2]]
例:
&q=login:equals:monty &q=title:contains:issues &q=creator:equals:monty;description:contains:Urgent
各リソースが使用するqパラメータの形式は同じですが、検索の実装方法は、検索対象のリソースによってそれぞれ異なります。各リソースにおける検索の実装方法の詳細は、それぞれのサービスの章を参照してください。
projection: 変数の再帰深度、フィールドまたは属性のフィルタリングなど、モデル表示の実装固有のプロジェクション用に予約されています。有効な値はsummaryまたはdetailsです。
たとえば、リストのコレクションに対してsummaryのプロジェクションをリクエストすると、タイトル、説明およびハイパーメディアのリンクのみが返されます。detailsのプロジェクションをリクエストすると、サーバーは、各リストの列メタデータがすべて含まれるリストのコレクションを返します。この場合、処理時間が余分にかかったり、サーバー上でデータベース問合せが必要になることがあります。
次のリクエストの例では、深いオブジェクト・グラフが含まれるレスポンス・エンティティが返されます。
http://host:port/...lists&projection=details
data: このパラメータでは、カンマ区切りのデータ・セットおよびアイテムのリストを使用できます。このパラメータを使用して、クライアントは受け取るデータを指定できます。たとえば、モバイル・デバイス・アプリケーションは、このパラメータを使用して、返されるXMLデータの量を制限できます。projectionとdataの両方の問合せ文字列パラメータが存在する場合は、dataパラメータを使用して返すデータを決定します。データ・パラメータとして定数dataを指定すると、リソースに対してすべての標準情報が返されます。
特定のリソースでのこれらのパラメータのサポートの詳細は、該当のサービスの章を参照してください。
レスポンスの実際のコンテンツは、itemsのコレクションで構成されています。これは、前述のlinksセクションと同じレベルです。(各レスポンス内の最上位レベル・タグを含めて)各アイテムには、リソース固有のコンテンツと形式に加えて、1つの共通属性(resourceType)があります。resourceTypeの詳細は、特定のサービスに関する章を参照してください。
エンティティ/アイテムのコレクションを示す例は、例53-13を参照してください。例53-15は、単一のエンティティ/アイテムを示しています。
HTMLまたはATOMフィードで参照およびやり取りする場合と同様の方法で、RESTサービス・ハイパーメディアを移動できます。やり取りは、HTTPメソッドを使用して、リンクで識別されるリソースで行われます。RESTサービスは、レスポンス・コードおよびレスポンス本文をクライアントに返し、クライアントはレスポンス内のハイパーメディアを使用してその後のやり取りを行います。
表53-2は、不透明なリソースURIの作成時に従う一般的なパターンを示しています。resourceTypeは、HTTPメソッドがリソースのコレクションで動作するのか個々のリソースで動作するのかによって異なります。
表53-2 HTTPメソッド
| HTTPメソッド | リソースのコレクションの場合のレスポンス | 個々のリソースの場合のレスポンス |
|---|---|---|
|
|
リソース・コレクションのコンテナを返します(200 HTTPレスポンス・コード) |
リソースを返します(200 HTTPレスポンス・コード) |
|
|
リソースのコレクションを更新できません(405 HTTPレスポンス・コード) |
リソースを更新して返します(200 HTTPレスポンス・コード) |
|
|
コレクション内に新規リソースを作成して返します 注意: 201または204 HTTPレスポンス・コードを返します。返されるコードは、新規作成されたオブジェクトが、直接アドレス可能であるかどうかによって異なります。たとえば、アクティビティは個別にアドレスを指定できないため、204のコンテンツなしというレスポンス・コードが返されます。 |
個々のリソース内にリソースを作成できません(405 HTTPレスポンス・コード) |
|
|
リソースのコレクションを削除できません(405 HTTPレスポンス・コード) |
リソースを削除します(204 HTTPレスポンス・コード) |
コレクション・リソースでは、通常、コレクションの読取り(GET)およびそのコレクションの従属要素の作成(POST)がサポートされます。個々のリソースでは、通常、リソースの読取り(GET)、更新(PUT)および削除(DELETE)がサポートされます。
HTTPレスポンス・ステータス・コード
表53-3は、返される可能性があるレスポンス・ステータス・コードを示しています。
表53-3 HTTPレスポンス・ステータス・コード
| HTTPレスポンス・ステータス・コード | 説明 |
|---|---|
|
200 |
OK。 |
|
201 |
作成済。 |
|
204 |
コンテンツなしまたはコンテンツを返さないリクエスト。たとえば、リンクできないオブジェクトを作成する場合です。 |
|
400 |
不正なリクエスト。URIが不正な形式だったか、処理できませんでした。たとえば、IDが正しく形式化されていなかったか、IDが |
|
401 |
未許可。クライアントは、資格証明を送信して再試行できます。問題の診断に役立つフォルト・レスポンス本文を伴う場合があります。 |
|
403 |
禁止。クライアントには、リソースの作成や削除など、特定のアクションを実行できる権限がありません。同じユーザーとしての再認証は役立ちません。問題の診断に役立つフォルト・レスポンス本文を伴う場合があります。 |
|
404 |
見つかりません。IDで特定のリソースを参照しましたが、リソースはありません。 |
|
405 |
メソッドは許可されていません。リクエストされたリソースで有効なメソッドのリストが含まれます。 |
|
406 |
受入れ不可。クライアントが送信した受入れヘッダー・メディア・タイプは要求された操作でサポートされていません。問題の診断に役立つフォルト・レスポンス本文を伴う場合があります。 |
|
409 |
競合。おそらくリソースIDが使用中であるか、またはエンティティが更新時に別のプロセスによって変更されました。問題の診断に役立つフォルト・レスポンス本文を伴う場合があります。 |
|
422 |
不正なエンティティ本体。本体内のデータが構文的に正しい場合でも、有効でなかったり、処理できませんでした。たとえば、行を更新する際にデータが無効な場合です。 |
|
500 |
内部サーバーのエラー。サーバーに予期せぬ状態が発生し、リクエストを処理できませんでした。 |
|
501 |
実装されていません。サーバーでは、リクエストを実行するために必要な機能がサポートされていません。これは、サーバーがリクエスト・メソッドを認識せず、リソースに対してこれをサポートできない場合のレスポンスです。 |
すべてのWebCenter REST URIは、(保護されているWebページと同様に)保護されているリソースを参照し、アクセスするには認証が必要です。
|
注意: 認証アクセス・ルールの1つの例外は、CMISリソースへのアクセスです。CMISリソースは、次のCMIS URIエントリ・ポイントを介して匿名でアクセスできます。
第53.9項「CMIS REST APIのセキュリティに関する考慮事項」も参照してください。 |
Basic認証を使用したリクエストによりこの認証に合格するか、またはクライアントとWebCenter RESTサービスがシングル・サインオンを使用するように構成できます。シングル・サインオンの詳細は、『Oracle WebCenter Portalの管理』の「SSLの構成」を参照してください。
Basic認証では、ユーザーのパスワードはプレーン・テキストで送信されます。このタイプの認証を使用する場合は、SSLを使用した接続の保護を考慮する必要があります。詳細は、『Oracle WebCenter Portalの管理』の「SSLの構成」の章を参照してください。
セキュリティを向上するために、すべてのURIには、hrefとtemplateのどちらの属性でも、セキュリティ・トークン・パラメータが含まれています。セキュリティ・トークンはユーザー・スコープです。つまり、認証ユーザーに基づいており、有効範囲は認証ユーザーで、そのユーザーのセッションでブックマークに指定したり、キャッシュしたりできます。このようなセキュリティ・トークンは、クロスサイト・リクエスト・フォージェリ(CSRF)攻撃の回避に役立ちます。
例:
<link template="opaque-template-uri/@me?startIndex={startIndex}&itemsPerPage={itemsPerPage} &token=generated-token" resourceType="urn:oracle:webcenter:messageBoard" href="opaque-uri/@me?token=generated-token" capabilities="urn:oracle:webcenter:read" />
|
注意: セキュリティ・トークンは、認証やアイデンティティ伝搬では使用されません。 |
WebCenter Portal REST APIは、認証ユーザーのアイデンティティに基づいて動作します。たとえば、ポータルのREST APIは、ポータルに関する情報のみを返し、ユーザーがアクセスできるポータルのみを変更できます。
CMIS REST APIが使用する認証スキームは、他のWebCenter Portal REST APIが使用するものとは異なります。他のWebCenter Portal REST APIでは、認証されていないアクセスは許可されず、アクセスを許可する前にユーザーに認証を要求しますが、CMIS REST APIでは、認証されていないアクセスでも許可されます。
ドキュメントが認証情報を要求して、その情報を受信しなかった場合(認証されていないユーザーがアクセスしていたため)、404エラーが返されます。これは必ずしもドキュメントが見つからないことを意味するのではなく、(認証されていない)ユーザーがそのドキュメントにアクセスするための適切な権限を持たないことを意味します。リクエストが成功するためには、現在のユーザーを識別するBasic認証ヘッダーが含まれている必要があります。
CMISはContent Management Interoperability Serviceの略であり、エンタープライズ・コンテンツ管理システムの標準のRESTインタフェースです。詳細は、第31章「コンテンツ管理REST API」を参照してください。
この項では、複数のWebCenter Portal REST APIで共有される共通タイプについて説明します。
共通タイプは、WebCenter Portal REST APIで使用されるオブジェクトを、一貫性のある方法で参照します。
この項には次のサブセクションが含まれます:
これは、システム内のユーザーを表す汎用データ・タイプです。様々なAPIで使用されて、たとえば、メッセージ・ボードやフィードバック・メッセージの作成者またはユーザーの上司や直属の部下を識別します。これは、次の要素で構成されています。
guid: ユーザーのGUID
id: ユーザーのログインID
displayName: ユーザーの表示名
personReferenceには、ユーザーのプロファイル・アイコンへのリンクも含まれています。値(small、mediumまたはlarge)を指定することによって、アイコンのサイズを制御できます。
personReferenceタイプが含まれる場所によっては、生成するレスポンスの関連するREST APIへのリンクを返すこともできます。たとえば、personReferenceタイプが、メッセージ・ボード・レスポンス内の作成者として含まれている場合は、メッセージ・ボード・サービスへのリンクを含みます。
これは、ポータルを表す汎用データ・タイプです。様々なAPIで使用されて、たとえばアクティビティ・ストリーム内では、特定のアクティビティが発生したポータルを識別します。次の要素で構成されています。
guid: ポータルのGUID
name: ポータルの名前
displayName: ポータルの表示名
groupSpaceReferenceには、htmlリンク、restリンクおよびアイコン・リンクも含まれています。
ポータブル連絡先タイプによって、Web上でアドレス帳および友人リストにアクセスする標準の手段が提供されます。ポータブル連絡先タイプは、ピープル・コネクション・サービスのプロファイル・コンポーネントが使用します。
|
注意: これらのタイプは、WebCenterのポータル連絡先タイプに基づいています。追加データを含む可能性があります。 |
この項には次のサブセクションが含まれます:
これは、ユーザーの名前に関する情報を提供するポータブル連絡先タイプです。これは、次の要素で構成されています。
formatted: ユーザーの書式設定されたフル・ネーム、たとえばMichael David Jones Ph.D.
familyName: ユーザーの姓、たとえばJones
givenName: ユーザーの名、たとえばMichael
honorificSuffix: ユーザーの敬称、たとえばEsq.やPh.D.
initials: ユーザーの先頭の頭文字、たとえばM.D.
maidenName: ユーザーの旧姓
ユーザー・リポジトリ構成およびデータによっては、要素の一部が表示されないことがあります。
これは、ユーザーの住所に関する情報を提供するポータブル連絡先タイプです。これは、次の要素で構成されています。
formatted: 書式設定された完全な住所
type: 住所のタイプ(例: 自宅、会社)
streetAddress: 番地
poBox: 私書箱番号
locality: 市町村
region: 都道府県
postalCode: 郵便番号
country: 国
ユーザー・リポジトリ構成およびデータによっては、要素の一部が表示されないことがあります。
これは、ユーザーの組織的な所属に関する情報を提供するポータブル連絡先タイプです。次の要素で構成されています。
name: 組織の名前
employeeNumber: ユーザーの従業員番号
employeeType: ユーザーの従業員タイプ。
department: ユーザーが所属する組織内の部門
defaultGroup: ユーザーが所属するデフォルト・グループ
title: 組織内でのユーザーの役職
description: 組織内でのユーザーの役割の説明
expertise: 組織内でのユーザーの専門
startDate: ユーザーが組織に加わった日付
ユーザー・リポジトリ構成およびデータによっては、要素の一部が表示されないことがあります。
これは、多様な連絡先情報のデータが格納される汎用オブジェクトです。これは、次の要素で構成されています。
primary: これが、この人に関するこのタイプの情報の主要部分であるかどうかを識別するブール値。主要要素は存在しない場合があり、同じタイプのデータに対して複数の値がある場合のみ関係します。
value: このタイプの値
type: 情報のタイプ。有効なタイプは次のとおりです。
standard: 有効な値はwork、home、other
phoneNumber: 有効な値はwork、home、fax、pager、mobile
photos: 有効な値はthumbnail
クライアント側の開発者は、リクエストとレスポンスでHTTPキャッシュ・ヘッダーを処理する方法を理解している必要があります。最終変更日を持つ個々のリソースは、エンティティ・タグも返します。エンティティ・タグを使用すると、特定のエンティティを効率的に取得できます。キャッシュにおけるエンティティ・タグの使用の詳細は、Hypertext Transfer Protocol仕様を参照してください。
http://www.w3.org/Protocols/
この項では、Apacheサーバー上に単純な応答再書込みを行うリバースHTTPプロキシを設定する方法を説明します。プロキシ・サーバーは、通常、ブラウザ・クライアントからのXMLHttpRequest (XHR)コールに関連する、クロスドメイン・リクエストの問題を回避するために使用されます。これらのコールは、通常、多機能な対話型のクライアント側インタフェースを作成する、Ajax開発技術に関係します。REST APIは、通常、このようなクライアント側開発のシナリオで使用されます。
|
注意: この項では、Apacheにプロキシ・サーバーを設定する単純な例を説明します。詳細は、http://httpd.apache.org/docsで入手できるApache Serverドキュメントを参照してください。プロキシ・サーバーに、Oracle HTTP Server (OHS)も使用できます。詳細は、『Oracle HTTP Server管理者ガイド』を参照してください。 |
Apacheでプロキシ・サーバーを設定する基本的な手順は次のとおりです。
Apacheサーバーへのアクセスを取得します。Apache 2.2.7以降のバージョンをお薦めします。
そのサーバーに、mod_substituteモジュールおよびmod_proxyモジュールがインストールされていることを確認します。Apacheのバージョン2.2.7以降にはmod_substituteがデフォルトで組み込まれていることに注意してください。mod_sedまたはmod_line_editも使用できますが、これらの構成はOracleではサポートされていません。
httpd.confまたは仮想ホスト構成ファイルを開き、次の行を追加し、適切な箇所を使用しているサーバー名またはサーバー情報で置き換えます。
ProxyRequests Off LoadModule substitute_module modules/mod_substitute.so SetOutputFilter SUBSTITUTE ProxyPass /rest/api/ http://myhost:8888/rest/api/ ProxyPassReverse /rest/api/ http://myhost:8888/rest/api/ Substitute s|myhost|yourhost|n ProxyPass /pathname/rest/api/ http://myhost:8888/rest/api/ ProxyPassReverse /pathname/rest/api/ http://myhost:8888/rest/api/ Substitute s|myhost:8888/rest/api|yourhost/pathname/rest/api|n
|
注意: このシナリオ例では、2つのサーバーがプロキシ設定されます。次の2つのコールは、実際にはこれら2つの異なるサーバーと通信していますが、クライアントからは同じサーバー・ホストと通信しているように見えます。
|
Apacheサーバーを再起動します。たとえば、Linuxでは次の操作を実行します。
sudo /etc/init.d/httpd restart
一部のLinuxの構成では、この方式によるApacheとのプロキシ設定には、httpdからのアウトバウンド接続を許可するためにSELinuxが必要であることに注意してください。SELinuxのGUI内またはコマンド・ラインを介してhttpd_can_network_connect flagを有効化すると設定できます。
|
開発者のヒント: httpd.confでUserDir権限を設定して、ユーザーが各自のpublic_htmlディレクトリにこれらのファイルをドロップできるようにします。たとえば、http://host/~yourname/sample.htmlをヒットしてサンプル・アプリケーションにアクセスし、サンプル・アプリケーションでhttp://host/rest/api/resourceIndexをXHRコールします。 |
この項では、WebCenter Portal REST APIの使用方法のサンプルを示します。次のサブセクションが含まれます:
この項では、RESTサービス・ハイパーメディアのナビゲーション方法のサンプルを示します。サンプルは、メッセージ・ボード上のメッセージの読取り、別のユーザーのメッセージ・ボードへのメッセージの投稿、不要なメッセージの削除およびメッセージ・ボードのメッセージをフィルタ処理する方法を示しています。
この項には次のサブセクションが含まれます:
最初は必ずリソース索引にアクセスします(例53-10)。
このリクエストは、メッセージ・ボードのエントリ・ポイントを含めて、RESTfulサービスへの最上位レベルURIエントリ・ポイントのリストを返します(例53-11)。
例53-11 リソース索引へのアクセスに対するレスポンス
200 OK
Accept: application/json;charset=UTF-8
{
"resourceType": "urn:oracle:webcenter:resourceindex",
"links": [
{
"resourceType": "urn:oracle:webcenter:resourceindex",
"capabilities": "urn:oracle:webcenter:read",
"rel": "self",
"href": "http://host:port/rest/api/resourceIndex"
},
{
"resourceType": "urn:oracle:webcenter:messageBoard",
"capabilities": "urn:oracle:webcenter:read",
"href": "opaque-messageBoard-URI"
},
...repeating for other services...
}
このリストを調べて、メッセージ・ボードへのアクセスに必要なURIを見つけることができます。resourceTypeがurn:oracle:webcenter:messageBoardであるリンクを探します。このリンクのhrefが、メッセージ・ボードへのアクセスに必要なものです。
他のリソースのrel、typeおよびtemplateも、正しいリンクを見つける上で役立ちます。
メッセージ・ボードの正しいURIがわかると、そのURIにGETリクエストを送信してメッセージを読み取ることができます(例53-12)。
メッセージ・ボード上のメッセージを読み取るには、ログインする必要があります。
レスポンスは、メッセージ・ボード上のすべてのメッセージに関する情報を提供します(例53-13)。
例53-13 メッセージ・ボードのメッセージの取得に対するレスポンス
200 OK
Accept: application/json;charset=UTF-8
{
"resourceType": "urn:oracle:webcenter:messageBoard",
"links": [
{
"resourceType": "urn:oracle:webcenter:messageBoard",
"capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create",
"rel": "self",
"href": "opaque-messageBoard-URI"
}
]
"items": [
{
"resourceType": "urn:oracle:webcenter:messageBoard:message",
"links": [
{
"resourceType": "urn:oracle:webcenter:messageBoard:message",
"capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:delete",
"rel": "self",
"href": "opaque-message-URI"
}
]
"id": "89add57c-7a35-4d35-b24f-ea9259612eb8",
"body": "What's up? It's been a while. Some of us are going to Conner O'Neal's after work. Want to go?",
"created": "2009-09-10T11:18:46.696-0700",
"author": {
"id": "carl",
"displayName": "carl",
"guid": "649A27F09D5C11DEBFAA799CBD41D9B8",
"links": [
{
"resourceType": "urn:oracle:webcenter:people:person",
"capabilities": "urn:oracle:webcenter:read",
"rel": "via",
"href": "opaque-person-URI"
},
{
"resourceType": "urn:oracle:webcenter:messageBoard",
"capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create",
"href": "opaque-messageBoard-URI-for-Carl"
},
{
"type": "text/html",
"resourceType": "urn:oracle:webcenter:spaces:profile",
"capabilities": "urn:oracle:webcenter:read",
"rel": "alternate",
"href": "opaque-profile-URI"
}
]
},
}
],
"startIndex": 0,
"itemsPerPage": 1,
}
レスポンスから、メッセージ・ボードに対してreadおよびcreateの機能を持つことがわかります。したがって、コンテンツの読取りおよび新しいメッセージの投稿が行えます。
さらに、レスポンスにはアイテムのコレクションも含まれます(この例では、コレクションは1つのアイテムのみで構成されています)。これらのアイテムは、resourceTypeがurn:oracle:webcenter:messageBoard:messageである、メッセージ・ボード上のメッセージです。メッセージのcapabilities属性は、この特定のメッセージについて、メッセージ・ボードからの読取りおよび削除が行えることを示しています。
各メッセージについて、レスポンスは次の情報を提供します。
id: メッセージの識別子
body: メッセージのテキスト
author: メッセージの作成者。author要素も、別の複数の要素で構成されます。
id: メッセージの作成者の識別子またはユーザー名
displayName: 表示用に書式設定された作成者の名前
guid: 作成者のグローバル一意識別子
author要素の中には、3つのリンクのコレクションもあります。これらのリンクのresourceTypeは、次のとおりです。
urn:oracle:webcenter:people:person: メッセージの作成者に関する情報を表示できます
urn:oracle:webcenter:messageBoard: 作成者のメッセージ・ボードでメッセージの読取りまたは作成を行えます
urn:oracle:webcenter:spaces:profile: 作成者のプロファイルのtext/htmlドキュメントを読み取れます
自分のメッセージ・ボード上のメッセージを読み、Carlのメッセージ・ボードに返信するとします。このためには、Carlのメッセージ・ボードのURIにPOSTリクエストを送信する必要があります。
正しいURIを見つけるには、resourceTypeがurn:oracle:webcenter:messageBoardである、authorリンクのhrefを使用します。
POSTリクエストにより、投稿先のリソースの従属リソースが作成されます。この例ではmessageBoardに投稿しているため、その従属リソースであるmessageを投稿する必要があります(例53-14)。
例53-14 別のユーザーのメッセージ・ボードへのメッセージの作成(POST)
POST opaque-messageBoard-URI-for-Carl
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
{
"body": "sure; see you guys at 6."
}
レスポンスは、Carlのメッセージ・ボードにメッセージが作成されたことを示しています(例53-15)。
例53-15 別のユーザーのメッセージ・ボードへのメッセージの作成に対するレスポンス
201 Created
Content-Type: application/json;charset=UTF-8
{
"id": "36b8464f-afda-44b5-90ad-8ecedcb040a3",
"body": "sure; see you guys at 6.",
"created": "2009-09-10T12:21:09.785-0700",
"resourceType": "urn:oracle:webcenter:messageBoard:message",
"links": [
{
"resourceType": "urn:oracle:webcenter:messageBoard:message",
"capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:update urn:oracle:webcenter:delete",
"rel": "self",
"href": "opaque-message-URI"
},
"author": {
"id": "mike",
"displayName": "mike",
"guid": "649657609D5C11DEBFAA799CBD41D9B8",
"links": [
{
"resourceType": "urn:oracle:webcenter:people:person",
"capabilities": "urn:oracle:webcenter:read",
"rel": "self",
"href": "opaque-person-URI"
},
{
"resourceType": "urn:oracle:webcenter:messageBoard",
"capabilities": "urn:oracle:webcenter:read urn:oracle:webcenter:create",
"href": "opaque-messageBoard-URI"
},
{
"type": "text/html",
"resourceType": "urn:oracle:webcenter:spaces:profile",
"capabilities": "urn:oracle:webcenter:read",
"rel": "alternate",
"href": "opaque:profile:URI"
}
]
}
]
}
PUTリクエストはPOSTリクエストによく似ていますが、親リソースではなく、編集されているリソースで実行される点が異なります。
Carlのメッセージ・ボードにメッセージを作成した場合、先のPOSTリクエストに対するレスポンスから、メッセージに関してread、updateおよびdeleteの機能を持つことがわかります。また、hrefでメッセージのURIもわかります。たとえば、急な仕事が入り、もう少し残ることが必要になったとします。メッセージのURIを使用して、PUTリクエストを送信してメッセージを更新することで、遅れることをCarlに伝えることができます(例53-16)。
例53-16 メッセージの更新(PUT)
PUT opaque:message:URI
Accept: application/json;charset=UTF-8
Content-Type: application/json;charset=UTF-8
{
"body": "working late; see you guys at 7."
}
レスポンスはPOSTのレスポンスとほぼ同じですが、bodyに更新されたメッセージがある点が異なります(例53-17)。
リソースのdelete機能を持っている場合、リソースに対してDELETEリクエストを実行すると、そのリソースは削除されます。Carlのメッセージ・ボード上のメッセージへのリンクは、deleteをサポートしています。
Carlのメッセージ・ボードに残したメッセージを削除することにします(例53-18)。
レスポンスは、ステータス・コード204のみです(例53-19)。
|
注意: DELETEはべき等です。つまり、複数回送信しても同じ結果が得られます。そのため、同じオブジェクトを2回削除しようとすると、以前に削除していても引き続き同じ204レスポンスを受信します。 |
メッセージは、可視性条件に基づき、(GET、POSTおよびPUTのHTTP動詞を使用して)フィルタ処理できます。メッセージ・ボードに投稿されたメッセージは次の可視性カテゴリに分けられます。
パブリック
プライベート
非表示
パブリックかつ非表示
プライベートかつ非表示
パブリック・メッセージとプライベート・メッセージの場合
メッセージ・ボードの所有者は、任意のメッセージをプライベートとしてマークできます。メッセージがプライベートとしてマークされると、そのメッセージは、メッセージの所有者以外には表示されません。デフォルトで、すべてのメッセージはパブリックです。
メッセージをプライベート・メッセージとして送信することもできます。たとえば、MikeがCarlのメッセージ・ボードを表示している場合、ユーザーであるMikeにはパブリック・メッセージのみ(プライベートとして送受信されたパブリック・メッセージも含む)が表示されます。
非表示メッセージと表示メッセージの場合
メッセージ・ボードの所有者は、任意のメッセージを非表示としてマークできます。メッセージが非表示としてマークされると、そのメッセージはメッセージ・ボードの所有者には表示されませんが、メッセージ・ボードを表示する他のユーザーには表示されたままになります。
次に、取得方法の例を示します。
例53-20 フィルタ処理されたメッセージの取得(GET)
me
all
rest/api/messageBoards/person/@me private rest/api/messageBoards/person/@me/private public
rest/api/messageBoards/person/@me/public hidden and public rest/api/messageBoards/person/@me/hidden private and hidden rest/api/messageBoards/person/@me/private_hidden
person
rest/api/messageBoards/person/<GUID>
メッセージを取得するログイン・ユーザーのGUIDが必要であることに注意してください。
space-guid
rest/api/messageBoards/space/<GUID>
space-guidでは可視性に基づくフィルタ処理が使用できないことに注意してください。
例53-21 新しいメッセージに対するフィルタ処理の使用(POST)
me
all
rest/api/messageBoards/person/@me
private
{"body" : "<BODY_CONTENT>","visibilityType" : "private"}
public
{"body" : "<BODY_CONTENT>","visibilityType" : "public"}
hidden and public
{"body" : "<BODY_CONTENT>","visibilityType" : "hidden"}
private and hidden
{"body" : "<BODY_CONTENT>","visibilityType" : "private_hidden"}
person
rest/api/messageBoards/person/<GUID>
「me」以外のGUIDの場合:
public
{"body" : "<BODY_CONTENT>","visibilityType" : "public"}
private
{"body" : "<BODY_CONTENT>","visibilityType" : "private"}
space-guid
rest/api/messageBoards/space/<GUID>
space-guidでは可視性に基づくフィルタ処理が使用できないことに注意してください。
例53-22 変更されたメッセージに対するフィルタ処理の使用(PUT)
me
all
rest/api/messageBoards/person/@me/messages/<msg guid>
private
{"body" : "<BODY_CONTENT>","visibilityType" : "private"}
public
{"body" : "<BODY_CONTENT>","visibilityType" : "public"}
hidden and public
{"body" : "<BODY_CONTENT>","visibilityType" : "hidden"}
private and hidden
{"body" : "<BODY_CONTENT>","visibilityType" : "private_hidden"}
person
rest/api/messageBoards/person/<GUID>/messages/<msg guid>
「me」以外のGUIDの場合:
public
{"body" : "<BODY_CONTENT>","visibilityType" : "public"}
private
{"body" : "<BODY_CONTENT>","visibilityType" : "private"}
space-guid
rest/api/messageBoards/space/<GUID>/messages/<msg guid>
space-guidでは可視性に基づくフィルタ処理が使用できないことに注意してください。
アクティビティ・ストリーム・データを正しく表示するには、次の操作を行う必要があります。
アクティビティ・ストリームURIエントリ・ポイントの取得
アクティビティ・ストリーム・データの取得
アクティビティ・ストリーム・データを表示するための処理
このサンプルは、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページでご利用いただけます。
http://www.oracle.com/technetwork/middleware/webcenter/ps3-samples-176806.html
次に、例53-23について説明します。
getResourceURLメソッドは、メイン・リソース索引(/rest/api/resourceIndex)のJSONデータを取得し、そのデータ内でアクティビティ・ストリーム・リソースのURIを見つけることによって、アクティビティ・ストリーム・サービスのURIエントリ・ポイントを取得する方法を示しています。
formatMessageメソッドは、アクティビティ・ストリーム・データを処理して表示可能な形式にします。これには、個々のメッセージの検索と、メッセージ内のテンプレート・パラメータをそのパラメータに対応するオブジェクトまたはユーザーの名前に置換する処理が含まれます。パラメータには、オブジェクトまたはユーザーを表示するためのリンクも含まれます。そのオブジェクトまたはユーザー用のRESTサービスへのリンクがある場合は、それが含まれることもあります。
|
注意: リソース索引およびアクティビティ・ストリームJSONデータを取得するには、Javascript(および場合によってはDojoなどのクライアント側スクリプト・ライブラリ)を使用してAjaxリクエストを作成し、結果のデータを適切なメソッドに渡します。 |
例53-23 アクティビティ・ストリーム・データの表示
/* Parse the resourceIndex to find the specified URL and
* return it.
*
* @Param jsonData the JSON data retrieved from calling
* the /rest/api/resourceIndex URL.
* @Param strResourceType the resource type of the URL
* you want to retrieve from the resourceIndex data.
* E.g., 'urn:oracle:webcenter:activities:stream'
*/
function getResourceURL(jsonData, strResourceType)
{
// Using the HATEOAS model, we browse the returned links
// looking for the one with the correct resource type.
for (var i = 0; i < data.links.length; i++) {
if (data.links[i].resourceType == strResourceType) {
return data.links[i].href;
}
}
}
/* Parse the resourceIndex to find the activity stream URL and
* then load it.
*
* @Param jsonData the JSON data retrieved from calling
* the /rest/api/resourceIndex URL.
*/
function getActivitiesURL(jsonData)
{
// Parse the JSON data to get the activities URI entry point.
var strHref = getResourceURL(jsonData,
'urn:oracle:webcenter:activities:stream');
// INSERT CODE HERE: Implement getting the JSON data from the
// strHref URL with the Accept header set to "application/json",
// and use the formatMessage(index, jsonData) function to get
// the displayable activity message for each activity.
}
/* Replace activity message parameters.
*
* @Param index the index of the activity to process
* @Param jsonData the JSON data retrieved from calling
* the /rest/api/resourceIndex URL.
*/
function formatMessage(index, jsonData)
{
var activity = jsonData.items[index];
var strMessage = activity.message;
// Look for activity parameters and replace them in the message.
if (activity.templateParams && activity.templateParams.items) {
for (var i = 0; i < activity.templateParams.items.length; i++) {
var param = activity.templateParams.items[i];
// Each parameter also has a set of links which at least
// includes an HTML link and possibly a REST API link.
strMessage = strMessage.replace(param.key, param.displayName);
}
}
if (activity.detail) {
strMessage = strMessage + "<br><font size='1'>" +
activity.detail + "</font>";
}
return strMessage;
}
次の例は、REST APIを使用してユーザーのWebCenter Portalプロファイル・ステータスを更新する方法を示しています。
|
注意: サンプルは、Webサーバー(Apache、Oracle HTTP Serverなど)またはアプリケーション・サーバーでホストする必要があります。クロスサイト・スクリプティング・エラーを防ぐには、プロキシURLを使用してRESTサービスにアクセスする必要があります。ApacheまたはOHSでは、confコマンドは次のようになります(必要に応じてmyspaceshostおよびportを変更します)。
ProxyPass /webcenter/ http://myspaceshost:port/webcenter/ ProxyPassReverse /webcenter/ http://myspaceshost:port/webcenter/ ProxyPass /rest/ http://myspaceshost:port/rest/ ProxyPassReverse /rest/ http://myspaceshost:port/rest/ ProxyPreserveHost on |
このサンプルは、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページでご利用いただけます。
http://www.oracle.com/technetwork/middleware/webcenter/ps3-samples-176806.html
ユーザー・ステータスの更新では、ステータス・オブジェクトのURLを取得するための、一連の非同期AJAXコールが行われます。
urn:oracle:webcenter:resourceindex
urn:oracle:webcenter:people
urn:oracle:webcenter:people:person:status
ユーザー・ステータスを更新するHTMLページ(例53-24)には、ユーザーが新しいステータス・メッセージ(statusMessage)を入力できる入力フィールドがあります。「Update Status」ボタンをクリックすると(または[Enter]キーを押すと)updateStatusメソッドがコールされて、リソース索引への初期コールが行われます。
例53-24 HTML本体
<body>
<div>New status message: <input id="statusMessage" type="text"
onkeyup="{if (event.keyCode==13) updateStatus();}" maxlength="250"
size="60" /></div>
<div>
<button id="button1" onclick="updateStatus();">Update Status</button>
</div>
<div id="statusResults"></div>
</body>
図53-1は、HTMLページを示しています。
例53-25のコードは、リソース索引(/rest/api/resourceIndexに設定されているresourceIndexURL変数)を取得します。リソース索引は、AJAXリクエスト・オブジェクト(resourceIndexRequest)として返されます。
例53-25 リソース索引の取得
function updateStatus() {
// Set the UI to busy state. This is cleared in the success and error callbacks
setUIBusy("Updating status...");
//get the Resource Index
resourceIndexRequest.get(
resourceIndexURL,
resourceIndexCallback,
clearUIBusy);
}
例53-26に示すgetResourceURLメソッドは、RESTコールによって返されるデータ内のリンクを調べて、要求されたリソース・タイプを識別する指定の文字列(URN)を見つけます。
例53-26 リンクのトラバース
function getResourceURL(data, strResourceType) {
for (var i = 0; i < data.links.length; i++) {
if (data.links[i].resourceType == strResourceType) {
return data.links[i].href;
}
}
return null;
}
例53-27では、getResourceURLを使用してリソース索引を解析して、ユーザー・プロファイルURLを見つけます。データは、AJAXリクエスト・オブジェクト(profileRequest)として返されます。
例53-27 ユーザー・プロファイルの取得
function resourceIndexCallback(data) {
//get my user profile
profileRequest.get(
getResourceURL(data, 'urn:oracle:webcenter:people'),
profileCallback,
clearUIBusy);
}
例53-28は、HTMLページでユーザーが指定した新しいステータス・メッセージを受け取り(statusMessage)、request.putを使用して、(getResourceURLを再びコールして取得した)ステータス・オブジェクトを更新します。
例53-28 ステータス・オブジェクトの取得
function profileCallback(data) {
profile = data;
// get the URL for the status object
var url = getResourceURL(data, 'urn:oracle:webcenter:people:person:status');
// get the new status and escape double quotes
var newStatus = document.getElementById
('statusMessage').value.replace(/\"/g. "\\\"");
//send a JSON string representing the new status object
var statusMessage = '{"note": "' + newStatus + '"}';
statusRequest.put(
getResourceURL(data, 'urn:oracle:webcenter:people:person:status'),
statusMessage, renderStatusPutResults, clearUIBusy);
}
例53-29のrenderStatusPutResultsメソッドは、新しいステータス・オブジェクトをレンダリングします。
例53-29 新しいステータス・オブジェクトのレンダリング
function renderStatusPutResults(data) {
var name = profile.displayName;
// get the URL for my profile HTML page in WebCenter Portal
var profileURL = getResourceURL(profile,
'urn:oracle:webcenter:spaces:profile');
var html = 'Status for <a href="' + profileURL + '" target="_blank">'
+ name + '</a> is: ' + data.note;
// clear the UI busy state and print the new status message
clearUIBusy(html);
}
例53-30は、UIを無効化および再有効化するコードを示しています。
例53-30 UIの無効化
function setUIBusy(message) {
document.getElementById('statusResults').innerHTML = message;
document.getElementById('button1').disabled = true;
document.getElementById('statusMessage').disabled = true;
}
function clearUIBusy(message) {
document.getElementById('statusResults').innerHTML = message;
document.getElementById('button1').disabled = false;
document.getElementById('statusMessage').disabled = false;
}
例53-31は、AJAXコールに役立つライブラリを示しています。その大部分はWebCenter固有のものではなく、JSONを返すサービスに対する任意のXHRリクエストで使用できます。
ライブラリには再利用可能なXHRオブジェクトが含まれています。このオブジェクトは、HTTP GET、POST、PUTおよびDELETEをサポートします。すべての関数は非同期であり、URLと2つのコールバック関数(成功した場合と失敗した場合)を使用します。成功コールは、戻りデータが含まれるJavaScriptオブジェクトを使用して行われます。失敗コールは、エラー文字列を使用して行われます。POSTおよびPUTも、JSON文字列のデータ引数を使用します。
例53-31 AJAXライブラリ
function AjaxRequest() {
// constructor to create an object oriented AJAX request
var xhr = null;
// get XHR object. Should work for IE 6+, Safari, and Mozilla based browsers
if (window.XMLHttpRequest) {
xhr = new window.XMLHTTPRequest;
} else {
try {
xhr = new ActiveXObject('MSXML2.XMLHTTP.3.0');
} catch (ex) {
xhr = null;
}
}
if (xhr == null) {
alert("Your browser does not support AJAX");
}
this.get = function(url, callback, errorCallback) {
xhr.open('GET', url, true);
// the REST APIs return XML by default. Please return JSON
xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
sendRequest(null, callback, errorCallback);
};
this.post = function(url, data, callback, errorCallback) {
xhr.open('POST', url, true);
// set headers to send and receive JSON
xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
sendRequest(data, callback, errorCallback);
};
this.put = function(url, data, callback, errorCallback) {
xhr.open('PUT', url, true);
// set headesr to send and receive JSON
xhr.setRequestHeader('Accept', 'application/json; charset=utf-8');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
sendRequest(data, callback, errorCallback);
};
this.deleteResource = function(url, callback, errorCallback) {
xhr.open('DELETE', url, true);
sendRequest(null, callback, errorCallback);
};
// set the callbacks and send the request with data, if any
function sendRequest(data, callback, errorCallback) {
xhr.onreadystatechange = function () {
processResponse(xhr, callback, errorCallback);
};
xhr.send(data);
}
function processResponse(xhr, callback, errorCallback) {
var data = null;
// can get called here many times. 4 means really done
if (xhr.readyState == 4) {
// let's call any HTTP codes in the 200s success
if (xhr.status >= 200 && xhr.status <300) {
// convert response text into a JSON object. This is insecure.
// data should not be blindly evaluated from the server return.
// consider using json2.js http://www.JSON.org/js.html
data = eval('(' + xhr.responseText + ')');
callback(data);
} else {
// we got an error. Format an error string
data = 'Error: ' + xhr.status + ' ' + xhr.statusText + '<br />'
+ xhr.responseText;
errorCallback(data);
}
}
}
}
