| Oracle® Fusion Middleware RESTful管理サービスによるOracle WebLogic Serverの管理 12c (12.2.1.1.0) E77247-02 |
|
 前 |
 次 |
| Oracle® Fusion Middleware RESTful管理サービスによるOracle WebLogic Serverの管理 12c (12.2.1.1.0) E77247-02 |
|
|
前 |
次 |
ここでのトピック
WebLogic Serverでは、リリースごとに、WebLogic Server管理のためのRESTリソースが、広汎かつ強力になってきています。このリリースでは、WLS MBeanとディスクリプタ・インタフェースに基づくRESTリソースの動的な生成により、WebLogic Serverの管理が包括的にサポートされます。12.1.3以降には、パーティション化および非パーティション化環境、ライフ・サイクル管理(LCM)リソースおよびレガシー・リソースの構成と監視をサポートするリソースがあります。
WLS RESTリファレンス・ドキュメントのガイドは、「情報ロードマップ」を参照してください。
注意:
WebLogic Server 12.2.1では、動的RESTリソースは1つのバージョン(12.2.1.0)をサポートし、最新バージョンはそれを指していました。12.2.1.1では、動的RESTリソースは2つのバージョンをサポートします。
12.2.1.0 (12.2.1.0.0とも呼ばれます): このバージョンは非推奨になりました
12.2.1.1.0: これが最新のバージョンです
このリリースでの変更点を次に示します。
12.2.1.0 RESTリソースは非推奨になったため、かわりに12.2.1.1.0 RESTリソースを使用してください。
最新のバージョンが12.2.1.0から12.2.1.1.0に変更されました
新しいすべてのMBean機能が、12.2.1.1.0および12.2.1.0 RESTリソースに追加されました
12.2.1.1.0で非推奨となったMBean機能は12.2.1.0 REST URLを使用して利用できますが、12.2.1.1.0 REST URLでは利用できません
WLS Beanは、WLSコンポーネントが構成設定を管理し、実行サーバーを監視および管理するために、広汎に使用されます。
WLS Beanは、Javaインタフェースから導出されます。WLSは実行時に、システムを構成および監視するために使用できる、Java Beanの内部ツリーを作成します。以前のリリースでは、Beanツリーは、JMX、WLSTおよび構成ファイル(たとえば、config.xml)を介してのみ公開されました。
このリリースでは、BeanツリーとBean情報を使用することにより、WLSが、実行時にRESTリソースを動的に、逐次、オンデマンド生成します。これらのRESTリソースは、WLS管理の代替選択肢となります。
次の各項では、RESTインタフェースの基礎となるWLS Beanに関する背景情報を提供します。
Beanには、次の2つの主要なタイプがあります。
構成 - WLSを構成するために使用されます。
ランタイム - WLSを監視するため、および一部の操作(たとえば、サーバーの起動と停止、データ・ソース接続プールの縮小)でWLSを制御するために使用されます。
WLSは、次のBeanツリーを提供します。
編集アクセス - 管理サーバーでのみ使用でき、構成(たとえば、config.xmlおよびシステム・リソース・ファイル)を変更するために使用されます。
ランタイム・アクセス - すべてのサーバーで使用でき、そのサーバーの構成を表示し、監視データにアクセスするために使用されます。
ドメイン・アクセス - 管理サーバーでのみ使用でき、実行サーバーのすべてのランタイムBeanのコピーを含んでいて、監視の単一アクセス・ポイントを提供し、永続している最新の構成を表示するためにも使用されます。
WLS MBeanの詳細は、『Oracle WebLogic Server JMXによるカスタム管理ユーティリティの開発』の「WebLogic Server MBeanの理解に関する項」を参照してください。
WebLogic Scripting Tool (WLST)は、次のようにBeanツリーを表示します。
編集 - 基礎となる編集アクセスBeanツリーに一致します。
domainConfig - ドメイン・アクセスBeanツリーの構成MBeanハーフ(たとえば、永続している最後の構成)。
domainRuntime - ドメイン・アクセスBeanツリーのランタイムMBeanハーフ(たとえば、すべてのサーバーの監視用)。
serverConfig - ランタイム・アクセスBeanツリーの構成MBeanハーフ(たとえば、サーバーが使用している構成)。
serverRuntime - ランタイム・アクセスBeanツリーのランタイムMBeanハーフ(たとえば、特定サーバーの監視用)。
のRESTリソースは、WLSTのMBeanツリー表示に対応しています(編集、domainConfig、domainRuntime、serverConfigおよびserverRuntime)。
WLS Beanツリー内には、数タイプの親/子(包含)関係があります。
書込み可能コレクション - たとえば、ドメインBeanはサーバーBeanのコレクションを持っています。
必須シングルトン - たとえば、サーバーBeanは、自動作成され、削除できないSSL Beanを常に持っています。
オプションのシングルトン - たとえば、オーバーロードされた保護Beanは、オプションで、サーバー障害トリガーBeanを持つことができます。
Beanは、プロパティ(一般にはスカラー、文字列および配列)、他のBeanへの参照および操作(たとえば、サーバーの起動)を含むことができます。
含まれているコレクションに関して:
各々の子は、コレクション内で一意のアイデンティティを持っています(たとえば、各ネットワーク・チャネルは、そのサーバーの範囲内で一意である名前を持っています)。
大部分のコレクションは同種ですが(たとえば、ドメインのアプリケーション)、異質なものもいくつかあります(たとえば、セキュリティ・レルムの認証プロバイダ)。
次の各項では、WLS BeanがどのようにRESTインタフェースにマップされるかを説明します。次のような共通点があります。
リソースURLはすべてバージョン番号を含んでいて、latestという名のバージョンをサポートします。詳細は、『Oracle WebLogic Server RESTful管理インタフェース・リファレンス(レガシー)』の、リソースURL内の{version}指定子に関する項を参照してください。
リクエスト・ボディとレスポンス・ボディはすべて、JSONを使用します(メディア・タイプはapplication/json)。
レスポンス・ボディには、標準のプロパティ・セット(コレクションに関する情報を戻すためのitems、関連リソースにリンクを戻すためのlinks、成功、警告および障害メッセージを戻すためのmessages)があります。
リソースはすべて、標準HTTPレスポンス・コードを戻します(作成の成功は201、それ以外の成功は200、未検出は404、ユーザー入力エラーは400、内部サーバー・エラーは500)。詳細は、「標準RESTレスポンス」を参照してください。
WLS Bean(子の同種コレクション、必須のシングルトンの子およびオプションの同種のシングルトンの子)はほぼすべて、次のRESTパターンを使用します。
| WLS Bean/RESTリソース | RESTメソッド | 説明 |
|---|---|---|
コレクション: コレクション・リソース |
GET |
コレクションを戻します。 |
POST |
コレクションに新しいアイテムを作成します。 |
|
コレクション: 作成フォーム・リソース |
GET |
事前に移入されたエンティティを戻します。 |
コレクション: 子リソース |
GET |
コレクションにアイテムを戻します。 |
POST |
コレクションのアイテムを更新します。 |
|
DELETE |
コレクションからアイテムを削除します。 |
|
シングルトン: シングルトン・リソース |
GET |
シングルトンを戻します。 |
POST |
シングルトンが存在する場合、更新します。存在しない場合は作成します。 |
|
DELETE |
シングルトンを削除します。 |
|
操作: アクション・リソース |
POST |
操作を呼び出します。 |
次の表は、WebLogic ServerのRESTリクエストを送るために使用する必要がある標準ヘッダーを示しています。
| リクエスト・ヘッダー | 説明 |
|---|---|
|
クライアントがレスポンスにJSONを含めようとしていることを示します。このヘッダーはGET、POSTおよびDELETEメソッドを呼び出す場合に適しています。他のデータ・タイプを返すリソースは、リファレンス・マニュアルおよびサンプルに記載されています。 |
|
クライアントがJSONを含むレスポンスを送っていることを示します。このヘッダーはPOSTメソッドに適しています。他のコンテンツ・タイプをサポートしているメソッドもあり(デプロイメントのアップロード時など)、リファレンス・マニュアルおよびサンプルには、どのような場合にサポートされるのか記載されています。 |
|
REST経由でのクロスサイト・リクエスト・フォージェリ(CSRF)攻撃からの保護に使用されます。このヘッダーはPOSTおよびDELETEメソッドには必須で、OPTIONSおよびGETメソッドでは無視されます。 |
管理サーバーと実行中の各管理対象サーバーは、各サーバーの管理ポート上で実行されるREST Webアプリケーションをホスティングします。それぞれのコンテキスト・ルートは、managementです。ルートRESTリソースは、WLSTのBeanツリーを模倣しています。
表2-1に、管理サーバーのルート・リソースを示し、対応するBeanツリーをリストします。
表2-1 管理サーバーのルート・リソース
| URL | 説明 | 対応するBeanツリー |
|---|---|---|
|
WLS構成を編集します。 |
管理サーバーの編集ツリー・ドメインBean |
|
管理サーバーが現在実行対象としているWLS構成を表示します。 |
管理サーバーのサーバー・ランタイム・ツリー・ドメインBean |
|
管理サーバーを監視します。 |
管理サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean |
|
最後にアクティブ化されたWLS構成を表示します。 |
管理サーバーのドメイン・ランタイム・ツリー・ドメインBean |
|
WLSドメイン全体を監視します。 |
管理サーバーのドメイン・ランタイム・ツリー・ドメイン・ランタイムBean |
|
管理サーバーを介してWLSドメインにあるすべての実行中のサーバーを監視します。 |
実行中の各サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean |
|
管理サーバーを介してWLSドメインにある特定の実行中のサーバーを監視します。 |
指定されたサーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean |
|
ライフ・サイクル管理(LCM) RESTリソース。 |
なし |
|
12.1.3(レガシー)のWLS RESTリソース。 |
なし |
表2-2に、管理対象サーバー上のルート・リソースを示します。
表2-2 管理対象サーバーのルート・リソース
| URL | 説明 | 対応するBeanツリー |
|---|---|---|
|
管理対象サーバーが現在実行対象としているWLS構成を表示します。 |
管理対象サーバーのサーバー・ランタイム・ツリー・ドメインBean |
|
その管理対象サーバーを監視します。 |
管理対象サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean |
管理対象サーバー上のURLは管理サーバー上のものと正確に同様ですが、ホストとポートは異なります。
たとえば、管理サーバーのサーバー・ランタイムを表示する手順は、次のとおりです:
curl ... -X GET http://adminHost:7001/management/weblogic/latest/serverRuntime
管理対象サーバーのサーバー実行時を表示する手順:
curl ... -X GET http://managed1Host:7002/management/weblogic/latest/serverRuntime
WLS Beanプロパティ名は、REST URLとJSONオブジェクト・プロパティでの名前にマップされます。WLSプロパティ名は通常大文字で始まります(たとえば、Domain、JDBCDataSource、ServerRuntime)が、REST命名規則は、キャメル・ケース(小文字に大文字が続く)を使用します(たとえば、domain、JDBCDataSource、serverRuntime)。
各WLS Beanは、別個のRESTリソースにマップされます。含まれているコレクションと操作も、別々のリソースにマップされます。WLS Beanはすべて、ルート・リソース(たとえば、ドメイン)、含まれているコレクションの子(たとえば、サーバー)、含まれているシングルトンの子(たとえば、サーバーのSSL構成)のいずれかです。
ルート・リソースのURLは、表2-1と表2-2にリストされています。
含まれているコレクションBeanそれぞれのプロパティは、コレクション全体のURLおよびそれぞれの子のURLにマップされます。例:
| URL | 説明 | 例 |
|---|---|---|
|
コレクション全体を管理します。 |
|
|
コレクションにある子を管理します。 |
|
同様に、含まれているそれぞれのシングルトンBeanプロパティは、それ自身のURLにマップされます。たとえば、サーバーのSSL Beanは、.../edit/servers/<serverName>/SSLにマップされます。
含まれているBeanプロパティが作成できる場合(たとえば、ドメインのサーバー・コレクションに新しいサーバーを追加したり、ドメインに対してRDBMSSecurityStoreを作成したりできます)、作成フォーム・リソースも提供され、デフォルト値を持つテンプレートJSONオブジェクトを戻して、新しいリソースの作成を助けます。一般的な手順では、作成フォームをGETし、値を記入し、元のところにPOSTして新しいリソースを作成します。どのフィールドも記入されない場合は、現在の値を保持します。作成フォーム・リソースのURLは、たとえば<parent>/<singlularCollectionPropertyName>CreateFormです。
.../edit/serverCreateForm
.../edit/securityConfiguration/realms/myrealm/RDBMSSecurityStoreCreateForm
各Bean操作は、それ自身のURLにマップされます。たとえば、.../domainRuntime/serverRuntimes/<serverName>/shutdownは、特定のサーバーを停止するために使用されます。
大部分のWLS Bean操作は、含まれているBeanを作成、削除、リストおよび検索するために使用されます。これらの操作は、RESTでは別個に処理されます(REST操作URLとして公開されません)。「WLS RESTful管理インタフェースの使用」の説明を参照してください。
RESTは、WLS BeanがJSONに使用する様々なJava型(たとえば、プロパティ、操作引数および戻り型)をマップします。
Java文字列とスカラーは、それに対応するJSONにマップされます。
| Java | JSON | 例(JavaからJSON) |
|---|---|---|
|
stringまたはnull |
"Foo" -> "Foo" null -> null |
|
string |
'a' -> "a" |
|
number |
7001 -> 7001 |
|
number |
1.23 -> 1.23 |
|
boolean |
true -> true |
各WLS Beanは、自身のBeanツリーの中で、URLの後置部分、バージョン指定子の後の部分により、一意に識別されます。たとえば、edit/machines/Machine-0です。
このアイデンティティは、ツリーのルート・リソースに続くパス・セグメントごとに1つの文字列を使用して、JSON文字列配列にマップされます。例:
[ "machines", "Machine-0" ]
一部のWLS Beanプロパティは、他のWLS Bean(包含関係でなく)への参照を含みます。操作の引数と戻り型についても同様です。たとえば、サーバーBeanはマシンBeanへの参照を持っており、デプロイメントBeanはターゲットBeanの配列への参照を持っています。
シングルトン参照(たとえば、サーバーのマシン)は、次の例のように、値が参照済Beanのアイデンティティになっているプロパティ(およびリンク)にマップされます。
{
machine: [ "domain", "machines", "Machine-0" ],
links: [
{ rel: "machine", href: "http://localhost:7001/management/latest/weblogic/edit/machines/Machine-0" }
]
}
参照のコレクション(たとえば、サーバーの候補マシン)は、次の例のように、各要素が参照済BeanのアイデンティティならびにBeanへのリンクを含むオブジェクトである配列プロパティにマップされます。
{
candidateMachines: [
{
identity: [ "machines", "Machine-0" ],
links [ { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-0"
},
{
identity: [ "machines", "Machine-1" ],
links [ { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-1"
}
]
}
null参照またはnull参照コレクションは、JSON nullにマップされます。
java.util.Propertiesは、プロパティのリストを保持します(たとえば、CommonLogMBean LoggerSeverityPropertiesプロパティ)。それはJSONオブジェクトにマップされ、次の例のように、プロパティ・セットにある各プロパティの一致する文字列プロパティを持ちます。
{
"property1": "value1",
"property2": "value2"
}
null java.util.Propertiesは、JSON nullにマップされます。
一部のWLS Bean文字列プロパティは、パスワードなどの機密データを持つため、暗号化されます。クライアントはパスワードを設定(クリアテキストの文字列として渡されます)できる必要がある一方で、他のユーザーは、それを表示する権限はありませんが、パスワードに値が設定されているかどうか(nullや未設定ではなく)を知りたいと思う場合があります。
マッピングは、インバウンドとアウトバウンドの暗号化されたプロパティで異なります。
アウトバウンドの暗号化されたプロパティでは、パスワードがnullの場合、JSON nullにマップされます。そうでない場合、JSON文字列@Oracle_Confidential_Property_Set_V1.1#にマップされます。
インバウンドの暗号化されたプロパティでは、通常はGETを実行してリソースの現在の値を取得し、変更するプロパティの値を設定して、その他は現在の値のままにし、新しい値をPOSTします。このため、POSTの値が@Oracle_Confidential_Property_Set_V1.1#である場合、プロパティは変更されません(古いプロパティ値を保持します)。それ以外の場合、値はPOSTにおいてクリアテキストの文字列値に変更されます。
RESTリソースは、次の標準HTTPレスポンス・コードを戻します。
RESTメソッドは、操作が成功して新しいエンティティを作成しない場合、たとえば、リソースをGETした場合、POSTして操作を呼び出したりエンティティを変更したりした場合、DELETEでエンティティを削除した場合には、200 (OK)を戻します。
操作により新しいエンティティが正常に作成された場合、RESTメソッドは201 (CREATED)を戻します。また、新しいエンティティへのリンクを持つLocationヘッダーも戻します。
操作によりなんらかの非同期作業が正常に開始された場合、RESTメソッドは202 (ACCEPTED)を戻します。また、ジョブのステータスを検出するためにポーリングできるリソースへのリンクを持つLocationヘッダーも戻します。
指定されたリクエストに誤りがあるために(たとえば、無効な引数値)リクエストが失敗した場合、RESTメソッドは400 (BAD REQUEST)を戻します。
ユーザーが操作を実行する権限を持たない場合、RESTメソッドは401 (UNAUTHORIZED)を戻します。ユーザーが不正確な資格証明を入力した場合(たとえば、不正なパスワード)も、401が戻されます。
ユーザーがADMIN、OPERATOR、DEPLOYERまたはMONITORロールでない場合、RESTメソッドは403 (FORBIDDEN)を戻します。
リクエストされたURLが既存のエンティティを参照していない場合、RESTメソッドは404 (NOT FOUND)を戻します。
リソースは存在するがHTTPメソッドをサポートしていない場合、たとえばユーザーがドメイン構成ツリーのリソースを使用してサーバーを作成しようとした場合(構成編集ができるのは編集ツリーのみ)、RESTメソッドは405 (METHOD NOT ALLOWED)を戻します。
このリクエストで指定されたリソースは、リクエストのAcceptヘッダーにあるメディア・タイプのいずれかに対応する表現を生成できません。たとえば、クライアントのAcceptヘッダーは、XMLを要求しますが、リソースはJSONのみを返すことができます。
リクエスト内の誤りが原因でないエラーが発生した場合、RESTメソッドは500 (INTERNAL SERVER ERROR)を戻します。一般にRESTレイヤーは、MBeanがBAD REQUESTとして送出した例外を扱うため、500は通常、RESTレイヤーで発生した想定外の例外を報告するために使用されます。エラーまたはスタック・トレースのテキストはこれらのレスポンスに含まれませんが、通常、サーバー・ログに記録されています。
現在、サーバーは、一時的なオーバーロードまたはメンテナンスのため、要求を処理できません。WLS REST Webアプリケーションは現在実行中ではありません。
リソースは、次の形式を使用してエラー・メッセージを戻します。
リソースが1つのエラー文字列を戻す場合は、この形式を使用します。
HTTP/1.1 400 Bad Request
{
type: "http://oracle/TBD/WlsRestMessageSchema",
title: "FAILURE",
detail: "Bean already exists: \"weblogic.management.configuration.ServerMBeanImpl@31fa1656([mydomain]/Servers[Server-1])\"",
status: 400
}
リソースが複数のエラー文字列を戻す場合は、この形式を使用します。
HTTP/1.1 400 Bad Request
{
type: "http://oracle/TBD/WlsRestMessagesSchema",
title: "ERRORS",
status: 400,
wls:errorsDetails: [
{
type: "http://oracle/TBD/WlsRestMessageSchema",
title: "FAILURE",
detail: "no-such-protocol is not a legal value for DefaultProtocol.\
The value must be one of the following: [t3, t3s, http, https, iiop, iiops]",
o:errorPat: "defaultProtocol"
},
{
type: "http://oracle/TBD/WlsRestMessageSchema",
title: "FAILURE",
detail: "Type mismatch. Cannot convert abc to int",
o:errorPath: "listenPort"
}
]
}
