WLS RESTful管理インタフェースの使用

3 WLS RESTful管理インタフェースの使用

Oracle WebLogic ServerでサポートされているRESTful管理サービスの使用方法について学習します。WLS REST APIを使用して一般的なドメイン管理および監視タスクを実行する方法を示すスクリプトの例については、「ドメイン・レベルのREST APIの例」を参照してください。

この章の内容は次のとおりです。

RESTリソースへのアクセス
各RESTリソース・メソッドは、それにアクセスできるユーザー・ロール(管理者、デプロイヤ、オペレータ、モニター)を定めています。
WLS Beanの表示
WLS Beanを表示するには、対応するREST URLでHTTP GETメソッドを呼び出します。
包含Beanのコレクションの表示
WLS Beanのコレクションを表示するには、対応するREST URLでHTTP GETメソッドを呼び出します。
作成フォームの取得
新しいリソースを作成するために作成フォームを取得するには、対応する作成フォームREST URL上でHTTP GETメソッドを呼び出します。
結果のフィルタリング
Bean、コレクション、作成フォーム・リソースGETメソッドは、これらの問合せパラメータをサポートしているため、レスポンスからプロパティとリンクを省略できます。
WLS構成の変更
Beanを作成、変更、削除できるのは、編集ツリー内(.../management/weblogic/<version>/edit/...)のみです。他のBeanツリーは読取り専用です。
複数の編集セッションの使用
以前のリリースでは、WebLogic Serverは複数の編集セッション、指定された並行編集セッションを導入しました。これにより、複数の管理者が同時に構成を変更できるようになります。これらの編集セッションは、ドメイン・スコープ指定されています。各スコープは、デフォルトの編集セッションを持っています。編集セッション名は、スコープ内で一意ですが、複数のスコープにはおよびません。
WLS構成Beanの作成
新しいBeanのプロパティを含んでいるJSON構造とともにPOSTをコールして、新しいWLS構成Beanを作成します。
プロパティ設定の有無の管理
MBeanプロパティは、設定されているか未設定かのどちらかです。設定されている場合、値は永続化され(たとえば、config.xmlに)、ロックされています。未設定の場合は、デフォルト値が使用されます。
操作の呼出し
各WLS Bean操作は、それ自身のREST URLにマップされます。オーバーロードされた操作の場合(たとえば、shutdown()に対するshutdown(int、boolean))、すべてのオーバーロードされた操作が同じURLにマップされ、リソースは、着信する引数を参照して、呼び出す操作を決定します。
問合せの使用
REST APIには強力な一括アクセス機能があり、1つのcallで戻せるBeanのツリーを動的に記述できます。
同期操作と非同期操作について
いくつかのMBean操作(たとえば、サーバー・ライフ・サイクルやデプロイメント)は、非同期です。ジョブがいつ完了したかを決定するために監視する必要があるジョブMBeanを戻します。
アプリケーションとライブラリのデプロイ
デプロイされたアプリケーションとライブラリは編集ツリーに表示されます。それらをデプロイするにはコレクション上でPOSTを、アンデプロイするにはDELETEをコールします。
WebLogic Server REST APIのCross-Origin Resource Sharing (CORS)
14.1.1.0.0以降、Oracle WebLogic ServerのRESTful管理サービスでは、クライアント側のCross-Origin Resource Sharing (CORS)をサポートしています。

RESTリソースへのアクセス

各RESTリソース・メソッドは、それにアクセスできるユーザー・ロール(管理者、デプロイヤ、オペレータ、モニター)を定めています。

一般的には、次のとおりです。

リソースを読み取るには(GETメソッドを使用)、管理者、デプロイヤ、オペレータまたはモニター・ロールである必要があります。
リソースを作成するか(POSTおよびDELETEメソッドを使用)、操作を呼び出す(POSTを使用)には、管理者ロールである必要があります。
ただし、一部のリソースでは、デプロイヤがアプリケーションとライブラリをデプロイおよびアンデプロイでき、オペレータがサーバーを起動できます。

ドメイン・ユーザー(たとえば、ドメインのデフォルト・セキュリティ・レルムで定義されているユーザー)の場合、RESTリソースにアクセスするURLはhttp://host:port/managementで始まります。

