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

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の管理が包括的にサポートされます。12.1.3以降には、ドメイン環境、ライフサイクル管理(LCM)リソースおよびレガシー・リソースの構成と監視をサポートするリソースがあります。

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

ノート:

Oracle WebLogic Server 14.1.2.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.2.0.0: これは最新バージョンです

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

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

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

  • 14.1.2.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に表示されます。

  • 14.1.2.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 REST URLを使用して利用可能です。ただし、14.1.2.0.0のREST URLでは使用できません。

親トピック: WLS RESTful管理インタフェースについて

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インタフェースにマップされるかを学習します。

親トピック: WLS RESTful管理インタフェースについて

一般的な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ツリー

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は管理サーバー上のものと正確に同様ですが、ホストとポートは異なります。

たとえば、管理サーバーのサーバー・ランタイムを表示する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 説明 例

<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として公開されません)。これらのBeanの詳細は、「WLS RESTful管理インタフェースの使用」を参照してください。

親トピック: WLS BeanのRESTへのマッピング

JSONマッピング

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

親トピック: WLS BeanのRESTへのマッピング

文字列とスカラー

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

親トピック: JSONマッピング

配列

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

親トピック: 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管理インタフェースについて