| Oracle® Fusion Middleware RESTful管理サービスによるOracle WebLogic Serverの管理 12c (12.2.1) E70051-01 |
|
 前 |
 次 |
この章では、WebLogic ServerでサポートされているRESTful管理サービスを使用する方法について説明します。共通のドメインとパーティション管理と監視タスクを実行するためにWLS REST APIを使用する方法を示すサンプル・スクリプトは、「ドメイン・レベルのREST API例」と「パーティション固有のREST API例」を参照してください。
ここでのトピック
各RESTリソース・メソッドは、それにアクセスできるユーザー・ロール(管理者、デプロイヤ、オペレータ、モニター)を定めています。
一般的には、次のとおりです。
リソースを読み取るには(GETメソッドを使用)、管理者、デプロイヤ、オペレータまたはモニター・ロールである必要があります。
リソースを作成するか(POSTおよびDELETEメソッドを使用)、操作を呼び出す(POSTを使用)には、管理者ロールである必要があります。
ただし、一部のリソースでは、デプロイヤがアプリケーションとライブラリをデプロイおよびアンデプロイでき、オペレータがサーバーを起動できます。
ユーザーがドメイン・ユーザーである(たとえば、ドメインのデフォルト・セキュリティ・レルムで定義されている)場合、RESTリソースにアクセスするURLはhttp://host:port/managementで始まります。ユーザーがパーティション・ユーザーである(たとえば、そのパーティションのセキュリティ・レルムで定義されている)場合、RESTリソースにアクセスするURLはhttp://host:port/partition_name/managementで始まります。
WebLogic Server Multitenantでのユーザー・ロールの詳細は、『WebLogic Server MTの使用』の、構成および管理のための管理ロールに関する項を参照してください。
WLS Beanを表示するには、対応するREST URLでHTTP GETメソッドを呼び出します。たとえば、サーバーServer-0の構成を取得する手順は、次のとおりです:
GET http://localhost:7001/management/weblogic/latest/edit/latest/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 |
これらのrel名を持つリンクのみが戻されます。 |
excludeLinks |
これらのrel名を持つものを除くすべてのリンクが戻されます。 |
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編集リファレンスで、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 12.2.1では、複数の編集セッションが導入されました。(『WebLogic Server MTの使用』の、名前付同時編集セッションの管理に関する項を参照してください。)これらの編集セッションは、スコープが指定されています。スコープは、ドメイン・レベル編集セッションに対して1つ、パーティションに対して1つ存在します。各スコープは、デフォルトの編集セッションを持っています。編集セッション名は、スコープ内で一意ですが、複数のスコープにはおよびません。
editツリーのすべてのRESTリソースに対して、使用する編集セッション(スコープの名前とそのスコープ内の編集セッションの名前)を指定する必要があります。
編集セッション・スコープ名は、URLから導出されます。パーティション化されていないREST URLを使用する場合、RESTはドメイン・レベル・スコープを使用します。パーティション化されたREST URLを使用する場合、RESTはそのパーティションのスコープを使用します。
そのスコープ内で、RESTは、使用する編集セッションを認識している必要があります。使用する編集セッションを正確に記述したヘッダーを指定することも、デフォルト・ルールを使用してRESTに選択させることもできます。
新しい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"
}
]
}
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
}
REST APIには強力な一括アクセス機能があり、1つのcallで戻せるBeanのツリーを動的に記述できます。各ツリー(たとえば、編集、ドメイン・ランタイムなど)は、ルートsearchリソースを持っています。これらのsearchリソースへの問合せをPOSTできます。問合せは、どのBean(およびプロパティとリンク)を戻すかを示し、示されたとおりに、Beanツリーの一部(「スライス」)を戻します。
一括アクセスは読取りにのみ使用できます。書込みには使用できません。
各Beanツリーには、一括問合せ用のsearchリソースが含まれます。
「管理サーバー」で、次の手順を実行します。
| URL | 説明 |
|---|---|
.../management/edit/search |
編集Beanツリー(まだディスクに保存されていない進行中の編集)のスライスを戻します。 |
.../management/domainConfig/search |
ディスクに保存された最後の構成Beanツリーのスライスを戻します(サーバーが現在使用している構成でなく)。 |
.../management/domainRuntime/search |
管理サーバーのドメイン・ランタイムBeanツリー(すべてのサーバーのランタイムBeanツリーを含む)のスライスを戻します。 |
.../management/serverConfig/search |
管理サーバーの構成Beanツリー(管理サーバーの実行対象である構成)のスライスを戻します。 |
.../management/serverRuntime/search |
管理サーバーのランタイムBeanツリーのスライスを戻します。 |
管理対象サーバー上で:
| URL | 説明 |
|---|---|
.../management/serverConfig/search |
管理対象サーバーの構成Beanツリー(サーバーの実行対象である構成)のスライスを戻します。 |
.../management/serverRuntime/search |
管理対象サーバーのランタイムBeanツリーのスライスを戻します。 |
問合せをPOSTしてリソースを検索すると、問合せはツリーのルートBeanで検索を開始します。リソースは、問合せの結果(Beanツリーのその「スライス」)を含むJSONレスポンスを戻します。
オブジェクト問合せは、次のように、WLS Bean(あるいは、Beanのコレクション)に対して、どのデータが戻されるべきかを記述しています。
Beanのプロパティのうち、どれを戻すか。
Beanのリンクのうち、どれを戻すか。
Beanの子のうち、どれを戻すか。
コレクションの場合、その子のうちどれを戻すか。
検索はすべて、searchリソースのツリーのルートBeanで検索を開始する点に注意してください。たとえば、management/domain/runtimeに問合せを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
いくつかの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例」を参照してください。