親トピック: WLS RESTful管理インタフェースの使用

WLS Beanの表示

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配列を戻します。

親トピック: WLS RESTful管理インタフェースの使用

WLS Beanプロパティについて

戻されたJSONオブジェクトは、標準のJavaからJSONへのマッピング(「JSONマッピング」を参照)を使用するWLS Beanのプロパティを含みます(たとえば、通常のプロパティと参照を含み、子を含まない)。また、Beanのアイデンティティを指定するidentityプロパティも含みます。たとえば:

{
  identity: [ "domain", "servers", "Server-0" ],
  name: 'Server-0',
  listenPort: 7001,
  machine: { identity: [ "domain", "machines", "Machine-0" ] }
}

親トピック: WLS Beanの表示

セルフ・リンクと正規のリンク

リソースはすべて、リソースを参照する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などです。

親トピック: WLS Beanの表示

親リンク

ルート・リソースを除いて、リソースはすべて、親リソースへのトップ・レベル・リンクを含みます。リンクの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" }
  ]
}

親トピック: WLS Beanの表示

セルフ作成フォームのリンク

Beanが作成可能である場合は、オプションのシングルトン(たとえば、レルムのRDBMSSecurityStore)、Beanが現在存在しない場合は、対応する作成フォーム・リリースへのリンクも戻されます。リンクのrelプロパティは、createに設定されています。たとえば、セキュリティ・レルムの裁決プロバイダ上でGETをコールすると、次も戻されます。

{
  links: [
     {
       rel: "create",
       href: "http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myrealm/adjudicatorCreateForm"
     }
  ]
}

親トピック: WLS Beanの表示

子Beanリンク

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

親トピック: WLS Beanの表示

子作成フォームのリンク

作成フォーム・リソースへのリンクは、作成できる包含プロパティ(シングルトンとコレクション)に対して戻されます。リンクのrelプロパティは、<singularPropertyName>CreateFormに設定されています。たとえば、Server-0上でGETをコールすると、次も戻されます。

{
  links: [
     {
       rel: "networkAccessPointCreateForm",
       href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPointCreateForm"
     }
  ]
}

親トピック: WLS Beanの表示

シングルトンBean参照リンク

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の表示

Bean参照コレクション・リンク

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

親トピック: WLS Beanの表示

操作リンク

リソースは、操作リソースへのトップ・レベル・リンクも戻します。リンクの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の表示

包含Beanのコレクションの表示

WLS Beanのコレクションを表示するには、対応するREST URLでHTTP GETメソッドを呼び出します。

たとえば、すべてのサーバーの構成を取得する手順は、次のとおりです:

GET http://localhost:7001/management/weblogic/latest/edit/servers

GETは、標準WLS RESTレスポンス・ボディを戻します。itemsは子のプロパティを包含します。各アイテムは、その子のリソースにselfおよびcanonicalリンクを埋め込んでいます。

直下の子のみが戻されます。たとえば、サーバー・コレクションを取得する場合、各サーバーのプロパティは戻されますが、サーバーの子(SSLなど)は戻されません。

親トピック: WLS RESTful管理インタフェースの使用

コレクション・アイテムについて

リソースは、コレクションの各々の子に対してJSONオブジェクトを戻します。これらのオブジェクトは、子のリソース上でのGETのコールから戻されたアイテムと同じデータを含みます。たとえば、ドメインBeanのserversコレクションを取得すると、次が戻されます。

{
  items: [
    { name: "Server-1", listenPort: 7001, ... },
    { name: "Server-2", listenPort: 7003, ... }
  ]
}

親トピック: 包含Beanのコレクションの表示

コレクション・リンクについて

コレクション・リソースは、次のリンクを戻します。

自身への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" }
  ]
}

親トピック: 包含Beanのコレクションの表示

作成フォームの取得

新しいリソースを作成するために作成フォームを取得するには、対応する作成フォームREST URL上でHTTP GETメソッドを呼び出します。

たとえば、新しいサーバーを作成するための作成フォームを取得する手順は、次のとおりです:

GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm

