Oracle® Fusion Middleware Oracle WebCenter Portal開発者ガイド 11g リリース1 (11.1.1.7.0) B72084-02 |
|
前 |
次 |
Oracle WebCenter Portalは、サーバー・データを取得および変更するための、一連のREST APIを備えています。この章では、WebCenter PortalのREST APIについて説明します。
この章には次の項が含まれます:
この章には、WebCenter Portal REST APIの使用方法を示すいくつかのサンプルが含まれています。他のサンプルについては、次の場所にある、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページを参照してください:
http://www.oracle.com/technology/products/webcenter/release11_demos.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に関する記事( |
RESTは、通常、クライアント側でスクリプトされ、サーバー側アプリケーションからのデータをやり取りする機能が必要なリッチ・インターネット・アプリケーション(RIA)で使用されます。たとえば、WebCenter iPhone AppはWebCenter Portal REST APIを使用して、WebCenter Portal: Spacesアプリケーションとやり取りします。ネイティブの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: Spacesのデータへアクセスし変更したりできます。一般に、WebCenter RESTコマンドは、SOAPスタイルWebサービス・アプローチのより自然で使いやすい代替を提供します。
表53-1では、WebCenter Portal: Services機能用に提供されているOracle WebCenter Portal REST APIについて説明しています。
表53-1 REST APIでサポートされるWebCenter Portal: Services機能の一覧
REST API | 説明 | 章 |
---|---|---|
ディスカッション |
クライアントが、ディスカッション・フォーラム、トピックおよびメッセージを投稿、読取り、更新および削除できます。 |
第33.3.8項「ディスカッション・サービスREST APIの使用」 |
リスト |
クライアントが、名前付きグループ・スペースに関連付けられたすべてのリストの参照、検索条件によるリスト列の検索、新規リストの作成、リスト行の追加、更新および削除、および同様のリスト関連タスクを実行できます |
|
ピープル・コネクション |
クライアントが、プロファイル・データの表示、コネクション・リスト、フィードバックおよびメッセージの管理、ユーザー、リストおよびグループ・スペースでの新規アクティビティの作成とアクティビティの表示を実行できます。 |
第41章「ピープル・コネクション・サービスREST API」 |
WebCenter Portal: Spaces |
クライアントが、グループ・スペース・メタデータの取得、およびグループ・スペース・リストとリスト・アイテムの表示、作成、更新および削除を実行できます。開発者はグループ・スペースのメンバーシップ情報も取得できます。 |
第56.3項「WebCenter Portal: Spaces REST APIの使用方法」 |
コンテンツ管理 |
Content Management Interoperability Services (CMIS) RESTfulサーバー・バインディングを使用して、Content Management Virtual Content Repository (CM VCR)へのアクセスを提供します。 |
Oracle Fusion Middleware Content Management REST Service開発者ガイド |
アクティビティ・グラフ |
基になるアクティビティ・グラフ・エンジンを使用して、接続、グループ・スペースおよびアイテムに関する推奨事項を取得できます。 |
|
イベント |
名前付きグループ・スペースに関連付けられたカレンダ・イベントにアクセスできます。 |
|
フィードバック |
クライアントが、ソーシャル・ネットワーク・アプリケーションでフィードバックを作成、読取りおよび削除できます。 |
|
検索 |
検索を投稿、確認、更新および削除します。検索のキーワードと範囲を指定できます。たとえば、iPhoneではすべてのスペース、ドキュメントおよびWikiページ内の「smith」を検索できます。 |
|
タグ |
クライアントが、タグおよびタグ付けしたアイテムをポスト、読取り、更新および削除できます。 |
|
ナビゲーション |
ナビゲーションREST APIを使用して、ナビゲーションを表示する独自のインタフェースを作成します。 注意: ナビゲーションREST APIは、この章に記載されているリソース索引を共有しません。 |
|
パーソナライズ |
パーソナライズ・コンダクタにアクセスできます。 |
|
ページレット |
リモートWebサービスは、リソースとページレットに関する情報を取得できます。ページレットをプロキシ設定されていないページに注入して、「ページレット・プロデューサ」がOracle WebCenter Interaction、Oracle WebLogic Portal、またはその他のサードパーティ・ポータルのポートレット・プロバイダとして動作できるようにします。 |
第65.2.2.2項「RESTを使用したページレットへのアクセス」 |
ハイパーメディアは、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です。
WebCenterリソース索引URIは、次のとおりです。
http://host:port/rest/api/resourceIndex
注意: リソース索引へのアクセスには、常に認証が必要です。ただし、次のURIを使用して、(必要に応じて)CMISリソース・エントリ・ポイントに匿名でアクセスできます。
第53.9項「CMIS 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; } } }
例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... ]
ハイパーメディア・リンクのresourceType
、rel
およびcapabilities
属性は、クライアントがURIを直接解析する必要なく、使用するURI(href
またはtemplate
)を決定できるようにするメタデータを提供します。URIは不透明で、メタデータによって特定の環境でどのリンクが役立つかが決まります。
複合語のフィールド名、要素名および属性名は、サービス作成者の直接管理下にない仕様に準拠する場合を除いて、キャメル・ケースで書式設定されます。頭字語は、大文字と小文字が必要に応じて調整されて、通常の単語として扱われます(たとえば、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によっては、 |
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
にマップします
注意: 最上位レベルの |
注意:
|
type
リンク属性は、リンク・オブジェクトがサポートするメディア・タイプを指定します。
CMISを除くすべてのRESTサービスは、XML (application/xml
)とJSON (application/json
)の両メディア・タイプをサポートします。CMISが現在サポートしているのは、ATOMのみです。CMIS REST APIの詳細は、『Oracle Fusion Middleware Content Management REST Service開発者ガイド』を参照してください。
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 Fusion Middleware Oracle WebCenter Portal管理者ガイド』のFrameworkアプリケーションでのシングル・サインオンの構成に関する項を参照してください。
Basic認証では、ユーザーのパスワードはプレーン・テキストで送信されます。このタイプの認証を使用する場合は、SSLを使用した接続の保護を考慮する必要があります。詳細は、『Oracle Fusion Middleware 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インタフェースです。詳細は、『Oracle Fusion Middleware Content Management REST Service開発者ガイド』を参照してください。
この項では、複数のWebCenter Portal REST APIで共有される共通タイプについて説明します。
共通タイプは、WebCenter Portal REST APIで使用されるオブジェクトを、一貫性のある方法で参照します。
この項には次のサブセクションが含まれます:
これは、システム内のユーザーを表す汎用データ・タイプです。様々なAPIで使用されて、たとえば、メッセージ・ボードやフィードバック・メッセージの作成者またはユーザーの上司や直属の部下を識別します。これは、次の要素で構成されています。
guid
- ユーザーのGUID
id
- ユーザーのログインID
displayName
- ユーザーの表示名
personReference
には、ユーザーのプロファイル・アイコンへのリンクも含まれています。値(small
、medium
またはlarge
)を指定することによって、アイコンのサイズを制御できます。
personReference
タイプが含まれる場所によっては、生成するレスポンスの関連するREST APIへのリンクを返すこともできます。たとえば、personReference
タイプが、メッセージ・ボード・レスポンス内の作成者として含まれている場合は、メッセージ・ボード・サービスへのリンクを含みます。
ポータブル連絡先タイプによって、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仕様を参照してください。
プロキシ・サーバーは、通常、ブラウザ・クライアントからのXMLHttpRequest (XHR)コールに関連する、クロスドメイン・リクエストの問題を回避するために使用されます。これらのコールは、通常、多機能な対話型のクライアント側インタフェースを作成する、Ajax開発技術に関係します。REST APIは、通常、このようなクライアント側開発のシナリオで使用されます。
プロキシ・サーバーの設定の詳細は、『Oracle Fusion Middleware Oracle WebCenter Portal管理者ガイド』のプロキシ・サーバーの構成に関する項を参照してください。
この項では、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)。
注意:
|
アクティビティ・ストリーム・データを正しく表示するには、次の操作を行う必要があります。
アクティビティ・ストリームURIエントリ・ポイントの取得
アクティビティ・ストリーム・データの取得
アクティビティ・ストリーム・データを表示するための処理
このサンプルは、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページでご利用いただけます。
http://www.oracle.com/technology/products/webcenter/release11_demos.html
次に、例53-20について説明します。
getResourceURL
メソッドは、メイン・リソース索引(/rest/api/resourceIndex
)のJSONデータを取得し、そのデータ内でアクティビティ・ストリーム・リソースのURIを見つけることによって、アクティビティ・ストリーム・サービスのURIエントリ・ポイントを取得する方法を示しています。
formatMessage
メソッドは、アクティビティ・ストリーム・データを処理して表示可能な形式にします。これには、個々のメッセージの検索と、メッセージ内のテンプレート・パラメータをそのパラメータに対応するオブジェクトまたはユーザーの名前に置換する処理が含まれます。パラメータには、オブジェクトまたはユーザーを表示するためのリンクも含まれます。そのオブジェクトまたはユーザー用のRESTサービスへのリンクがある場合は、それが含まれることもあります。
注意: リソース索引およびアクティビティ・ストリームJSONデータを取得するには、Javascript(および場合によってはDojoなどのクライアント側スクリプト・ライブラリ)を使用してAjaxリクエストを作成し、結果のデータを適切なメソッドに渡します。 |
例53-20 アクティビティ・ストリーム・データの表示
/* 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; }
Extは、表とフォームを作成し、それらをREST Webサービスにリンクするための、一般的なJavaScriptライブラリです。次の例は、Ext JsonStore
およびGridPanel
を使用してピープル・コネクション・サービスのREST APIからコネクションのリストを表示する方法を示しています。
Extの詳細は、次を参照してください。
注意: ExtはWebサーバーで実行する必要があります。そのサーバーがWebCenterインスタンスでない場合は、クロスサイト・スクリプティングの問題が発生します。WebCenterサーバーでサンプルを実行できないがExtを使用する必要がある場合は、Apache、WebCenter Ensembleなどのプロキシを検討します。 |
このサンプルは、Oracle Technology Network (OTN)のOracle WebCenter Portalのデモとサンプルのページでご利用いただけます。
http://www.oracle.com/technology/products/webcenter/release11_demos.html
この項には次のサブセクションが含まれます:
例53-21は、単純なHTMLページを示しています。HTMLページは、要求されるExtファイルおよびJavaScriptファイルconnections.js
を参照する必要があります。ページの本体には、宛先div
が含まれています。このdiv
内にGridPanel
がレンダリングされます。
例53-21 HTMLページ
<head> <link rel="stylesheet" type="text/css" href="../../extjs/resources/css/ext-all.css" /> <script type="text/javascript" src="../../extjs/adapter/ext/ext-base.js"></script> <script type="text/javascript" src="../../extjs/ext-all.js"></script> <script type="text/javascript" src="connections.js"></script> </head> <body> <div id="connections"></div> </body>
JavaScriptファイルconnections.js
を使用すると、ページがロードされたときにリストを移入できます。例53-22は、すべてのJavaScriptがExt.onReady()
へのパラメータであることを示しています。
JavaScriptは次の処理を行います。
最初に、リソース索引を問合せます(例53-23)。
例では、JSON形式のレスポンスを要求しています。
例53-23 リソース索引の問合せ
//Connection Information
var resourceIndexURL = "http://webcenter_server/rest/api/resourceIndex";
var peopleServiceURN = "urn:oracle:webcenter:people";
var connectionsURN = "urn:oracle:webcenter:people:person:list";
var connectionsRel = "urn:oracle:webcenter:people:person:list:connections";
//create a request for the resourceIndex
Ext.Ajax.request({
url: resourceIndexURL,
method: 'GET',
success: function(response, opts) {
//locate the people connections entry point
var index = Ext.decode(response.responseText);
for (x in index.links) {
if (index.links[x].resourceType == peopleServiceURN)
getMe(index.links[x].href);
}
},
failure: function(response, opts) {
alert('Could not communicate with the REST server.');
},
headers: {
'Accept': 'application/json'
},
});
次に、JavaScriptは認証されたリクエストをピープル・コネクション・エントリ・ポイントに送信し、レスポンスからコネクション・リストのURLを取得します(例53-24)。
デフォルトでは、REST APIはAPIを保護するためにBasic認証を使用します。この例では、コネクション・リストURLへ渡される資格証明はBase64エンコード方式です。Ext自体にはBase64ユーティリティ・オブジェクトはありませんが、次で開発されています:
http://extjs.com/forum/showthread.php?p=167166
例53-24 コネクション・リストURLの取得
function getMe(requestURL) { //Encode a token to identify yourself with secure parts of the REST API. var unencodedToken = "username" + ":" + "password"; var encodedToken = "Basic " + Ext.util.base64.encode(unencodedToken); //call the connections entry point Ext.Ajax.request({ url: requestURL, method: 'GET', success: function(response, opts) { //locate the link for my connections if (index.links[x].resourceType == connectionsURN) { if (index.links[x].rel == connectionsRel) getMyConnections(index.links[x].href, encodedToken); } }, failure: function(response, opts) { alert('Could not communicate with the REST server.'); }, headers: { 'Accept': 'application/json', 'Authorization' : encodedToken }, }); }
次に、認証されたリクエストをコネクション・リストURLに送信します(例53-25)。
例53-25 コネクション・リストURLへの認証済リクエストの送信
function getMyConnections(requestURL, encodedToken) { Ext.Ajax.request({ url: requestURL, method: 'GET', success: function(response, opts) { displayData(response, opts); }, failure: function(response, opts) { alert('Could not communicate with the REST server.'); }, headers: { 'Accept': 'application/json', 'Authorization' : encodedToken }, }); }
JavaScriptは、JsonStore
にレスポンスを追加します(例53-26)。
以前、この例では、コネクション・リストURLへのコールが正常なコールのためのハンドラとしてdisplayData()
が指定されていました。現在では、関数を作成し、JsonStore
コードを追加します。JsonStore
では、データのデータ・モデルが定義され、RESTコールで予期される結果にマップされます。
例53-26 JsonStoreへのレスポンスの追加
function displayData(response, opts) { //create a datamodel to display the JSON var store = new Ext.data.JsonStore({ // store configs autoDestroy: true, storeId: 'forumStore', // reader configs root: 'items', idProperty: 'id', fields: ['displayName', {name:'email', mapping:'emails.value'}, {name:'phone', mapping:'phoneNumbers[0].value'}] }); }
JavaScriptは、例53-27のコードをdisplayData()
に含めることによって、JsonStore
を表示するためのExt GridPanel
を作成します。
グリッドは、列とタイトルを定義します。表のサイズなど、他の表示オプションも含まれます。
例53-27 JsonStoreを表示するためのGridPanelの作成
//create the Grid var grid = new Ext.grid.GridPanel({ store: store, columns: [ {id: 'conn', header: 'Connection', width: 80, sortable: true, dataIndex: 'displayName'}, {header: 'Email', width: 120, sortable: true, dataIndex: 'email'}, {id: 'phone', header: 'Phone', width: 120, sortable: true, dataIndex: 'phone'} ], stripeRows: true, autoExpandColumn: 'conn', height: 200, width: 400, title: 'My Connections', viewConfig: {scrollOffset: 2} });
最後に、コードは、例53-28の行をdisplayData()
に含めることによって、GridPanel
をレンダリングします。
図53-1に、ピープル・コネクション・サービスREST APIのコネクションのリストを示します。
次の例は、REST APIを使用してユーザーのWebCenterプロファイル・ステータスを更新する方法を示しています。
注意: サンプルは、Webサーバー(Apache、Oracle HTTP Serverなど)またはアプリケーション・サーバーでホストする必要があります。クロスサイト・スクリプティング・エラーを防ぐには、プロキシURLを使用してRESTサービスにアクセスする必要があります。ApacheまたはOHSでは、confコマンドは次のようになります(必要に応じて 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/technology/products/webcenter/release11_demos.html
ユーザー・ステータスの更新では、ステータス・オブジェクトのURLを取得するための、一連の非同期AJAXコールが行われます。
urn:oracle:webcenter:resourceindex urn:oracle:webcenter:people urn:oracle:webcenter:people:person:status
ユーザー・ステータスを更新するHTMLページ(例53-29)には、ユーザーが新しいステータス・メッセージ(statusMessage
)を入力できる入力フィールドがあります。「Update Status」ボタンをクリックすると(または[Enter]キーを押すと)updateStatus
メソッドがコールされて、リソース索引への初期コールが行われます。
例53-29 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-2は、HTMLページを示しています。
例53-30のコードは、リソース索引(/rest/api/resourceIndex
に設定されているresourceIndexURL
変数)を取得します。リソース索引は、AJAXリクエスト・オブジェクト(resourceIndexRequest
)として返されます。
例53-30 リソース索引の取得
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-31に示すgetResourceURL
メソッドは、RESTコールによって返されるデータ内のリンクを調べて、要求されたリソース・タイプを識別する指定の文字列(URN)を見つけます。
例53-31 リンクのトラバース
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-32では、getResourceURL
を使用してリソース索引を解析して、ユーザー・プロファイルURLを見つけます。データは、AJAXリクエスト・オブジェクト(profileRequest
)として返されます。
例53-32 ユーザー・プロファイルの取得
function resourceIndexCallback(data) { //get my user profile profileRequest.get( getResourceURL(data, 'urn:oracle:webcenter:people'), profileCallback, clearUIBusy); }
例53-33は、HTMLページでユーザーが指定した新しいステータス・メッセージを受け取り(statusMessage
)、request.put
を使用して、(getResourceURL
を再びコールして取得した)ステータス・オブジェクトを更新します。
例53-33 ステータス・オブジェクトの取得
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-34のrenderStatusPutResults
メソッドは、新しいステータス・オブジェクトをレンダリングします。
例53-34 新しいステータス・オブジェクトのレンダリング
function renderStatusPutResults(data) { var name = profile.displayName; // get the URL for my profile HTML page in WebCenter Portal: Spaces 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-35は、UIを無効化および再有効化するコードを示しています。
例53-35 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-36は、AJAXコールに役立つライブラリを示しています。その大部分はWebCenter固有のものではなく、JSONを返すサービスに対する任意のXHRリクエストで使用できます。
ライブラリには再利用可能なXHRオブジェクトが含まれています。このオブジェクトは、HTTP GET、POST、PUTおよびDELETEをサポートします。すべての関数は非同期であり、URLと2つのコールバック関数(成功した場合と失敗した場合)を使用します。成功コールは、戻りデータが含まれるJavaScriptオブジェクトを使用して行われます。失敗コールは、エラー文字列を使用して行われます。POSTおよびPUTも、JSON文字列のデータ引数を使用します。
例53-36 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); } } } }