NEC Mark
WebOTX Manual V11.1 (第7版)

目次を表示

10. 運用管理REST アプリケーションの開発

10.1. はじめに

10.1.1. 運用管理RESTとは

運用管理RESTは、運用管理コマンド(otxadmin)や運用管理コンソール、統合運用管理ツールなどのJavaベースのクライアントを必要とせず、 HTTPリクエストを介して運用操作を行うことを目的としています。

本機能は大別して、管理チャネルと統計情報チャネルの2種類のURLを提供しており、どちらの場合もJSON (JavaScript Object Notation)形式にてサーバ 側よりデータが返却されます

また、管理チャネルでは設定値の参照・更新や運用操作を実行することが可能であり、設定更新に必要なパラメータや運用操作を実行する際に必要なパラメータ はリクエスト送信時にJSON形式でエンティティボディに指定する必要があります。なお、本機能は、管理ドメインに対する操作、及びアプリケーションの配 備操作を実行することはできません

10.1.2. 対象読者

HTTPリクエストを介して運用操作・監視業務を実施されたい方、または運用管理コンソール、統合運用管理ツールなどの機能を使用せずに独自の運用管理・監視業 務用の画面を構築されたい方が対象となります。

10.2. 設定

本機能は既定では機能が無効化されており、使用する場合、設定値を変更する必要があります

10.2.1. 設定方法

本機能を有効化する場合、有効化対象のドメインにログインした後、設定操作を行う必要があります。

10.2.1.1. コマンドでの設定方法
設定内容の確認・変更
機能の有効化

下記のコマンドを使用し、機能の有効化を行います。

otxadmin > enable-admin-rest

機能が有効化できているか否か、確認する場合は下記のコマンドを実行し、enabledと表示されることを確認してください。

otxadmin > get-admin-rest-status
enabled

これで設定は完了です。

10.2.1.2. 運用管理コンソールでの設定方法
設定内容の確認・変更
機能の有効化

[管理サービス] > [運用管理REST]の[操作]タブから、[有効化]を選択し、実行します。


機能の有効化

機能が有効化できているか否か、確認する場合[管理サービス] > [運用管理REST]の[操作]タブから、[状態表示]を選択し実行し、enabledと出 力されることを確認してください。

10.2.2. 動作確認

動作確認を行う場合、HTTPSリクエストが発行可能なHTTPクライアントを用意する必要があります。簡単な動作確認であればInternet ExplorerなどのWebブラウザ を使用し、以下のURL にアクセスすることで動作確認を行うことが可能です。

https://localhost:20101/adminrest/v1/config/

アクセス時に求められるユーザ情報は運用管理ユーザとなります。実行結果はWebブラウザの種別によって異なりますが、Internet Explorerの場合JSON形式のデータ が出力されます。

Caution

インストールした既定の状態で運用管理RESTの設定を行い、Webブラウザで該当URLにアクセスした場合、ブラウザにより"この Web サイトのセキュリティ証明書に は問題があります"などの証明書が適切でない旨が警告として表示されます。

これはWebOTXがサンプルとして自己署名証明書を登録しており、既定で運用管理RESTはその証明書を使用しているためです。このため、本番環境などで使用される場合は、 任意の機関の信頼できる証明書をサーバ側にインポートすることを推奨します。

10.3. ログ

本機能では、主に下記の場所を対象にログを出力します。ログの詳細については[WebOTXのログ]を確認してください。

ログファイル 出力内容
${INSTANCE_ROOT}/logs/agent_operationg 運用管理RESTを含む運用管理操作の詳細ログ。
${INSTANCE_ROOT}/logs/adminrest_access.log 運用管理RESTにアクセスした場合のアクセスログ。既定では無効。
${INSTANCE_ROOT}/logs/agent.log WebOTX ドメインのエージェントのJVMで出力される全てのメッセージを統合したログ。運用管理操作にて問題が発生した場合に確認する。
${INSTANCE_ROOT}/logs/server.log エージェントのJava VM上での標準出力および標準エラー出力。運用管理操作にて問題が発生した場合に確認する。

10.3.1. adminrest_access.logの有効化

