Oracle® Fusion Middleware RESTful管理サービスによるOracle WebLogic Serverの管理 12c (12.2.1.3.0) E90202-03 |
|
![]() 前 |
![]() 次 |
この章の内容は次のとおりです。
各RESTリソース・メソッドは、それにアクセスできるユーザー・ロール(管理者、デプロイヤ、オペレータ、モニター)を定めています。
一般的には、次のとおりです。
リソースを読み取るには(GET
メソッドを使用)、管理者、デプロイヤ、オペレータまたはモニター・ロールである必要があります。
リソースを作成するか(POST
およびDELETE
メソッドを使用)、操作を呼び出す(POST
を使用)には、管理者ロールである必要があります。
ただし、一部のリソースでは、デプロイヤがアプリケーションとライブラリをデプロイおよびアンデプロイでき、オペレータがサーバーを起動できます。
ユーザーがドメイン・ユーザーである(たとえば、ドメインのデフォルト・セキュリティ・レルムで定義されている)場合、RESTリソースにアクセスするURLはhttp://host:port/management
で始まります。ユーザーがパーティション・ユーザーである(たとえば、そのパーティションのセキュリティ・レルムで定義されている)場合、RESTリソースにアクセスするURLはhttp://host:port/
partition_name
/management
で始まります。
WebLogic Server Multitenantでのユーザー・ロールの詳細は、『Oracle WebLogic Server Multitenantの使用』の構成および管理のための管理ロールに関する項を参照してください。
WLS Beanを表示するには、対応するREST URLでHTTP GET
メソッドを呼び出します。
たとえば、サーバーServer-0
の構成を取得する手順は、次のとおりです:
GET http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
GET
は、標準WLS RESTレスポンス・ボディを戻します。Beanのプロパティとlinks
プロパティを含んでいるJSONオブジェクト、関連リソースへのリンクを含むJSON配列を戻します。
戻されたJSONオブジェクトは、標準のJavaからJSONへのマッピング(「JSONマッピング」を参照)を使用するWLS Beanのプロパティを含みます(たとえば、通常のプロパティと参照を含み、子を含まない)。また、Beanのアイデンティティを指定するidentity
プロパティも含みます。例:
{ identity: [ "domain", "servers", "Server-0" ], name: 'Server-0', listenPort: 7001, machine: { identity: [ "domain", "machines", "Machine-0" ] } }
リソースはすべて、リソースを参照するself
およびcanonical
トップ・レベル・リンクを含みます。たとえば、サーバーは、指定されたサーバーを参照するself
およびcanonical
リンクを含んでいます。
{ links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] }
これらのリンクの相互参照はそのRESTリソースも参照するため、リソースが子になっているツリーの名前(たとえば、edit
、domainRuntime
、serverConfiguration
など)を含みます。
ルート・リソースを除いて、リソースはすべて、親リソースへのトップ・レベル・リンクを含みます。リンクのrel
プロパティは、parent
に設定されています。
コレクションの子はコレクション・リソースへのリンクを戻します。たとえば、サーバーはサーバーのコレクション・リソースへのリンクを戻します。
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } ] }
同様に、シングルトンの子はコレクション・リソースへのリンクを戻します。たとえば、SSL BeanはサーバーBeanへのリンクを戻します。
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] }
Beanが作成可能である場合は、オプションのシングルトン(たとえば、レルムのRDBMSSecurityStore
)、Beanが現在存在しない場合は、対応する作成フォーム・リリースへのリンクも戻されます。リンクのrel
プロパティは、create
に設定されています。たとえば、セキュリティ・レルムの裁決プロバイダ上でGET
をコールすると、次も戻されます。
{ links: [ { rel: "create", href: "http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myrealm/adjudicatorCreateForm" } ] }
WLS Beanの包含プロパティ(たとえば、子)は、RESTリソースを分離するためにマップされるため、JSONレスポンス・ボディのトップ・レベル・リンクとして戻されます。
各リンクのrel
プロパティは、Beanプロパティの名前にマップされます。たとえば、Server-0
上でGET
をコールすると、次が戻されます。
{ links: [ // mandatory singleton child: { rel: "SSL", href: "http://localhost:7001/management/weblogic/latest/servers/Server-0/SSL" }, // writable collection of children: { rel: "networkAccessPoints", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPoints" } ] }
作成フォーム・リソースへのリンクは、作成できる包含プロパティ(シングルトンとコレクション)に対して戻されます。リンクのrel
プロパティは、<singularPropertyName>CreateForm
に設定されています。たとえば、Server-0
上でGET
をコールすると、次も戻されます。
{ links: [ { rel: "networkAccessPointCreateForm", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPointCreateForm" } ] }
WLS Beanは、各々の非nullシングルトン参照に対してトップ・レベル・リンクを戻します。リンクのrel
プロパティは、参照プロパティの名前に設定されます。たとえば、Server-0
がMachine-0
を参照する場合、次のようになります:
{ machine: [ "machines", "Machine-0" ], links: [ { rel: "machine", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-0" } ] }
Server-0
がマシン参照を持たない場合、次のようになります:
{ machine: null }
WLS Beanは、参照コレクションの各参照に対してネストされたリンクを戻します。リンクのrel
プロパティは、self
に設定されています。
たとえば、Application-0
がターゲットServer-0
およびCluster-0
を参照する場合、次のようになります:
{ targets: [ { identity: ["clusters", "Cluster-0" ], links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/clusters/Cluster-0" } ] }, { identity: ["servers", "Server-0" ], links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] } }
リソースは、操作リソースへのトップ・レベル・リンクも戻します。リンクのrel
プロパティはaction
に設定され、リンクのタイトルは操作の名前に設定されます。たとえば、ServerRuntimeMBean
は次を戻します。
{ links: [ { rel: "action", title: "suspend", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/suspend" }, { rel: "action", title: "resume", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/resume" }, { rel: "action", title: "shutdown", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown" } ] }
WLS Beanのコレクションを表示するには、対応するREST URLでHTTP GET
メソッドを呼び出します。
たとえば、すべてのサーバーの構成を取得する手順は、次のとおりです:
GET http://localhost:7001/management/weblogic/latest/edit/servers
GET
は、標準WLS RESTレスポンス・ボディを戻します。items
は子のプロパティを包含します。各アイテムは、その子のリソースにself
およびcanonical
リンクを埋め込んでいます。
直下の子のみが戻されます。たとえば、サーバー・コレクションを取得する場合、各サーバーのプロパティは戻されますが、サーバーの子(SSLなど)は戻されません。
リソースは、コレクションの各々の子に対してJSONオブジェクトを戻します。これらのオブジェクトは、子のリソース上でのGET
のコールから戻されたアイテムと同じデータを含みます。たとえば、ドメインBeanのservers
コレクションを取得すると、次が戻されます。
{ items: [ { name: "Server-1", listenPort: 7001, ... }, { name: "Server-2", listenPort: 7003, ... } ] }
コレクション・リソースは、次のリンクを戻します。
自身へのself
およびcanonical
リンク。
親へのリンク。
コレクションが書込み可能の場合、対応する作成フォーム・リソースへのリンク。
その各々の子への、ネストされたself
およびcanonical
リンク。
たとえば、ドメインBeanのservers
コレクションを取得すると、次が戻されます。
{ items: [ { name: "Server-1", listenPort: 7001, links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } ] }, { name: "Server-2", listenPort: 7005, links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } ] } ] links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" } { rel: "create-form", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" } ] }
新しいリソースを作成するために作成フォームを取得するには、対応する作成フォームREST URL上でHTTP GET
メソッドを呼び出します。
たとえば、新しいサーバーを作成するための作成フォームを取得する手順は、次のとおりです:
GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm
GET
は、標準WLS RESTレスポンス・ボディを戻します。作成フォームのプロパティとlinks
プロパティを含んでいるJSONオブジェクト(関連リソースへのリンクを含むJSON配列)を戻します。
戻されたJSONオブジェクトは、そのタイプの新しいリソースを作成するときに指定される場合がある、各書込み可能プロパティ(通常のプロパティおよび参照)に対するプロパティを含みます。プロパティの値は、そのタイプのBean情報(使用できる場合)からのデフォルト値、またはプロパティのタイプのデフォルト値(たとえば、int
の場合は0
)のいずれかです。参照プロパティの値は、常にnullです。たとえば、ドメインのserverCreateForm
を取得すると、次が戻されます。
{ name: null, // identity - unique names are not generated idleConnectionTimeout: 65, // from the default value in the bean info replicationGroup: null, // default value for a String since the bean info does not provide a default value machine: null, // singleton reference candidateMachines: null, // reference collection ... }
作成フォームは、次のリンクを戻します。
自身へのself
およびcanonical
リンク。
親へのリンク。
このタイプのリソースを作成するために使用できる、対応するリソースへのcreate
リンク。
たとえば、ドメインBeanのserverCreateForm
を取得すると、次が戻されます。
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" }, { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" }, { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" }, { rel: "create", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } ] }
Bean、コレクション、作成フォーム・リソースGET
メソッドは、これらの問合せパラメータをサポートしているため、レスポンスからプロパティとリンクを省略できます。
パラメータ名 | 説明 |
---|---|
|
これらのプロパティのみ戻されます。 |
|
これらのプロパティを除くすべてのプロパティが戻されます。 |
|
これらの |
|
これらの |
fields
とexcludeFields
は、links
とexcludeLinks
同様に、相互に排他的です。値はすべて、カンマで区切られた名前のリストです。
たとえば、サーバーのself
およびparent
リンクと、name
およびlistenPort
プロパティの、取得のみを行う手順は、次のとおりです:
curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/servers/myserver\ ?fields=name,listenPort\&links=self,parent { links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }, { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/myserver" } ], name: "myserver", listenPort: 7001 }
Beanを作成、変更、削除できるのは、編集ツリー内のみ(.../management/weblogic/<version>/edit/...
)です。他のBeanツリーは読取り専用です。
WLS Bean編集はすべて、構成トランザクション内で実行する必要があります。
トランザクションをすでに開始している場合、RESTの変更は同じトランザクションで行われます。ユーザーが引き続きトランザクションのコミットまたはロールバックを行います。
トランザクションを開始していない場合、RESTリソースがかわりにトランザクションを開始し、変更を試み、変更が行われたかどうかに関係なく、トランザクションをコミットまたはロールバックします(自動トランザクション)。
他のユーザーがトランザクションをすでに開始している場合、RESTリソースはエラーを戻します(構成を変更しません)。
場合によっては、同じトランザクションで複数のBeanへの補完的な変更が行われないかぎり、構成トランザクションをコミットできません。その場合、自動トランザクションを使用せず、明示的にトランザクションを開始および終了する必要があります。
また、クライアントがトランザクションを管理する場合は、各RESTコールが変更を保存します(ただし、アクティブ化はしません)。保存操作時に発生するいくつかのMBean検証があり、障害の原因になることがあります。たとえば、JDBCシステム・リソースを作成する場合、その子JDBCリソース名が設定されるまで、変更を保存できません。このような場合は、saveChanges=false
問合せパラメータを使用します。
Oracle WebLogic Server RESTful EditリファレンスのchangeManagerリソースに関する項を参照してください。
WLS Beanを変更するには、変更する値を含むJSONオブジェクトを構築し、対応するREST URL上でHTTP POST
メソッドを呼び出して、リクエスト・ボディとしてそのJSONオブジェクトを渡します。
たとえば、サーバーのリスニング・ポートと管理ポートを変更する手順は、次のとおりです:
curl ... -d "{ listenPort: 7007, administrationPort: 9007 }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
これは、Beanのプロパティのすべてを毎回渡す必要はなく、Beanの一部のみを変更すればよい点で、HTTP PATCH
操作に類似しています。
変更する値を含むJSONオブジェクトを構築します。一部のWLS Beanプロパティは読取り専用です(たとえば、サーバーの名前)。読取り専用プロパティは無視されます。
Beanのすべてのプロパティを渡す必要はありません。渡されないプロパティはすべて、現在の値を保持します。「暗号化されたプロパティ」で説明されているように、非null値を持つ暗号化された文字列プロパティの場合、GET
は値@Oracle_Confidential_Property_Set_V1.1#
を戻します。この値をPOST
して戻す場合、プロパティは現在の値を保持します。暗号化されたプロパティの値を変更する場合、たとえば次のように、クリアテキスト文字列に希望の値を設定します。
{ defaultIIOPPassword: "admin123" }
参照を変更するには、そのアイデンティティを渡します。参照コレクションの場合も同様です。これにより、参照コレクションが追加されるのでなく、参照コレクションが置き換えられます。たとえば、サーバーのマシンをMachine-0
に、候補マシンをMachine-0
およびMachine-1
に設定する手順は、次のとおりです:
{ machine: [ 'machines', 'Machine-0' ] }, candidateMachines: [ { identity: [ 'machines', 'Machine-0' ] }, { identity: [ 'machines', 'Machine-1' ] } ] }
また、参照を削除するにはnullを使用します。たとえば、サーバーのマシンと候補マシンの参照を削除する手順は、次のとおりです:
{ machine: null, candidateMachines: null }
有効および無効な値を混合して渡すと、有効なものは書き込まれ、無効なものにはエラーが戻され、全体として、RESTメソッドはOK
ステータス・コードを戻します。例:
curl ... -d "{ listenPort: 7007, administrationPort: 'foo' }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0 HTTP/1.1 200 OK { messages: [ { severity: "FAILURE", field: "administrationPort", message: "Something about the value needs to be an integer" } ] }
この例では、リスニング・ポートは変更されますが、管理ポートは変更されません。メソッドは、OK
ステータス・コードを戻しました。
前のリリースでは、WLSに複数の変数セッションが導入されました。これらの編集セッションは、スコープが指定されています。スコープは、ドメイン・レベル編集セッションに対して1つ、パーティションに対して1つ存在します。各スコープは、デフォルトの編集セッションを持っています。編集セッション名は、スコープ内で一意ですが、複数のスコープにはおよびません。
編集セッションの詳細は、『Oracle WebLogic Server Multitenantの使用』の名前付き同時編集セッションの管理に関する項を参照してください。
edit
ツリーのすべてのRESTリソースに対して、使用する編集セッション(スコープの名前とそのスコープ内の編集セッションの名前)を指定する必要があります。
編集セッション・スコープ名は、URLから導出されます。パーティション化されていないREST URLを使用する場合、RESTはドメイン・レベル・スコープを使用します。パーティション化されたREST URLを使用する場合、RESTはそのパーティションのスコープを使用します。
そのスコープ内で、RESTは、使用する編集セッションを認識している必要があります。使用する編集セッションを正確に記述したヘッダーを指定することも、デフォルト・ルールを使用してRESTに選択させることもできます。
weblogic.edit.session
ヘッダーをリクエストに含めることによって、編集セッションを選択することができます。ヘッダーの値が編集セッション名として使用されます。例:
curl ... -H weblogic.edit.session=MySession ...
各編集セッション・スコープは、default
という名のデフォルト編集セッションを持っています。スコープのデフォルト編集セッションを明示的に選択する手順は、次のとおりです:
curl ... -H weblogic.edit.session=default ...
新しいBeanのプロパティを含んでいるJSON構造とともにPOST
をコールして、新しいWLS構成Beanを作成します。
簡単にするために、対応する作成フォーム・リソースを使用して、様々な書込み可能プロパティのデフォルト値が移入されたテンプレートJSON構造を取得することができます。
コレクションの子を作成するには、コレクションのURL(たとえば、http://localhost:7001/management/weblogic/latest/edit/servers
)でPOST
をコールします。
オプションのシングルトンの子を作成するには、提案された子のURL(たとえば、http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicator
)でPOST
をコールします。
作成フォームを取得するには、対応する作成フォーム・リソース上でGET
メソッドをコールします。
http://localhost:7001/management/weblogic/latest/edit/serverCreateForm
および
http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicatorCreateForm
基礎となるWLS Beanは、多くのプロパティのデフォルト値を持っています。通常はこれらのデフォルト値を表示、場合によりカスタマイズし、新しいWLS Beanを作成するために使用します。対応する作成フォーム・リソース上でGET
をコールすることによって、これらのデフォルト値を取得できます。例:
curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm HTTP/1.1 200 OK { listenPort: 7001, ... } }
WLS構成Beanを作成するには、新しいBeanのプロパティを含んでいるJSONオブジェクト上でPOST
をコールします。
JSONオブジェクトは、可能なプロパティをすべて含んでいる必要はありません。未指定のプロパティはデフォルト値に設定されます。コレクションである子は、すべてコレクション内で一意のアイデンティティを割り当てられる必要があり、たとえば、サーバーは一意の名を必要とします。このため、identity
プロパティは、オプションではありません。
レスポンスは、リソースのURLを含んでいるlocation
ヘッダーを含みます。例:
curl ... -d "{ name: "Server-1", defaultProtocol: "t3s" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 201 Created Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1 curl -X GET http://localhost:7001/management/weblogic/latest/edit/servers/id/Server-1 HTTP/1.1 200 OK { item: { identity: [ "domain", "servers", "Server-1" ], name: "Server-1", defaultProtocol: "t3s", // specified by the caller listenAddress: 7001 // not specified by the caller, therefore set to its default value } }
その名前を持つBeanがすでに存在する場合、リソースは障害メッセージに加えてBAD_REQUEST
ステータス・コードを戻します。例:
curl ... -d "{ name: "Server-1" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers 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 }
WLS構成Beanの更新と同様に、有効な値と無効な値を混合して渡すことができます。Beanがサポートしない読取り専用プロパティおよびプロパティは、無視されます。プロパティの設定で例外があった場合、リソースはレスポンスに障害メッセージを追加します。すべてのプロパティを処理した後でなんらかのエラーが発生した場合、リソースは新しいBeanを削除し、BAD_REQUEST
ステータス・コードを戻そうとします。
例3-1 有効なプロパティと無効なプロパティの混合の例
curl ... -d "{ name: "Server-1", listenPort: abc, defaultProtocol: "no-such-protocol", adminstrationProtocol: "iiop" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers 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" } ] }
例3-2 すべての有効プロパティ
curl ... -d "{ name: "Server-1", listenPort: 7003, defaultProtocol: "https", adminstrationProtocol: "iiop" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 201 Created Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1
MBeanプロパティは、設定されているか未設定かのどちらかです。設定されている場合、値は永続化され(たとえば、config.xml
に)、ロックされています。未設定の場合は、デフォルト値が使用されます。値は、プロパティのタイプのデフォルト値、ハードコードされたデフォルト値または一部のカスタムJavaコードを実行する、計算されたデフォルト値のいずれかです。
デフォルトでは、リソース上でGET
をコールすると、プロパティの現在の値を戻します。String
プロパティの値をnullまたは空の文字列に設定すると、プロパティが設定解除されます(デフォルト値に戻ります)。
RESTでは、プロパティが設定されているかどうかを判断し、プロパティを明示的に設定するか、設定解除します。
リソース取得時にexpandedValues
問合せパラメータをtrue
に設定すると、各々の値は、set
ブール値プロパティと、現在の値を保持するvalue
プロパティを持つJSONオブジェクトとして戻されます。たとえば、サーバーを取得すると、次が戻されます。
curl ... -X GET \ http://localhost:7001/management/weblogic/latest/edit/servers/myserver?&expandedValues=true { listenPortEnabled: { set: false, value: true }, // currently not set name: { set: true, value: "myserver" }, // currently set listenPort: { set: true, value: 7003 } // currently set }
同様に、expandedValues
問合せパラメータを使用して、値を明示的に設定または設定解除できます。たとえば、リスニング・ポートを設定解除して、リスニング・アドレスを空の文字列に設定する手順は、次のとおりです:
curl ... -d "{ listenPort: { set: false }, // value will be ignored if specified listenAddress: { set: true, value: "" } }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/myserver?expandedValues=true
各WLS Bean操作は、それ自身のREST URLにマップされます。オーバーロードされた操作の場合(たとえば、shutdown()
に対するshutdown(int、boolean)
)、すべてのオーバーロードされた操作が同じURLにマップされ、リソースは、着信する引数を参照して、呼び出す操作を決定します。
操作が入力引数を必要とする場合、各引数のプロパティとともにJSONオブジェクト・リクエスト・ボディを渡すことによって指定します。プロパティの名前は、引数の名前に一致します。
操作が入力引数をとらない場合、JSONオブジェクトをプロパティなしで渡す必要があります。
同様に、操作が値を戻す場合、標準RESTレスポンス・ボディのJSONオブジェクトreturn
プロパティで戻されます。操作がvoidである場合、レスポンス・ボディはreturn
プロパティを含みません。
基礎となるMBean操作が例外を送出した場合、RESTメソッドは、例外のテキストを含むBAD REQUEST
(404
)レスポンスを戻します。
例3-3 引数のないvoid操作: void shutdown()
curl ... -d "{}" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown { // response does not include a 'return' property since it's a void operation }
例3-4 複数の引数を持つvoid操作: void shutdown(int timeout, boolean ignoreSessions)
curl ... -d "{ timeout: 500, ignoreSessions: false }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown { // response does not include a 'return' property since it's a void operation }
例3-5 1つの引数を持つ非void操作: String getURL(String protocol)
curl ... -d "{ protocol: 'http' }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/getURL { return: "http://localhost:7003" }
REST APIには強力な一括アクセス機能があり、1つのcallで戻せるBeanのツリーを動的に記述できます。
各ツリー(たとえば、編集、ドメイン・ランタイムなど)は、ルートsearch
リソースを持っています。これらのsearch
リソースへの問合せをPOST
できます。問合せは、どのBean(およびプロパティとリンク)を戻すかを示し、示されたとおりに、Beanツリーの一部(「スライス」)を戻します。
一括アクセスは読取りにのみ使用できます。書込みには使用できません。
各Beanツリーには、一括問合せ用のsearch
リソースが含まれます。
「管理サーバー」で、次の手順を実行します。
URL | 説明 |
---|---|
|
編集Beanツリー(まだディスクに保存されていない進行中の編集)のスライスを戻します。 |
|
ディスクに保存された最後の構成Beanツリーのスライスを戻します(サーバーが現在使用している構成でなく)。 |
|
管理サーバーのドメイン・ランタイムBeanツリー(すべてのサーバーのランタイムBeanツリーを含む)のスライスを戻します。 |
|
管理サーバーの構成Beanツリー(管理サーバーの実行対象である構成)のスライスを戻します。 |
|
管理サーバーのランタイムBeanツリーのスライスを戻します。 |
管理対象サーバー上で:
URL | 説明 |
---|---|
|
管理対象サーバーの構成Beanツリー(サーバーの実行対象である構成)のスライスを戻します。 |
|
管理対象サーバーのランタイムBeanツリーのスライスを戻します。 |
問合せをPOST
してリソースを検索すると、問合せはツリーのルートBeanで検索を開始します。リソースは、問合せの結果(Beanツリーのその「スライス」)を含むJSONレスポンスを戻します。
オブジェクト問合せは、次のように、WLS Bean(あるいは、Beanのコレクション)に対して、どのデータが戻されるべきかを記述しています。
Beanのプロパティのうち、どれを戻すか。
Beanのリンクのうち、どれを戻すか。
Beanの子のうち、どれを戻すか。
コレクションの場合、その子のうちどれを戻すか。
検索はすべて、search
リソースのツリーのルートBeanで検索を開始する点に注意してください。たとえば、management/weblogic/latest/domainRuntime/search
に問合せをPOST
すると、ドメイン・ランタイム・ツリーのDomainRuntimeMBean
で検索を開始します。
fields
は、どのBeanプロパティ(たとえば、スカラーと参照)を戻すかを指定します。これは、プロパティ名のJSON文字列配列です。たとえば、ドメインのname
およびconfigurationVersion
を戻す手順は、次のとおりです:
curl ... -d "{ fields: [ 'name', 'configurationVersion' ] }" \ -X POST http://localhost:7001/management/weblogic/latest/edit/search
Beanがサポートしていないプロパティを問合せがリストした場合、問合せのその部分は無視されます(エラーを戻しません)。fields
が指定されていない場合、すべてのプロパティが戻されます。
excludeFields
は、戻さないフィールドのリストを指定します。他のプロパティはすべて戻されます。fields
とexcludeFields
は、排他的です。
問合せのfields
およびexcludeFields
プロパティは、リソース上でGET
をコールする場合に指定できるfields
およびexcludeFields
問合せパラメータを反映している点に注意してください。違いは、問合せパラメータがカンマで区切られた名前を使用し、問合せが名前のJSON配列を使用する点です。
links
は、Beanのリンクのうち、どれを戻すかを指定します。これは、リンクrel
名のJSON文字列配列です。たとえば、ドメインのself
およびservers
リンクを戻す手順は、次のとおりです:
curl ... -d "{ links: [ 'self', 'servers' ] }" \ -X POST http://localhost:7001/management/weblogic/latest/edit/search
Beanがサポートしていないリンクを問合せがリストした場合、問合せのその部分は無視されます(エラーを戻しません)。
links
が指定されていない場合、すべてのリンクが戻されます(デフォルトでself
およびcanonical
リンクのみを戻すコレクションの子を除く)。
同様に、excludeLinks
は、戻さないリンクのリストを指定します。他のリンクはすべて戻されます。links
とexcludeLinks
は、排他的です。
コレクションの子のリンクをすべて戻すには、excludeLinks
: []
を使用します。
問合せのlinks
およびexcludeLinks
プロパティは、リソース上でGET
をコールする場合に指定できるlinks
およびexcludeLinks
問合せパラメータを反映している点に注意してください。
children
は、どの子Beanプロパティを戻すかを指定します。これは、プロパティ名が戻す子の名前であり、値がオブジェクト問合せであるJSONオブジェクトです。たとえば、各サーバーの名前およびリスニング・ポートとともにドメインの名前を取得する手順は、次のとおりです:
curl ... -d "{ fields: [ 'name' ], // only return the domain's name children: { servers: { // fetch the domain's 'servers' collection fields: [ 'name', 'listenPort' ] // only return each server's name and listen port } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search
children
が指定されていない場合、Beanの子はどれも戻されません。
場合により、コレクション内の特定のアイテム(たとえば、myserver
およびServer-0
)のみを戻さなければならないことがあります。それぞれのコレクションの子は、そのアイデンティティを指定するプロパティを持っています。通常、これはname
プロパティです。問合せは、このプロパティ名を使用して、コレクションのどの子を戻すかを指定します。これはアイデンティティのJSON文字列配列です。fields
およびlinks
は、これらの子それぞれに対して、どのプロパティとリンクを戻すかを制御するために使用することもできます。たとえば、サーバーServer-0
およびServer-1
の名前とリスニング・ポートを戻す手順は、次のとおりです:
curl ... -d "{ fields: [ 'name' ], // only return the domain's name children: { servers: { // fetch the domain's 'servers' collection names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1' fields: [ 'name', 'listenPort' ] // only return each server's name and listen port } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search
存在しないアイデンティティは無視されます(エラーを戻しません)。同様に、コンテキストがコレクションでない場合、問合せのこの部分は無視されます。デフォルトで、コレクションの子はすべて戻されます。
レスポンス・ボディは通常のパターン(URLがBeanとコレクションのどちらに対するものかに応じて、インライン・プロパティまたはitems
)に従います。子Beanは、ネストされたプロパティとして戻されます。例:
curl ... -d "{ fields: [], // don't return any domain level properties links: [], // don't return any domain level links children: { servers: { // fetch the domain's 'servers' collection names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1' fields: [ 'name' ], // only return each server's name links: [], // don't return any per-server links children: { SSL: { fields: [ 'listenPort' ], // only return each server's SSL listen port links: [] // don't return any SSL level links } } } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search {code:JavaScript} HTTP/1.1 200 OK { servers: { items: [ { name: "myserver", SSL: { listenPort: 7002} }, { name: "AnotherServer", SSL: { listenPort: 7002} } ] } }
この例は、実行中のすべてのサーバー上で、特定のアプリケーションのコンポーネント・ランタイムを取得します。サーバー・ランタイムとアプリケーション・ランタイムでは親の名前のみ、コンポーネント・ランタイムではすべてのプロパティを戻します。
curl ... -d "{ fields: [], links: [], // don't return any domain runtime level properties or links children: { serverRuntimes: { fields: [ 'name' ], links: [], // return each server's name. don't return any server level links children: { applicationRuntimes: { name: [ 'myapp', 'BasicApp' ], // only return apps 'myapp' and 'BasicApp' fields: [ 'name' ], links: [], // return each app's name but no per-app links children: { componentRuntimes: { links: [] } // return all component runtime properties, but no links } } } } } }" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search
この例は、すべての実行中サーバーにわたって、一群のアプリケーションのサーブレット・ランタイムとEJBランタイムの情報をすべて取得します。
curl ... -d "{ links: [], fields: [], children: { serverRuntimes: { links: [], fields: [ 'name', 'state' ], children: { applicationRuntimes: { name: [ 'myapp', 'BasicApp' ], links: [], fields: [ 'name', 'healthState' ], children: { componentRuntimes: { links: [], fields:[ 'name', 'healthState', 'contextRoot', 'openSessionsCurrentCount', 'sessionsOpenedTotalCount' ], children: { EJBRuntimes: { links: [], fields: [ 'EJBName', 'type' ], children: { transactionRuntime: { links: [], fields: [ 'transactionsCommittedTotalCount', 'transactionsRolledBackTotalCount', 'transactionsTimedOutTotalCount' ] }, poolRuntime: { links: [], fields: [ 'accessTotalCount', 'missTotalCount', 'destroyedTotalCount', 'pooledBeansCurrentCount', 'beansInUseCurrentCount', 'waiterCurrentCount', 'timeoutTotalCount' ] }, cacheRuntime: { links: [], fields: [ 'cachedBeansCurrentCount', 'cacheAccessCount', 'cacheMissCount', 'activationCount', 'passivationCount' ] }, lockingRuntime: { links: [], fields: [ 'lockEntriesCurrentCount', 'lockManagerAccessCount', 'waiterTotalCount', 'waiterCurrentCount', 'timeoutTotalCount' ] }, timerRuntime: { links: [], fields: [ 'timeoutCount', 'cancelledTimerCount', 'activeTimerCount', 'disabledTimerCount' ] } } }, servlets: { links: [], fields: [ 'servletName', 'contextPath', 'reloadTotalCount', 'invocationTotalCount', 'executionTimeTotal', 'executionTimeHigh', 'executionTimeLow' ] } } } } } } } } }" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search
1つ以上のサーバーに統合されるdomainRuntimeツリー内でGETリクエストまたはPOSTコールを作成する場合、requestMaxWaitMillis
問合せパラメータを指定して、各サーバーからのレスポンスを待機する最大時間を設定できます。指定されない場合、ドメインに構成された管理者の値であるRestfulManagementServicesMBeanのDelegatedRequestMaxWaitMillis
値が使用されます。
十分な速さでレスポンスしないサーバーでは、レスポンス・ボディにサーバーごとの不正なHTTPステータス・コードが含まれます。
次のサンプルを確認してください。
# GET all the server runtimes' names, give up on a server if it doesn't respond within 10 milliseconds: curl -v \ --user admin:admin123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -X GET http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/serverRuntimes?links=none\&fields=name\&requestMaxWaitMillis=10 < HTTP/1.1 200 OK {"items": [ { "httpStatus": 504, "name": "Cluster1Server1", "identity": [] }, {"name": "AdminServer"}, { "httpStatus": 504, "name": "Cluster1Server2", "identity": [] } ]} # GET all the server runtimes' application's names, give up on a server if it doesn't respond within 50 milliseconds: curl -v \ --user admin:admin123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -X POST http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/search?requestMaxWaitMillis=50 \ -d "{ links: [], fields: ['name'], children: { serverRuntimes: { links: [], fields: ['name'], children: { applicationRuntimes: { links: [], fields: ['name'] } } } } }" < HTTP/1.1 200 OK { "name": "bean-ex", "serverRuntimes": {"items": [ { "httpStatus": 504, "name": "Cluster1Server1", "identity": [] }, { "name": "AdminServer", "applicationRuntimes": {"items": [ {"name": "bea_wls_management_internal2"}, {"name": "jms-internal-xa-adp"}, {"name": "mejb"}, {"name": "jms-internal-notran-adp"}, {"name": "bea_wls_internal"}, {"name": "wls-management-services"}, {"name": "bea_wls_deployment_internal"} ]} }, { "httpStatus": 504, "name": "Cluster1Server2", "identity": [] } ]} }
指定された基準に基づいたドメインにある複数のサーバーにまたがるRESTリソースのdomainRuntime検索結果を統合できます。たとえば、すべての実行中のサーバーの最大openSocketsCurrentCount
を取り出せます。
他の検索と同様に、戻されるBeanツリーのスライスをリクエスト・ボディを使用して指定します。この機能を有効化するには、追加のフィールドを指定して、結果がサーバー全体で統合されることおよびどのようにそれぞれのプロパティが統合されるかを示します。
次の統合検索のサンプルの構文を確認します。
---------------------------------------------------------------------- Get the total number of open sessions across each application's component runtimes across all servers ---------------------------------------------------------------------- curl -v \ --user monitor:monitor123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -d "{ links: [], fields: [], children: { serverRuntimes: { mergeCollection: true, children: { applicationRuntimes: { mergeOn: 'name', fields: [ { name: 'name', sameValue: true } ], children: { componentRuntimes: { mergeCollection: true, fields: [ { name: 'openSessionsCurrentCount', total: true } ] } } } } } } }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search HTTP/1.1 200 OK Response Body: {"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [ { "name": "JDBCDataSource1", "componentRuntimes": {"items": [{}]} }, { "name": "bea_wls_deployment_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 3 }}]} }, { "name": "wls-management-services", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 202, "count": 3 }}]} }, { "name": "bea_wls_cluster_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "jms-internal-xa-adp", "componentRuntimes": {"items": [{}]} }, { "name": "fairShare", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "bea_wls_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 3 }}]} }, { "name": "JMSSystemResource1", "componentRuntimes": {"items": [{}]} }, { "name": "basicapp", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "jms-internal-notran-adp", "componentRuntimes": {"items": [{}]} }, { "name": "bea_wls_management_internal2", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 1 }}]} }, { "name": "mejb", "componentRuntimes": {"items": [{}]} } ]}}]}} ---------------------------------------------------------------------- Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers ---------------------------------------------------------------------- curl -v \ --user monitor:monitor123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -d "{ links: [], fields: [], children: { serverRuntimes: { mergeCollection: true, children: { applicationRuntimes: { name: [ 'fairShare', 'wls-management-services' ], mergeOn: 'name', fields: [ { name: 'name', sameValue: true } ], children: { componentRuntimes: { mergeOn: 'moduleId', fields: [ { name: 'contextRoot', sameValue: true } ], children: { servlets: { mergeCollection: true, fields: [ { name: 'invocationTotalCount', total: true } ] } } } } } } } } }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search HTTP/1.1 200 OK Response Body: {"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [ { "name": "fairShare", "componentRuntimes": {"items": [{ "contextRoot": "\/fairShare", "servlets": {"items": [{"invocationTotalCount": { "total": 0, "count": 8 }}]} }]} }, { "name": "wls-management-services", "componentRuntimes": {"items": [{ "contextRoot": "\/management", "servlets": {"items": [{"invocationTotalCount": { "total": 202, "count": 9 }}]} }]} } ]}}]}}
最初のサンプル、"Get the total number of open sessions across each application's component runtimes across all servers"では、各アプリケーションのコンポーネントをすべてのサーバー全体でマージしながら、各アプリケーションを別々に維持します(アプリケーションのname
に基づく)。
これは、次のように指定して実現されます。
serverRuntimes - mergeCollection: true applicationRuntimes - mergeOn: 'name' componentRuntimes - mergeCollection: true
たとえば、次のようなBeanツリーがあるとします。
server1 app1 : comp1, comp2 app2 : comp3, comp4 app3 : comp5, comp6 server2 app1 : comp1, comp2 app2 : comp3, comp4 app3 : comp5, comp6
次のレスポンスが返されます。
app1 comp merged values from server1.app1.comp1, server1.app1.comp2, server2.app1.comp1, server2.app1.comp2 app2 comp merged values from server1.app2.comp3, server1.app2.comp4, server2.app2.comp3, server2.app2.comp4 app3 comp merged values from server1.app3.comp5, server1.app3.comp6, server2.app3.comp5, server2.app3.comp6
2番目のサンプル、"Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers"では、各アプリケーションのコンポーネントのサーブレットをすべてのサーバー全体でマージしながら、各アプリケーションを別々に維持し(アプリケーションのname
に基づく)、各アプリケーションのコンポーネントを別々に維持し(コンポーネントのmoduleId
モジュールに基づく)ます。これは、app1
およびapp2
(すべてのアプリケーションを使用せず)に対してだけ結果を返すようにも指定します。
これは、次のように指定して実現されます。
serverRuntimes - mergeCollection: true applicationRuntimes - mergeOn: 'name', name: [ 'app1', 'app2' ] componentRuntimes - mergeOn: 'moduleId' servlets - mergeCollection: true
たとえば、次のようなBeanツリーがあるとします。
server1 app1 comp1 : servlet1, servlet2 comp2 : servlet3, servlet4 app2 comp3 : servlet5, servlet6 comp4 : servlet7, servlet8 app3 comp5 : servlet9, servlet10 comp6 : servlet11, servlet12 server2 app1 comp1 : servlet1, servlet2 comp2 : servlet3, servlet4 app2 comp3 : servlet5, servlet6 comp4 : servlet7, servlet8 app3 comp5 : servlet9, servlet10 comp6 : servlet11, servlet12
レスポンスは次を返します(app3
は返らないことに注意)。
app1 comp1 merged values from server1.app1.comp1.servlet1, server1.app1.comp1.servlet2, server2.app1.comp1.servlet1, server2.app1.comp1.servlet2 comp2 merged values from server1.app1.comp2.servlet3, server1.app1.comp2.servlet4, server2.app1.comp2.servlet3, server2.app1.comp2.servlet4 app2 comp3 merged values from server1.app2.comp3.servlet5, server1.app2.comp3.servlet6, server2.app2.comp3.servlet5, server2.app2.comp3.servlet6 comp4 merged values from server1.app2.comp4.servlet7, server1.app2.comp4.servlet8, server2.app2.comp4.servlet7, server2.app2.copm4.servlet8
ドメインおよびパーティションの検索結果の統合の例は、「ドメイン・レベルのREST API例」および「パーティション固有のREST API例」を参照してください。
リクエスト・ボディ・マージ関連フィールド
フィールド | 説明 |
---|---|
|
MBeanのコレクション(およびサブMBeanのツリー)を単一の統合されたMBeanツリー(およびサブMBeanツリー)にマージすることを示します。値はブールです。 |
|
マージされたコレクションの子MBeanをいつ一緒にマージするかを示します(たとえば、server1のapp1はserver2のapp1と一緒にマージします)。値は文字列で、プロパティを指定します。
|
|
どのMBeanのプロパティを返すかを指定します。 fields: [ { name: 'openSessionCurrentCount', total: true, min:true, max:true }, { name: 'type', sameValue: true } ] 複数のマージ・ルールを同一のプロパティに指定できます(たとえば、min、maxおよびtotalを返します)。プロパティにマージ・ルールが指定されない場合、BAD REQUESTを戻します。後述のプロパティごとのマージ・ルールの表を参照してください。 |
|
非統合検索を実行する場合、どのプロパティを返さないかを指定します(たとえば、返すものではなく返さないもののリストなど)。統合検索を実行する場合、これはサポートされません。存在する場合、BAD REQUESTを戻します。 |
|
|
プロパティごとのマージ・ルール
次の表にプロパティごとのマージ・ルールを示します。
フィールド | 説明 |
---|---|
|
マージするプロパティの名前を含みます。これは必須の文字列フィールドです。指定されていない場合、BAD REQUESTを戻します。 |
|
REST APIにより数字ではない値(または数字に変換可能な文字列)が検出された場合、BAD REQUESTを戻します。 |
|
いくつかのプロパティ値は、コンポーネントのタイプおよびmoduleIdのように、マージした各MBeanで同一である必要があります。 REST APIによりマージ中に異なる値が検出された場合、BAD REQUESTを戻します。同様に、プロパティ値が文字列ではない場合、BAD REQUESTを戻します。 |
|
プロパティ値の合リストを返すことを示します。順序付けは行われません。フィールドはオプションのブール・フィールドで、デフォルトはfalseに設定されます。MBeanプロパティの任意のタイプで使用できます。 |
いくつかのMBean操作(たとえば、サーバー・ライフ・サイクルやデプロイメント)は、非同期です。ジョブがいつ完了したかを決定するために監視する必要があるジョブMBeanを戻します。
操作が完了したか、すぐに失敗した場合、非同期MBean操作は200 OK
、201 Created
または400 Bad Request
を戻します。それ以外の場合は202 Accepted
が戻され、作業がいつ完了したかを検出するには、戻されたジョブ・リソースをポーリングする必要があります。RESTはデフォルトで、ベスト・エフォート型試行を行って作業の完了を待機しますが、およそ5分後に戻します。Prefer
ヘッダーを指定して、RESTが作業の完了をどのくらい待機するかを制御できます。
表3-1は、Prefer
ヘッダーの使用を説明しています。
表3-1 Preferヘッダーの使用
ヘッダー | 説明 |
---|---|
|
クライアントは、戻されたジョブ・リソースをポーリングします。非同期MBean操作がすぐに完了した場合、RESTは |
たとえば、 |
RESTリソースは、最大で指定された秒数までジョブを内部的にポーリングして、非同期MBean操作がその間に完了したら、 |
Prefer
ヘッダーを指定しない場合、非同期MBean操作がおよそ5分以内に完了したら、RESTは200 OK
、201 Created
または400 Bad Request
を戻し、それ以外の場合は202 Accepted
を戻します。
respond-async
とwait
の両方を指定すると、respond-async
は無視されます。
同期および非同期操作の例は、「ドメイン・レベルのREST API例」および「パーティション固有のREST API例」を参照してください。
デプロイされたアプリケーションとライブラリは編集ツリーに表示されます。それらをデプロイするにはコレクション上でPOST
を、アンデプロイするにはDELETE
をコールします。
同様に、デプロイメントMBeanは、サーバー相対パス名をとります。さらに、クライアントからサーバーにファイルをアップロードしてからそれをデプロイし、作成フォーム・リソースを使用してデプロイメントを調査(たとえば、優先名とバージョン番号を決定するために)できます。ドメイン指定およびパーティション指定のアプリケーションのデプロイの例は、「ドメイン・レベルのREST API例」および「パーティション固有のREST API例」を参照してください。