GETは、標準WLS RESTレスポンス・ボディを戻します。作成フォームのプロパティとlinksプロパティを含んでいるJSONオブジェクト(関連リソースへのリンクを含むJSON配列)を戻します。

親トピック: WLS RESTful管理インタフェースの使用

作成フォーム・プロパティについて

戻された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
}

親トピック: WLS RESTful管理インタフェースの使用

WLS構成の変更

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 RESTful管理インタフェースの使用

WLS構成Beanの変更

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操作に類似しています。

親トピック: WLS構成の変更

JSONオブジェクト・リクエスト・ボディについて

変更する値を含む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構成の変更

複数の編集セッションの使用

以前のリリースでは、WebLogic Serverは複数の編集セッション、指定された並行編集セッションを導入しました。これにより、複数の管理者が同時に構成を変更できるようになります。これらの編集セッションは、ドメイン・スコープ指定されています。各スコープは、デフォルトの編集セッションを持っています。編集セッション名は、スコープ内で一意ですが、複数のスコープにはおよびません。

editツリーのすべてのRESTリソースに対して、使用する編集セッション(スコープの名前とそのスコープ内の編集セッションの名前)を指定する必要があります。

編集セッション・スコープ名は、URLから導出されます。ドメイン・スコープ指定されたREST URLを使用する場合、RESTはドメイン・レベル・スコープを使用します。そのスコープ内で、RESTは、使用する編集セッションを認識している必要があります。使用する編集セッションを正確に記述したヘッダーを指定することも、デフォルト・ルールを使用してRESTに選択させることもできます。

親トピック: WLS RESTful管理インタフェースの使用

クライアント指定の編集セッション

weblogic.edit.sessionヘッダーをリクエストに含めることによって、編集セッションを選択することができます。ヘッダーの値が編集セッション名として使用されます。たとえば:

curl ... -H weblogic.edit.session=MySession ...

各編集セッション・スコープは、defaultという名のデフォルト編集セッションを持っています。スコープのデフォルト編集セッションを明示的に選択するには:

curl ... -H weblogic.edit.session=default ...

親トピック: 複数の編集セッションの使用

デフォルトの編集セッション

weblogic.edit.sessionヘッダーを含めなかった場合、RESTリソースは次のルールを使用して編集セッションを選択します。

現在、スコープにロックされた1つの編集セッションがある場合、RESTはそれを使用します。
または、スコープに1つの編集セッションを作成している場合、RESTはそれを使用します。
それ以外の場合、RESTはスコープのデフォルト編集セッションを使用します。

親トピック: 複数の編集セッションの使用

WLS構成Beanの作成

新しいBeanのプロパティを含んでいるJSON構造とともにPOSTをコールして、新しいWLS構成Beanを作成します。

簡単にするために、対応する作成フォーム・リソースを使用して、様々な書込み可能プロパティのデフォルト値が移入されたテンプレートJSON構造を取得することができます。

親トピック: WLS RESTful管理インタフェースの使用

WLS構成Beanの作成のためのURL

コレクションの子を作成するには、コレクションのURLでPOSTをコールします。たとえば、http://localhost:7001/management/weblogic/latest/edit/serversです。

オプションのシングルトンの子を作成するには、提案された子のURLでPOSTをコールします。たとえば、http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicatorです。

作成フォームを取得するには、対応する作成フォーム・リソースでGETをコールします。たとえば:

http://localhost:7001/management/weblogic/latest/edit/serverCreateForm

および

http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicatorCreateForm

親トピック: WLS構成Beanの作成

JSONテンプレートの取得

基礎となる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の作成

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

親トピック: WLS構成Beanの作成

WLS構成Beanの削除

対応するWLS Bean(コレクションの子と、オプションのシングルトンである子)を削除するには、REST URL上でHTTP DELETE操作をします。そのBeanへの参照もすべて削除されます。たとえば、サーバーを削除する手順は、次のとおりです:

curl ... -X DELETE http://localhost:7001/management/weblogic/latest/edit/servers/Server-0

親トピック: WLS構成Beanの作成

プロパティ設定の有無の管理

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 RESTful管理インタフェースの使用

操作の呼出し

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

親トピック: WLS RESTful管理インタフェースの使用

問合せの使用