デフォルトの状態では、運用管理RESTにアクセスした時のアクセスログは出力されません。アクセスログを出力したい場合は次の設定を行ってください。

  1. 運用管理コンソール、もしくは運用管理コマンドで次のツリーを表示するかコマンドを実行します
    運用管理コンソール：
    アプリケーションサーバ ＞ ログサービス ＞ モジュールログレベル ＞ [Web]タブ

    運用管理コマンド： 
    otxadmin> login -u admin -w adminamdin
otxadmin> get server.log-service.module-log-levels.adminrestaccess-log
  2. 任意のレベルに変更します
    運用管理コンソール：
    「AdminRest Access Log」のログレベルを希望のレベルに変更し「更新」ボタンを押下します

    運用管理コマンド： 
    otxadmin> login -u admin -w adminamdin
otxadmin> set server.log-service.module-log-levels.adminrestaccess-log={レベル}
  3. ドメインを起動します

ログは「${INSTANCE_ROOT}/logs/adminrest_access.log」に出力されます。

10.4. 提供するURLについて

本機能は運用管理操作を提供する管理チャネルと統計情報を監視するための統計情報チャネル、リクエストの実行形式を返却する WADL(Web Application Description Language)向けの各URLを提供します

10.4.1. 管理チャネル

管理チャネルは、運用管理操作を実行することを目的にしており、下記のURLにより提供するものです。

提供するHTTPメソッドGET,PUT,POSTの3種類となります。

https://localhost:20101/adminrest/v1/config/

10.4.1.1. URLの構成について

管理チャネルのURLは、ホスト名、ポート番号、管理チャネルのコンテキスト、参照先リソースであるDottedName名(CLIName)、及びその属性値、操作により構成されます。また、 パラメータとしてview、visibilityを提供します。以下ではURLで識別される、アクセス先情報(リソース)を提示しています。

管理チャネルで提供するリソース
URL 説明
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/?{パラメータ} 管理チャネル直下のアクセス可能なリソースを表示します。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName名}?{パラメータ} 指定したリソースが保持する操作・属性・子のリソースを表示します。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName名}/{属性名}?{パラメータ} 指定した属性の情報を表示します。また属性値を変更することができます。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName名}/{操作名}?{パラメータ}
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName名}/{操作名}({引数1の型},{引数2の型},...)?{パラメータ}		 指定した操作の情報を表示します。また操作を実施することができます。
同名で引数が異なる操作が存在する場合は、操作名の後ろに()で囲んだ引数の型のリストを付けることで、対象の操作を指定することができます。

なお、DottedName名はドット(.)をスラッシュに置き換えて実行する必要があります。例えば、server.java-config.max-heap-sizeの場合、max-heap-sizeが属性名となります。 このため、属性値の情報を取得する場合、下記のようなURLを構築する必要があります。

https://localhost:20101/adminrest/v1/config/server/java-config/max-heap-size

10.4.1.2. パラメータについて

URLを指定する場合、合わせてパラメータを指定することが可能です。パラメータとしては下記の値を指定することができます。

パラメータ
パラメータ 入力値 既定値 説明
view all,simple all 取得結果を詳細と概要の2パターンに分けて表示するを切り替えます。simpleを指定した場合に、出力情報が低減されます。
visibility 1,2,3 1 otxadminコマンドで提供するgetサブコマンドの--visibilityオプションと同様に重要度を指定することで、出力される情報 をフィルタリングします。
  • 1 : 基本レベル
  • 2 : 詳細レベル
  • 3 : 全レベル
10.4.1.3. リクエストに含めるエンティティボディについて

管理チャネルでは属性値の変更や操作の実行を行うことが可能です。その場合、リクエストのボディにJSON形式で入力する必要があります。形式は下記の通りです。

{
     "args" : [
        ${args.object}
     …]
}
メンバ名 説明 型
args 属性の更新、及び操作を行う上で入力するパラメータ群。 array
args.[i] アクセス先のリソースに対する引数。 object

イメージとしては下記の通りです。

10.4.1.4. リクエストの返却値について

返却されるリクエストは常に下記の情報が含まれます。

