プライマリ・コンテンツに移動
Oracle Fusion Middleware Oracle WebLogic Server 12.1.3 RESTful管理インタフェース・リファレンス
12c (12.1.3)
E57542-02
  目次へ
目次
前
前 		 次
次		  

1 リソース

この項では、Oracle WebLogic Server 12.1.3 RESTful管理リソースについて説明します。

RESTful管理リソースは、サポートされているすべての環境内のOracle WebLogic Serverプラットフォームを構成、モニタリングおよび管理するための包括的なパブリック・インタフェースを提供します。


注意:

REST管理APIのURL形式が12.1.3で変更されました。12.1.2で導入されたURL形式は引き続き機能しますが、このりリースのWebLogic Serverでは非推奨になりました。

スタート・ガイド

WebLogic ServerドメインでRESTful管理サービスを使用するには、WebLogic管理者はWebLogic Server管理コンソールを使用してこれらを有効化する必要があります。詳細は、管理コンソール・オンライン・ヘルプのRESTful管理サービスの有効化に関する項を参照してください。または、WebLogic Scripting Tool (WLST)を使用して、DomainMBeanでRestfulManagementService Enabledプロパティを設定します。

WebLogic Serverを管理するためのREST URLフォーマット

WebLogic ServerリソースURLのフォーマットは次のとおりです。

http(s)://host:port/management/wls/{version}/path

説明:

host - WebLogic Serverが実行中のホスト

port - HTTPまたはHTTPSポート

{version} - RESTリソースのバージョン。「リソースURL内の{version}指定子」を参照してください。

path—リソースを識別する相対パス。たとえば、サーバー・インスタンスへのパスはservers/id/myserverとなります。

リソースURL内の{version}指定子

リソースURLの{version}指定子は、RESTリソースのバージョンを暗黙的(/latest)または明示的(/12.1.3.0)に示します。将来のWLSリリースでは、現在のRESTリソース・バージョンを使用するには/latestを、前のバージョンを指定するにはバージョン番号を指定できます。

ベスト・プラクティスとして、ナビゲーションにブラウザまたはリソース内のリンクに従う再帰クライアントを使用しており、進化するリソースに対応できる場合、/latestを使用します。リソースが進化すると破損するコードを記述している場合、バージョンを明示的に指定します。

RESTリソースでサポートされているコンテンツ・タイプ

WebLogic Server RESTful管理サービスは、次の表示フォーマットをサポートしています。

  • リソースから取得できるデータ・フォーマット(Acceptヘッダーなどを使用) - JSONのみ。

  • リソース内で送信できるデータ・フォーマット(Content-Typeヘッダーなどを使用) - ほとんどはJSONのみをサポートしますが、一部はマルチパート・フォームもサポートします(アプリケーションおよびライブラリのデプロイのファイル・アップロード・バージョンなど)。

RESTリソース・メソッドを使用したWebLogic Serverの管理

WebLogic Server RESTインタフェースは、構成およびモニタリング・オブジェクト・ツリー内のオブジェクトにアクセスするためのメソッドをサポートします。

表1-1は、モニタリングおよび構成データを管理するためのRESTメソッド、および各メソッドで実行できるタスクを示しています。

表1-1 構成データを管理するためのRESTリソース・メソッド

タスク RESTメソッド

ツリー内のオブジェクトがサポートするメソッドおよびメソッド・パラメータを特定します。

OPTIONS

ツリー内のオブジェクトのデータを取得します。

GET

オブジェクトをツリーに追加します。

POST

ツリー内のオブジェクトを更新します。

POST

ツリーからオブジェクトを削除します。

DELETE

WebLogic Server RESTリソースでは次の手順を使用します。

作成

新規エンティティを作成するには、次のようにします。

  1. OPTIONSを呼び出し、新規エンティティのデフォルト値を含むテンプレート・オブジェクトを取得します。

  2. 返されたオブジェクトでカスタマイズするプロパティの値を変更します。

  3. 変更したオブジェクトをPOSTし、新規エンティティを作成します。

編集