REST APIには強力な一括アクセス機能があり、1つのcallで戻せるBeanのツリーを動的に記述できます。

各ツリー(たとえば、編集、ドメイン・ランタイムなど)は、ルートsearchリソースを持っています。これらのsearchリソースへの問合せをPOSTできます。問合せは、どのBean(およびプロパティとリンク)を戻すかを示し、示されたとおりに、Beanツリーの一部(「スライス」)を戻します。

一括アクセスは読取りにのみ使用できます。書込みには使用できません。

親トピック: WLS RESTful管理インタフェースの使用

リソースの検索

各Beanツリーには、一括問合せ用のsearchリソースが含まれます。

「管理サーバー」で、次の手順を実行します。

URL	説明
`.../management/weblogic/latest/edit/search`	編集Beanツリー(まだディスクに保存されていない進行中の編集)のスライスを戻します。
`.../management/weblogic/latest/domainConfig/search`	ディスクに保存された最後の構成Beanツリーのスライスを戻します(サーバーが現在使用している構成でなく)。
`.../management/weblogic/latest/domainRuntime/search`	管理サーバーのドメイン・ランタイムBeanツリー(すべてのサーバーのランタイムBeanツリーを含む)のスライスを戻します。
`.../management/weblogic/latest/serverConfig/search`	管理サーバーの構成Beanツリー(管理サーバーの実行対象である構成)のスライスを戻します。
`.../management/weblogic/latest/serverRuntime/search`	管理サーバーのランタイムBeanツリーのスライスを戻します。

管理対象サーバー上で:

URL	説明
`.../management/weblogic/latest/serverConfig/search`	管理対象サーバーの構成Beanツリー(サーバーの実行対象である構成)のスライスを返します。
`.../management/weblogic/latest/serverRuntime/search`	管理対象サーバーのランタイムBeanツリーのスライスを戻します。

問合せをPOSTしてリソースを検索すると、問合せはツリーのルートBeanで検索を開始します。リソースは、問合せの結果(Beanツリーのその「スライス」)を含むJSONレスポンスを戻します。

親トピック: 問合せの使用

オブジェクト問合せ

オブジェクト問合せは、次のように、WLS Bean(あるいは、Beanのコレクション)に対して、どのデータが戻されるべきかを記述しています。

Beanのプロパティのうち、どれを戻すか。
Beanのリンクのうち、どれを戻すか。
Beanの子のうち、どれを戻すか。
コレクションの場合、その子のうちどれを戻すか。

検索はすべて、searchリソースのツリーのルートBeanで検索を開始する点に注意してください。たとえば、management/weblogic/latest/domainRuntime/searchに問合せをPOSTすると、ドメイン・ランタイム・ツリーのDomainRuntimeMBeanで検索を開始します。

親トピック: 問合せの使用

FieldsとExcludeFields

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とExcludeLinks

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の例」を参照してください。

表3-1に、リクエスト・ボディ・マージ関連検索フィールドを示します。なにも指定しない場合、検索結果は統合されません。

表3-1 リクエスト・ボディ・マージ関連のフィールド

フィールド	説明
`mergeCollection`	MBeanのコレクション(およびサブMBeanのツリー)を単一の統合されたMBeanツリー(およびサブMBeanツリー)にマージすることを示します。値はブールです。
`mergeOn`	マージされたコレクションの子MBeanをいつ一緒にマージするかを示します(たとえば、server1のapp1はserver2のapp1と一緒にマージします)。値は文字列で、プロパティを指定します。 `mergeOn`をマージしたコレクションのすべての子コレクションに指定する必要があります(`mergeCollection: true`を子コレクションに指定する場合は必要ありません)。同様に、マージしたコレクションが親ではないコレクションには指定しないでください。いずれかの条件が満たされない場合、`BAD REQUEST`を返します。
`fields`	どのMBeanのプロパティを返すかを指定します。`fields`にはプロパティごとのマージ・ルールのリストが含まれます。指定しない場合、プロパティは返されません。フィールドのリスト内の各エントリはJSONオブジェクトで、プロパティの名前およびそのマージ・ルールが含まれます。たとえば: fields: [ { name: 'openSessionCurrentCount', total: true, min:true, max:true }, { name: 'type', sameValue: true } ] 複数のマージ・ルールを同一のプロパティに指定できます(たとえば、min、maxおよびtotalを返します)。プロパティにマージ・ルールが指定されない場合、`BAD REQUEST`を返します。この項の表3-2を参照してください。
`excludeFields`	非統合検索を実行する場合、どのプロパティを返さないかを指定します(たとえば、返すものではなく返さないもののリストなど)。統合検索を実行する場合、これはサポートされません。存在する場合、`BAD REQUEST`を返します。
`links`	`linksexcludeLinks`は、非統合検索を実行する場合、RESTリソースに関連するどのリンクを返すかを指定します。統合検索を実行する場合、これらはサポートされません。いずれかが存在する場合、`BAD REQUEST`を返します。