{
  "timestamp": UNIX時間,
  "status": レスポンスコード,
  "message" : "エラー発生時に推奨するアクション",  
  "description" : "リソースの説明",
  "request :{
       "resource" : "現在アクセスしているリソース",
       "params" : [{"指定しているパラメータ"}, ... ],
       "method" : "{実行しているHTTPメソッド}"
  },
  "elements" :{
    /* 各チャネルで定義 */
  }
}
メンバ名 説明 型
timestamp アクセス先のドメインプロセスが動作するサーバ上のUNIX時間を表示します。 number
status 実行時のHTTPレスポンスコードを表示します。 number
message エラー発生時に実施すべきアクションを表示する。表示される内容は、サーバの状況に基づいてローカライズされる。該当する内容 が存在しない場合、空文字が表示されます。 string
description アクセスしているリソースについての説明を記載します。 該当するパラメータが存在しない場合は、表示しません。 string
request 現在実行中のリクエストの情報を表示します。 object
request.resource アクセスしたリソースのURI(絶対パス)を表示します。なお、https://{ホスト名}:{運用管理RESTポート}は除きます。 string
request.params リクエスト実行時に入力したパラメータ群。パラメータの指定が無い場合、空の配列となります。 array
request.params.[i] リクエスト実行時に入力したパラメータが表示されます。 string
request.method アクセス時のHTTPのメソッド名。POST, GET, PUTの何れか一つを表示されます。 string
elements 各チャネルで定義する要素です。 object

管理チャネルにおけるelementsメンバは下記の形式で提供します。

  "elements" :{
      "attributes": [],
      "operations" : [],
      "childResources" : []
  }

各メンバの形式は以下の通りです。

10.4.1.5. API

本章では管理チャネルが提供するAPIをHTTPリクエストごとにまとめています。