エンティティの一部のプロパティを変更するには、次のようにします。

  1. エンティティのURLでGETを呼び出し、エンティティの現在の値を含むオブジェクトを取得します。

  2. 返されたオブジェクトで変更するプロパティの値を変更します。

  3. 変更したオブジェクトをPOSTし、エンティティのURLに戻します。

非同期操作

実行時間が長い操作の場合、__detached=true問合せパラメータを指定します(非同期呼出し)。メソッドは、デタッチ(バックグラウンド)・モードで実行され、ジョブの起動後ただちに返されます。そうでない場合、ジョブが完了、失敗またはタイムアウトするのを待機します(同期呼び出し)。

結果のフィルタリング

_includeFieldsおよび_excludeFields問合せパラメータを指定し、レスポンスに含められるフィールドを制限します。必要とする情報のみに収集結果をフィルタリングすると、大規模なデータ・セットとやりとりする際にレスポンス時間を短縮できます。包含と除外は相互に排他的であり、いずれも指定しない場合すべての使用可能な情報が含まれます。

ファイルのアップロード

マルチパート・フォーム・データを使用して、バイトのストリームをクライアントからWLSリソースに渡します。たとえば、デプロイ(または再デプロイ)するファイルが管理サーバーのファイル・システムに存在しない場合などです。"multipart/form-data"を受け入れるPOSTを使用して、ファイルをクライアントのファイル・システムから管理サーバーにアップロードし、デプロイ(再デプロイ)します。

RESTリソース・ツリーの動的なナビゲート

WebLogic Server RESTインタフェースは、リソース・ツリーの動的なナビゲートをサポートします。このサポートを提供するために、各RESTリソースのGETメソッドは、リソース・ツリー内の前後のリソースへのURIリストを含むlinks要素を返します。これにより、この手法を使用してリソース・ツリーをナビゲートできます。

  1. リテラルでハードコードされた値をURIとして指定して、既知のRESTリソースでHTTP GETリクエストを行います。

  2. リソース内のlinksリストを解析し、適切な親または子リソースを識別します。詳細は、「リンク・リストの解析」を参照してください。

  3. ナビゲートを終了しており、ステップ 2で識別されたRESTリソースが操作を実行する対象である場合、適切なHTTPリクエストで、linksリストから取得したURI値を使用して操作を実行します。

    リソース・ツリーのナビゲートを続行する必要がある場合、linksリストから取得されたURI値を使用して、ステップ 2で識別されたRESTリソースでHTTP GETリクエストを行います。その後、ステップ 2に戻ります。

リソース・ツリーの動的ナビゲーションの使用には、様々な利点があります。

  • 各HTTPリクエストにはリテラルなハードコードされたURI値は含まれないため、ソース・コードがよりメンテナンスしやすくなります。

  • コード・デプロイメント中には名前が不明なサーバーやアプリケーションなどのオブジェクトの集合全体にわたってアクションを実行できます。

リンク・リストの解析

HTTP GETリクエストへのレスポンスの一部として返されるlinks要素は、従属要素であり、それぞれ現在のリソースに直接関連する単一リソースを記述します。各従属要素には、次のプロパティが含まれます。

rel

リンクされたリソースが現在のリソースにどのように関連するかを示す文字列値。文字列値は次のとおりです。

parent

リンクされたリソースは、現在のリソースの親です。

action

リンクされたリソースは、現在のリソースによって表されるオブジェクトでアクションを実行します。titleプロパティの値は、リンクされたリソースが実行するアクションのタイプを示します。

simple-name

ドット(.)を含まない文字列。リンクされたリソースには、現在のリソース固有の現在のリソースとの関係があります。たとえば、/management/wls/{version}リソースのGETメソッドでは、ドメイン内のオブジェクトのタイプに対応するsimple-name値を含むlinkリスト要素が返されます。

  • changemanger

  • datasources

  • deployments

  • jobs

  • servers

  • targets

dotted-name

1つのドット(.)を含む文字列。リンクされたリソースは、現在のリソースに従属するリソースの集合のメンバーであり、GETレスポンス内の別の要素はリンクされたリソースに関する詳細情報を提供します。このような集合の例として、/management/wls/{version}/serversリソースの下の個別のサーバーがあります。