表3-2 プロパティごとのマージ・ルール

フィールド	説明
`name`	マージするプロパティの名前を含みます。これは必須の文字列フィールドです。指定されていない場合、`BAD REQUEST`を返します。
`total` `min` `max`	`total`フィールドは、プロパティ値の合計および数を返すことを示します。同様に、`min`および`max`フィールドは、最少または最大のプロパティ値を返すことを示します。これらはオプションのブール・フィールドで、デフォルトはfalseに設定されます。 REST APIにより数字ではない値(または数字に変換可能な文字列)が検出された場合、`BAD REQUEST`を返します。
`sameValue`	いくつかのプロパティ値は、コンポーネントのタイプおよびmoduleIdのように、マージした各MBeanで同一である必要があります。`sameValue`フィールドは、マージしたMBeanに対して同一の値であることを示します。これはオプションのブール・フィールドで、デフォルトはfalseに設定されます。 REST APIによりマージ中に異なる値が検出された場合、`BAD REQUEST`を返します。同様に、プロパティ値が文字列ではない場合、`BAD REQUEST`を返します。
`values`	プロパティ値の合リストを返すことを示します。順序付けは行われません。フィールドはオプションのブール・フィールドで、デフォルトはfalseに設定されます。MBeanプロパティの任意のタイプで使用できます。

親トピック: 問合せの使用

同期操作と非同期操作について

いくつかのMBean操作(たとえば、サーバー・ライフ・サイクルやデプロイメント)は、非同期です。ジョブがいつ完了したかを決定するために監視する必要があるジョブMBeanを戻します。

操作が完了したか、すぐに失敗した場合、非同期MBean操作は200 OK、201 Createdまたは400 Bad Requestを戻します。それ以外の場合は202 Acceptedが戻され、作業がいつ完了したかを検出するには、戻されたジョブ・リソースをポーリングする必要があります。デフォルトでは、RESTは作業が完了するまで待機するよう最善を尽くしますが、5分ほど経過すると戻ります。Preferヘッダーを指定して、RESTが作業の完了をどのくらい待機するかを制御できます。

表3-3は、Preferヘッダーの使用を説明しています。

表3-3 Preferヘッダーの使用

ヘッダー説明

ヘッダー	説明
`-X Prefer:respond-async`	クライアントは、戻されたジョブ・リソースをポーリングします。非同期MBean操作がすぐに完了した場合、RESTは`200 OK`、`201 Created`または`400 Bad Request`を戻します。それ以外の場合は`202 Accepted`を戻します。
`-X Prefer:wait=#` たとえば、`-X Prefer:wait=10`	RESTリソースは、最大で指定された秒数までジョブを内部的にポーリングして、非同期のMBean操作がその間に完了したら、`200 OK`、`201 Created`または`400 Bad Request`を返します。それ以外の場合は、クライアントが(`GET`を介して)ポーリングして作業がいつ完了したかを検出できるRESTタスク・リソースのURLを含む`Location`ヘッダーとともに、`202 Accepted`を返します。

-X Prefer:respond-async

クライアントは、戻されたジョブ・リソースをポーリングします。非同期MBean操作がすぐに完了した場合、RESTは200 OK、201 Createdまたは400 Bad Requestを戻します。それ以外の場合は202 Acceptedを戻します。

-X Prefer:wait=#

たとえば、-X Prefer:wait=10

