1. RESTful管理サービスを使用したOracle WebLogic Serverの管理
  2. WLS RESTful管理インタフェースについて

2 WLS RESTful管理インタフェースについて

WebLogic Server RESTful管理インタフェースについて、およびWLS MBeanをRESTインタフェースにマップする方法について学習します。

この章では、WebLogic ServerでサポートされているRESTful管理サービスについて説明します。

WLS RESTful管理インタフェースの概要

WebLogic Server RESTful管理インタフェースでは、WLS MBeanとディスクリプタ・インタフェースに基づくRESTリソースの動的な生成により、WebLogic Serverの管理が包括的にサポートされます。12.1.3以降には、パーティション化および非パーティション化環境、ライフ・サイクル管理(LCM)リソースおよびレガシー・リソースの構成と監視をサポートするリソースがあります。

ノート:

WebLogic Server Multitenantドメイン・パーティション、リソース・グループ、リソース・グループ・テンプレート、仮想ターゲットおよびリソース消費管理は、WebLogic Server 12.2.1.4.0で非推奨になり、次のリリースで削除されます。

WLS RESTリファレンス・ドキュメントのガイドは、「情報ロードマップ」を参照してください。

ノート:

WebLogic Server 12.2.1.4.0の場合:

  • 12.2.1.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: これが最新のバージョンです

このリリースでの変更点を次に示します。

  • すべての以前のバージョンは非推奨になったため、かわりに12.2.1.4.0 RESTリソースを使用してください

  • 最新のバージョンが12.2.1.3.0から12.2.1.4.0に変更されました

  • 12.2.1.4.0に追加された新しいすべてのMBean機能は、12.2.1.1.0、12.2.1.2.0および12.2.1.3.0でも表示されます

  • 12.2.1.4.0で非推奨となったMBean機能は、12.2.1.1.0、12.2.1.2.0および12.2.1.3.0 REST URLを使用して利用できますが、12.2.1.4.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 Beanツリーの概要

次の各項では、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へのマッピング

WLS BeanがどのようにRESTインタフェースにマップされるかを学習します。

一般的なRESTパターン

WLS Bean(子の同種コレクション、必須のシングルトンの子およびオプションの同種のシングルトンの子)はほぼすべて、次のRESTパターンを使用します。

WLS Bean/RESTリソース RESTメソッド 説明

コレクション: コレクション・リソース

GET

コレクションを戻します。

POST

コレクションに新しいアイテムを作成します。

コレクション: 作成フォーム・リソース

GET

事前に移入されたエンティティを戻します。

コレクション: 子リソース

GET

コレクションにアイテムを戻します。

POST

コレクションのアイテムを更新します。

DELETE

コレクションからアイテムを削除します。

シングルトン: シングルトン・リソース

GET

シングルトンを戻します。

POST

シングルトンが存在する場合、更新します。存在しない場合は作成します。

DELETE

シングルトンを削除します。

操作: アクション・リソース

POST

操作を呼び出します。

ルート・リソースについて

管理サーバーと実行中の各管理対象サーバーは、各サーバーの管理ポート上で実行されるREST Webアプリケーションをホスティングします。それぞれのコンテキスト・ルートは、managementです。ルートRESTリソースは、WLSTのBeanツリーを模倣しています。

表2-1に、管理サーバーのルート・リソースを示し、対応するBeanツリーをリストします。

表2-1 管理サーバーのルート・リソース

URL 説明 対応するBeanツリー

management/weblogic/<version>/edit

WLS構成を編集します。

管理サーバーの編集ツリー・ドメインBean

management/weblogic/<version>/serverConfig

管理サーバーが現在実行対象としているWLS構成を表示します。

管理サーバーのサーバー・ランタイム・ツリー・ドメインBean

management/weblogic/<version>/serverRuntime

管理サーバーを監視します。

管理サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean

management/weblogic/<version>/domainConfig

最後にアクティブ化されたWLS構成を表示します。

管理サーバーのドメイン・ランタイム・ツリー・ドメインBean

management/weblogic/<version>/domainRuntime

WLSドメイン全体を監視します。

管理サーバーのドメイン・ランタイム・ツリー・ドメイン・ランタイムBean

management/weblogic/<version>/domainRuntime/serverRuntimes

管理サーバーを介してWLSドメインにあるすべての実行中のサーバーを監視します。

実行中の各サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean

management/weblogic/<version>/domainRuntime/serverRuntimes/<serverName>

管理サーバーを介してWLSドメインにある特定の実行中のサーバーを監視します。

指定されたサーバーのサーバー・ランタイム・ツリー・サーバー・ランタイムBean

management/lifecycle

ライフ・サイクル管理(LCM) RESTリソース。

なし

management/wls

12.1.3(レガシー)のWLS RESTリソース。

なし

表2-2に、管理対象サーバー上のルート・リソースを示します。

表2-2 管理対象サーバーのルート・リソース

URL 説明 対応するBeanツリー

management/weblogic/<version>/serverConfig

管理対象サーバーが現在実行対象としているWLS構成を表示します。

管理対象サーバーのサーバー・ランタイム・ツリー・ドメインBean

management/weblogic/<version>/serverRuntime

その管理対象サーバーを監視します。

管理対象サーバーのサーバー・ランタイム・ツリー・サーバー・ランタイム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)。

REST URLのマッピング

各WLS Beanは、別個のRESTリソースにマップされます。含まれているコレクションと操作も、別々のリソースにマップされます。WLS Beanはすべて、ルート・リソース(たとえば、ドメイン)、含まれているコレクションの子(たとえば、サーバー)、含まれているシングルトンの子(たとえば、サーバーのSSL構成)のいずれかです。

ルート・リソースのURLは、表2-1と表2-2にリストされています。

含まれているコレクションBeanそれぞれのプロパティは、コレクション全体のURLおよびそれぞれの子のURLにマップされます。たとえば:

URL 説明 例

<parent>/<collectionPropertyName>

コレクション全体を管理します。

.../edit/servers

<parent>/<collectionPropertyName>/<childName>

コレクションにある子を管理します。

.../edit/servers/Server-0

同様に、含まれているそれぞれのシングルトン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管理インタフェースの使用」の説明を参照してください。

JSONマッピング

RESTは、WLS BeanがJSONに使用する様々なJava型(たとえば、プロパティ、操作引数および戻り型)をマップします。

文字列とスカラー

Java文字列とスカラーは、それに対応するJSONにマップされます。

Java JSON 例(JavaからJSON)

java.lang.String

stringまたはnull

"Foo" -> "Foo"

null -> null

char, java.lang.Character

string

'a' -> "a"

int

java.lang.Integer

long

java.lang.Long

number

7001 -> 7001

float

java.lang.Float

double

java.lang.Double

number

1.23 -> 1.23

boolean

java.lang.Boolean

boolean

true -> true
配列

非nullのJava配列は、JSON配列にマップされます。nullのJava配列は、JSONのnullにマップされます。

アイデンティティ

各WLS Beanは、自身のBeanツリーの中で、URLの後置部分、バージョン指定子の後の部分により、一意に識別されます。たとえば、edit/machines/Machine-0です。

このアイデンティティは、ツリーのルート・リソースに続くパス・セグメントごとに1つの文字列を使用して、JSON文字列配列にマップされます。たとえば:

[ "machines", "Machine-0" ]
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にマップされます。

java.util.Properties

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においてクリアテキストの文字列値に変更されます。

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"
    }
  ]
}