dotted-name値の最初の部分は、詳細情報を含むGETレスポンス内のリスト要素の名前で、2番目の部分は各下位要素を識別するリスト要素の下位要素内のプロパティ名です。

list-element-name.subelement-property-name

リンクされたリソースに関する詳細情報を検出するには、そのdotted-name値をそのtitle値と組み合せて使用します。

  1. dotted-name値を、その2つの部分であるlist-element-nameとsubelement-property-nameで解析します。

  2. GETレスポンスで、list-element-nameという名前のリスト要素を探します。このリストで、subelement-property-nameプロパティ値が、リンクされたリソースのtitleプロパティ値に一致する下位要素を探します。

たとえば、dotted-name値がitems.nameで、title値がmyserverの場合、nameプロパティ値が文字列myserverと一致するitemsリストの下位要素をGETレスポンスで探します。

uri

リンクされたリソースにアクセスするためにHTTPリクエスト内で使用するURIを含む文字列値。

title

(オプション)relプロパティ値がactionまたはdotted-nameの場合、追加情報を提供する文字列値。

  • relプロパティ値がactionの場合、titleプロパティ値は、リンクされたリソースが実行するアクションの種類を記述します。

  • relプロパティ値がdotted-nameの場合、titleプロパティ値は、dotted-name値によって指定されるリスト要素の下位要素プロパティ内で一致する値です。

標準のHTTPステータス・コード

この項で説明されているリソースの操作に使用されるHTTPメソッドはすべて、次のHTTPステータス・コードのいずれかを返します。

200 OK

リクエストは正常に完了しました。200は、成功したGETまたはOPTIONSメソッド、またはリソースを(作成に対して)変更するためのPOSTメソッドに対して返されます。

201 Created

要求が満たされ、新規リソースが作成されます。新たに作成されたリソースの正規のURIを含むLocationヘッダーが返されます。

201は、同期リソース作成、またはレスポンスが返される前に完了した非同期リソース作成から返されます。

202 Accepted

要求の処理は受け入れられましたが、処理は完了していません。要求は、実際に処理が行われる際に拒否される可能性があるため、最終的には処理されない場合もあります。

非同期(__detached=true)リソース作成(アプリケーションのデプロイ時など)または更新(アプリケーションの再デプロイ時など)を指定する際、操作がまだ進行中である場合202が返されます。__detached=falseの場合、基底の操作が適切な時間で終了していないと202が返されることがあります。

レスポンスには、ジョブが終了した時期を検出するためにクライアントが調査する必要があるジョブ・リソースのLocationヘッダーが含まれます。また、ジョブの現在の状態を含むエンティティを返します。

400 Bad Request

情報が欠落しているか不適切であるため(入力フィールドでの検証エラー、必須値の欠落など)、リクエストを処理できませんでした。

401 Unauthorized

リクエストが認可されていません。このリクエストに認証資格証明がないか、または無効です。

403 Forbidden

ユーザーを認証できません。ユーザーは、このリクエストを実行する権限を所有していません。

404 Not Found

リクエストで、存在しないリソースのURIが指定されました。

405 Method Not Allowed

リクエストで指定されたHTTP動詞(DELETE、GET、HEAD、POST、PUT)は、このリクエストURIではサポートされていません。

406 Not Acceptable

このリクエストによって識別されたリソースは、リクエストのAcceptヘッダーのいずれかのメディア・タイプに対応する表現を生成できません。たとえば、クライアントのAcceptヘッダーは、XMLを要求しますが、リソースはJSONのみを返すことができます。

415 Not Acceptable

クライアントのContentTypeヘッダーに誤りがあります(たとえば、クライアントがXMLで送信しようとしたがリソースはJSONのみを受入れ可能な場合など)。

500 Internal Server Error

サーバーに予期しない状況が発生し、リクエストを遂行できなくなりました。

503 Service Unavailable

現在、サーバーは、一時的なオーバーロードまたはメンテナンスのため、要求を処理できません。WLS REST Webアプリケーションは現在実行中ではありません。

  前
前 		 次
次
  目次へ移動
目次