RESTリソースは、最大で指定された秒数までジョブを内部的にポーリングして、非同期のMBean操作がその間に完了したら、200 OK、201 Createdまたは400 Bad Requestを返します。それ以外の場合は、クライアントが(GETを介して)ポーリングして作業がいつ完了したかを検出できるRESTタスク・リソースのURLを含むLocationヘッダーとともに、202 Acceptedを返します。

Preferヘッダーを指定しない場合、非同期MBean操作が約5分以内に完了したら、RESTは200 OK、201 Createdまたは400 Bad Requestを返し、それ以外の場合は202 Acceptedを返します。

respond-asyncとwaitの両方を指定すると、respond-asyncは無視されます。

同期操作と非同期操作の例は、「ドメイン・レベルREST APIの例」を参照してください。

親トピック: WLS RESTful管理インタフェースの使用

アプリケーションとライブラリのデプロイ

デプロイされたアプリケーションとライブラリは編集ツリーに表示されます。それらをデプロイするにはコレクション上でPOSTを、アンデプロイするにはDELETEをコールします。

同様に、デプロイメントMBeanは、サーバー相対パス名をとります。さらに、クライアントからサーバーにファイルをアップロードしてからそれをデプロイし、作成フォーム・リソースを使用してデプロイメントを調査(たとえば、優先名とバージョン番号を決定するために)できます。ドメイン・スコープ指定のアプリケーションのデプロイの例は、「ドメイン・レベルREST APIの例」を参照してください。

親トピック: WLS RESTful管理インタフェースの使用

WebLogic Server REST APIのCross-Origin Resource Sharing (CORS)

14.1.1.0.0以降、Oracle WebLogic ServerのRESTful管理サービスでは、クライアント側のCross-Origin Resource Sharing (CORS)をサポートしています。

CORSは、追加のHTTPヘッダーを使用して、1つのドメインまたはオリジンで実行されているWebアプリケーションからリソースにアクセスしたり、別のドメインからデータを取得することによって、クロスドメイン・リクエストを可能にするセキュリティ・メカニズムです。Oracle WebLogic REST APIのRESTful管理サービス・エンドポイントには、CORSコントロールに使用する新しいヘッダーが含まれています。CORS HTTPヘッダーの値を構成して、Oracle WebLogic Server RESTエンドポイントに発行されたHTTPリクエストを処理できます。Oracle WebLogic Server RESTful編集管理インタフェースのこのRestful管理サービスの変更に関する項を参照してください。

表3-4に、HTTPリクエストの処理に使用できるCORS構成パラメータを示します:

表3-4 CORS構成パラメータ

CORSのパラメータ	説明
`CORSEnabled`	RESTful管理サービスWebアプリケーションでのCORS (Cross-Origin Resource Sharing)処理のサポートを有効にするかどうかを指定します。デフォルト値は`false`です。
`CORSAllowedOrigins`	CORSリクエストに許可されたオリジンのリストを指定します。指定する場合、HTTP `Origin`ヘッダーは、許可されるように構成された値のいずれかと完全に一致する必要があります。`Origin`ヘッダーと一致しない場合、ブラウザはリクエストを拒否します。リストが空であるか指定されていない場合に、CORSサポートが有効になっていると、すべてのオリジンがデフォルトで受け入れられます。 CORSのオリジン値には、プロトコル、ドメイン名があり、ポート番号も含まれる場合があります。
`CORSAllowedCredentials`	サーバーでCookieを使用した資格証明の使用を許可するかどうかを決定します。デフォルト値は`false`です。
`CORSAllowedHeaders`	CORSリクエストに許可されたHTTPヘッダー名のリストを指定します。デフォルト設定では、すべてのヘッダーが許可されます。
`CORSAllowedMethods`	CORSリクエストに許可されたHTTPメソッドのリストを指定します。デフォルト設定では、すべてのメソッドが許可されます。
`CORSExposedHeaders`	ブラウザに公開するHTTPヘッダー名のカンマ区切りリストを指定します。デフォルト設定では、特定のヘッダーは指定されません。
`CORSMaxAge`	CORS処理前リクエスト結果をキャッシュできる時間を秒単位で示します。デフォルト設定では、どの値も指定されません。

親トピック: WLS RESTful管理インタフェースの使用