GETメソッド
管理チャネルで提供するGETメソッド
項目 概要
URL https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName}/{属性名|操作名}?{パラメータ}
Content-Type application/json
パラメータ view=all,simple visibility=1,2,3
エンティティボディの形式 なし(不要)
返却されるリクエスト形式 
{
  "timestamp": UNIX時間,
  "status": レスポンスコード,
  "message" : "エラー発生時に推奨するアクション",  
  "description" : "リソースの説明",
  "request :{
       "resource" : "現在アクセスしているリソース",
       "params" : [{"指定しているパラメータ"}, ... ],
       "method" : "{実行しているHTTPメソッド}"
  },

  "elements" :{
      "attributes": [{
          "resource" : "/adminrest/v1/config/{DottedName}/{属性名}",
          "methods" : ["GET","PUT "],
          "asciiOnly" : "ASCII文字のみ使用可/不可",
          "defaultValue" : "既定値",
          "description" : "説明",
          "displayName" : "表示名",
          "encrypted" : "暗号化対象か否か",
          "legalNull" : "nullの指定可/不可",
          "legalRange" : "設定可能な値",
          "legalValues" : ["設定範囲" …]
          "maxValue" : "最大値",
          "minValue" : "最小値",
          "name" : "属性名",
          "regex" : "有効とみなされる属性値の正規表現",
          "type" : "属性の型",
          "value" : "属性値",
          "visibility" : "重要度"
      }, ...]

      "operations" : [{
          "resource" : "/adminrest/v1/config/{DottedName}/{操作名}",
          "method" : "POST",
          "description" : "説明",
          "displayName" : "表示名",
          "name" : "操作名",
          "returnType" : "返却結果の型",
          "visibility" : "重要度",
          "value" : "返却値"
          "args" :[ {
              "asciiOnly" : "ASCII文字のみ使用可/不可",
              "defaultValue" : "既定値",
              "description" : "説明",
              "displayName" : "表示名",
              "encrypted" : "暗号化対象か否か",
              "legalNull" : "nullの指定可/不可",
              "legalRange" : "設定可能な値",
              "legalValues" : ["設定範囲" …]
              "name" : "引数名",
              "regex" : "有効とみなされる引数値の正規表現",
              "type" : "引数の型",
              "visibility" : "重要度"
          }, ...]
      }, ...]

      "childResources" : [ 
           "/adminrest/v1/config/{現在のDottedNameの下の階層に連なるDottedName}", 
           ...] 
  }
}
PUTメソッド
管理チャネルで提供するPUTメソッド
項目 概要
URL https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName}/{属性名}?{パラメータ}
Content-Type application/json
パラメータ view=all,simple visibility=1,2,3
エンティティボディの形式 
{
     "args" : ["${更新情報}"]
}
返却されるリクエスト形式 
{
  "timestamp": ${UNIX時間},
  "status": ${レスポンスコード},
  "message" : "${属性のdescription}",  
  "request :{
       "resource"/adminrest/v1/config/{DottedName/{属性名}",
       "params" : [{"view=all"}],
       "method" : "PUT"
  },
  
  "elements" :{
      "attributes": [{
          "resource" : "/adminrest/v1/config/{DottedName/{属性名}",
          "method" : "PUT ",
          "asciiOnly" : "ASCII文字のみ使用可/不可",
          "defaultValue" : "既定値",
          "description" : "説明",
          "displayName" : "表示名",
          "encrypted" : "暗号化対象か否か",
          "legalNull" : "nullの指定可/不可",
          "legalRange" : "設定可能な値",
          "legalValues" : ["設定範囲" …]
          "maxValue" : "最大値",
          "minValue" : "最小値",
          "name" : "属性名",
          "regex" : "有効とみなされる属性値の正規表現",
          "type" : "属性の型",
          "value" : "属性値",
          "visibility" : "重要度"
      }]

      "operations" : []
      "childResources" : []
  }
}
POSTメソッド
管理チャネルで提供するPOSTメソッド
項目 概要
URL https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/config/{DottedName}/{操作名}?{パラメータ}
Content-Type application/json
パラメータ view=all,simple visibility=1,2,3
エンティティボディの形式 
{
     "args" : ["${更新情報}"]
}
返却されるリクエスト形式 
{
  "timestamp": ${UNIX時間},
  "status": ${レスポンスコード},
  "message" : "${属性のdescription}",  
  "request :{
       "resource" : "/adminrest/v1/config/{DottedName}",
       "params" : [{"view=all"}],
       "method" : "POST "
  },
  
  "elements" :{
      "attributes": [],

      "operations" : [{
          "resource" : "/adminrest/v1/config/{DottedName}/{操作}",
          "method" : "POST",
          "description" : "説明",
          "displayName" : "表示名",
          "name" : "操作名",
          "returnType" : "返却結果の型",
          "visibility" : "重要度",
            "args" :[ {
              "asciiOnly" : "ASCII文字のみ使用可/不可",
              "defaultValue" : "既定値",
              "description" : "説明",
              "displayName" : "表示名",
              "encrypted" : "暗号化対象か否か",
              "legalNull" : "nullの指定可/不可",
              "legalRange" : "設定可能な値",
              "legalValues" : ["設定範囲" …]
              "name" : "引数名",
              "regex" : "有効とみなされる引数値の正規表現",
              "type" : "引数の型",
              "visibility" : "重要度"
          }, ...],

      "childResources" : []
  }
}

10.4.2. 統計情報チャネル

10.4.2.1. URLの構成について

統計情報チャネルのURLは、ホスト名、ポート番号、統計情報チャネルのコンテキスト、参照先リソースであるDottedName名(CLIName)、及びその属性値により構成されます。また、 パラメータとしてview、visibilityを提供します。以下ではURLで識別される、アクセス先情報(リソース)を提示しています。

統計情報チャネルで提供するリソース
URL 説明
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/stats/?{パラメータ} 統計情報チャネル直下のアクセス可能なリソースを表示します。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/stats/{DottedName名}?{パラメータ} 指定したリソースが保持する統計情報・子のリソースを表示します。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/stats/{DottedName名}/{統計情報名}?{パラメータ} 指定した統計情報の情報を表示します。

なお、DottedName名はドット(.)をスラッシュに置き換えて実行する必要があります。例えば、domain.ApVirtualMemSize-Currentの場合ApVirtualMemSizeが統計情報名となり、 Currentはその統計情報に属する値となります。 このため、統計情報を取得する場合、下記のようなURLを構築する必要があります。

https://localhost:20101/adminrest/v1/stats/server/domain/ApVirtualMemSize

また、統計情報の一部は、当該機能のモニタリングレベルをON、LOW、HIGHにした場合に表示されるものがあります。 現在、希望する統計情報が取得できるかどうかは、下記のようにotxadminコマンドのgetサブコマンドを使用し、確認し てください。

otxadmin > get --user {ユーザ名} --password {パスワード} --monitor=true "*"
10.4.2.2. パラメータについて

URLを指定する場合、合わせてパラメータを指定することが可能です。パラメータとしては下記の値を指定することができます。

パラメータ
パラメータ 入力値 既定値 説明
view all,simple all 取得結果を詳細と概要の2パターンに分けて表示するを切り替えます。simpleを指定した場合に、出力情報が低減されます。
visibility 1,2,3 1 otxadminコマンドで提供するgetサブコマンドの--visibilityオプションと同様に重要度を指定することで、出力される情報 をフィルタリングします。1: 基本レベル、2: 詳細レベル、3: 全レベルとなります。
10.4.2.3. リクエストに含めるエンティティボディについて

統計情報チャネルではエンティティボディは使用しません。

10.4.2.4. リクエストの返却値について

返却されるリクエストは常に下記の情報が含まれます。

{
  "timestamp": UNIX時間,
  "status": レスポンスコード,
  "message" : "エラー発生時に推奨するアクション",  
  "description" : "リソースの説明",
  "request :{
       "resource" : "現在アクセスしているリソース",
       "params" : [{"指定しているパラメータ"}, ... ],
       "method" : "{実行しているHTTPメソッド}"
  },
  "elements" :{
    /* 各チャネルで定義 */
  }
}
メンバ名 説明 型
timestamp アクセス先のドメインプロセスが動作するサーバ上のUNIX時間を表示します。 number
status 実行時のHTTPレスポンスコードを表示します。 number
message エラー発生時に実施すべきアクションを表示する。表示される内容は、サーバの状況に基づいてローカライズされる。該当する内容 が存在しない場合、空文字が表示されます。 string
description アクセスしているリソースについての説明を記載します。 該当するパラメータが存在しない場合は、表示しません。 string
request 現在実行中のリクエストの情報を表示します。 object
request.resource アクセスしたリソースのURI(絶対パス)を表示します。なお、https://{ホスト名}:{運用管理RESTポート}は除きます。 string
request.params リクエスト実行時に入力したパラメータ群。パラメータの指定が無い場合、空の配列となります。 array
request.params.[i] リクエスト実行時に入力したパラメータが表示されます。 string
request.method アクセス時のHTTPのメソッド名。POST, GET, PUTの何れか一つを表示されます。 string
elements 各チャネルで定義する要素です。 object

