2 WLS RESTful管理インタフェースについて
Oracle WebLogic Server RESTful管理インタフェースについて、およびWLS MBeanをRESTインタフェースにマップする方法について学習します。
この章では、Oracle WebLogic ServerでサポートされているRESTful管理サービスについて説明します。この章の内容は次のとおりです。
- WLS RESTful管理インタフェースの概要
Oracle WebLogic Server RESTful管理インタフェースでは、WLS MBeanとディスクリプタ・インタフェースに基づくRESTリソースの動的な生成により、Oracle WebLogic Serverの管理が包括的にサポートされます。 - WLS BeanのRESTへのマッピング
WLS BeanがどのようにRESTインタフェースにマップされるかを学習します。 - エラー・メッセージの返送
リソースは、エラー・メッセージの返送に様々な形式を使用します。
WLS RESTful管理インタフェースの概要
WLS RESTリファレンス・ドキュメントのガイドは、「情報ロードマップ」を参照してください。
ノート:
Oracle WebLogic Server 14.1.1.0.0では:
-
以前のバージョンはすべて非推奨になりました: 12.2.1.0.0、12.2.1.1.0、12.2.1.2.0、12.2.1.3.0および12.2.1.4.0
-
14.1.1.0.0: これが
最新
のバージョンです
このリリースでの変更点を次に示します。
-
すべての以前のバージョンは非推奨になったため、かわりに14.1.1.0.0 RESTリソースを使用してください
-
最新
のバージョンが12.2.1.4.0から14.1.1.0.0に変更されました -
14.1.1.0.0に追加された新しいすべてのMBean機能は、12.2.1.1.0、12.2.1.2.0、12.2.1.3.0および12.2.1.4.0に表示されます。
-
14.1.1.0.0で非推奨となったMBean機能は、12.2.1.1.0、12.2.1.2.0、12.2.1.3.0および12.2.1.4.0 REST URLを使用して利用可能です。ただし、14.1.1.0.0のREST URLでは使用できません。
WLS Beanツリー用の生成済REST API
WLS Beanは、WLSコンポーネントが構成設定を管理し、実行サーバーを監視および管理するために、広汎に使用されます。
WLS Beanは、Javaインタフェースから導出されます。WLSは実行時に、システムを構成および監視するために使用できる、Java Beanの内部ツリーを作成します。以前のリリースでは、BeanツリーはJMX、WLSTおよび構成ファイル(config.xml
など)を介してのみ公開されていました。
このリリースでは、BeanツリーとBean情報を使用することにより、WLSが、実行時にRESTリソースを動的に、逐次、オンデマンド生成します。これらのRESTリソースは、WLS管理の代替選択肢となります。
親トピック: WLS RESTful管理インタフェースの概要
WLS Beanツリーの概要
次の各項では、RESTインタフェースの基礎となるWLS Beanに関する背景情報を提供します。
Beanには、次の2つの主要なタイプがあります。
-
構成: WLSを構成するために使用されます。
-
ランタイム: WLSを監視するために使用され、一部の操作ではWLSを制御します(サーバーの起動と停止、データ・ソース接続プールの縮小など)。
WLSは、次のBeanツリーを提供します。
-
編集アクセス: 構成(たとえば、
config.xml
およびシステム・リソース・ファイル)を変更するために使用される管理サーバーでのみ使用できます。 -
ランタイム・アクセス: すべてのサーバーで使用でき、そのサーバーの構成を表示し、その監視データにアクセスするために使用されます。
-
ドメイン・アクセス: 管理サーバーでのみ使用でき、実行サーバーのすべてのランタイムBeanのコピーを含み、監視の単一アクセス・ポイントを提供し、永続している最新の構成を表示するためにも使用されます。
WLS MBeanの詳細は、『Oracle WebLogic Server JMXによるカスタム管理ユーティリティの開発』のWebLogic Server MBeanの理解に関する項を参照してください。
Oracle WebLogic Scripting Tool (WLST)では、次のようにBeanツリーが表されます:
-
edit: 基礎となる編集アクセス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 RESTful管理インタフェースの概要
WLS BeanのRESTへのマッピング
WLS BeanがどのようにRESTインタフェースにマップされるかを学習します。
一般的なRESTパターン
WLS Bean(子の同種コレクション、必須のシングルトンの子およびオプションの同種のシングルトンの子)はほぼすべて、次のRESTパターンを使用します。
WLS Bean/RESTリソース | RESTメソッド | 説明 |
---|---|---|
コレクション: コレクション・リソース |
GET |
コレクションを戻します。 |
POST |
コレクションに新しいアイテムを作成します。 |
|
コレクション: 作成フォーム・リソース |
GET |
事前に移入されたエンティティを戻します。 |
コレクション: 子リソース |
GET |
コレクションにアイテムを戻します。 |
POST |
コレクションのアイテムを更新します。 |
|
DELETE |
コレクションからアイテムを削除します。 |
|
シングルトン: シングルトン・リソース |
GET |
シングルトンを戻します。 |
POST |
シングルトンが存在する場合は更新し、存在しない場合は作成します。 |
|
DELETE |
シングルトンを削除します。 |
|
操作: アクション・リソース |
POST |
操作を呼び出します。 |
親トピック: WLS BeanのRESTへのマッピング
ルート・リソースについて
管理サーバーと実行中の各管理対象サーバーは、各サーバーの管理ポート上で実行される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は管理サーバー上のものと正確に同様ですが、ホストとポートは異なります。
たとえば、管理サーバーのサーバー・ランタイムを表示するURL:
curl ... -X GET http://adminHost:7001/management/weblogic/latest/serverRuntime
管理対象サーバーのサーバー・ランタイムを表示するURL:
curl ... -X GET http://managed1Host:7002/management/weblogic/latest/serverRuntime
親トピック: WLS BeanのRESTへのマッピング
命名規則
WLS Beanプロパティ名は、REST URLとJSONオブジェクト・プロパティでの名前にマップされます。WLSプロパティ名は通常大文字で始まります(たとえば、Domain、JDBCDataSource、ServerRuntime)が、REST命名規則は、キャメル・ケース(小文字に大文字が続く)を使用します(たとえば、domain、JDBCDataSource、serverRuntime)。
親トピック: WLS BeanのRESTへのマッピング
REST URLのマッピング
各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として公開されません)。これらのBeanの詳細は、「WLS RESTful管理インタフェースの使用」を参照してください。
親トピック: WLS BeanのRESTへのマッピング
JSONマッピング
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 |
親トピック: JSONマッピング
アイデンティティ
各WLS Beanは、自身のBeanツリーの中で、URLの後置部分、バージョン指定子の後の部分により、一意に識別されます。たとえば、edit/machines/Machine-0
です。
このアイデンティティは、ツリーのルート・リソースに続くパス・セグメントごとに1つの文字列を使用して、JSON文字列配列にマップされます。たとえば:
[ "machines", "Machine-0" ]
親トピック: JSONマッピング
WLS Beanの参照
一部の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にマップされます。
親トピック: JSONマッピング
java.util.Properties
java.util.Properties
には、プロパティのリストが保持されます。たとえば、CommonLogMBean LoggerSeverityProperties
プロパティです。プロパティ・セット内の各プロパティに一致する文字列プロパティを使用して、JSONオブジェクトにマップされます。たとえば:
{ "property1": "value1", "property2": "value2" }
null java.util.Properties
は、JSON nullにマップされます。
親トピック: JSONマッピング
暗号化されたプロパティ
一部のWLS Bean文字列プロパティは、パスワードなどの機密データを保持するため暗号化されます。クライアントはパスワードを設定(クリアテキストの文字列として渡されます)できる必要がある一方で、他のユーザーは、それを表示する権限はありませんが、パスワードに値が設定されているかどうか(nullや未設定ではなく)を知りたいと思う場合があります。
マッピングは、インバウンドとアウトバウンドの暗号化されたプロパティで異なります。
アウトバウンドの暗号化されたプロパティでは、パスワードがnullの場合、JSON nullにマップされます。そうでない場合、JSON文字列@Oracle_Confidential_Property_Set_V1.1#
にマップされます。
インバウンドの暗号化されたプロパティでは、通常はGET
を実行してリソースの現在の値を取得し、変更するプロパティの値を設定して、その他は現在の値のままにし、新しい値をPOST
します。このため、POST
の値が@Oracle_Confidential_Property_Set_V1.1#
である場合、プロパティは変更されません(古いプロパティ値を保持します)。それ以外の場合、値はPOST
においてクリアテキストの文字列値に変更されます。
親トピック: JSONマッピング
Returning Error Messages
リソースは、エラー・メッセージの返送に様々な形式を使用します。
- 1つのエラー文字列を持つエラー・メッセージ
-
リソースが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" } ] }
親トピック: WLS RESTful管理インタフェースについて