統計情報チャネルにおけるelementsメンバは下記の形式で提供します。

  "elements" :{
      "statistics": [],
      "childResources" : []
  }
10.4.2.5. API

本章では統計情報チャネルが提供するAPIをHTTPリクエストごとにまとめています。

GETメソッド
統計情報チャネルで提供するGETメソッド
項目 概要
URL https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/stats/{DottedName}/{統計情報名}?{パラメータ}
Content-Type application/json
パラメータ view=all,simple visibility=1,2,3
エンティティボディの形式 なし(不要)
返却されるリクエスト形式 
{
  "timestamp": ${UNIX時間},
  "status": ${レスポンスコード},
  "message" : "",  
  "request :{
       "resource" : "/adminrest/v1/stats/{DottedName}/{統計情報名}",
       "params" : [{"view=all"}],
       "method" : "GET "
  },
  
  "elements" :{
      "statistics": [{
          "resource" : "統計情報が存在するリソース(URI)名+統計情報名",
          "method" : "GET",
          "name" : "統計情報名",
          "unit" : "単位",
          "description" : "説明",
          "starttime" : "当該情報の採取開始時刻(UNIX時間)",
          "lastSampletime" : "当該情報の最新取得時間(UNIX時間)",
          "statisticsType: "統計情報の型",
          "{統計情情報の型による}"}, 
          ...],

      "childResources" : []
  }
}

10.4.3. WADL

WADLはWeb Application Description Languageの略称です。運用管理RESTではアクセスするリソースのスキーマ及び返却値のスキーマ をWADLにより提供しています。それぞれのアクセス先は下記の通りです。

URL 説明
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/application.wadl リソースのスキーマをXML形式で表示する。
https://{ホスト名}:{運用管理RESTポート}/adminrest/v1/application.wadl/xsd0.xsd リソースの返却値のスキーマをXML形式で表示する。
Copyright (C) 1998 - 2023 NEC Corporation. All rights reserved.