3.5. 管理 API

3.5.1. HTTP API

HTTP API のエンドポイントは、HTTP プロトコルに依存して JBoss EAP 管理レイヤーと統合する管理クライアントのエントリーポイントです。

HTTP API は、JBoss EAP 管理コンソールによって使用されますが、他のクライアントの統合機能も提供します。デフォルトでは、http://HOST_NAME:9990/management で HTTP API にアクセスできます。この URL は、API に公開される raw 属性および値を表示します。

リソースの読み取り

HTTP POST メソッドを使用して他の操作を読み取り、書き込み、および実行できますが、GET リクエストを使用すると一部の読み取り操作を実行できます。HTTP GET メソッドは以下の URL 形式を使用します。 

http://HOST_NAME:9990/management/PATH_TO_RESOURCE?operation=OPERATION&PARAMETER=VALUE

置き換え可能な値は必ず適切な値に置き換えてください。置き換え可能な OPERATION の値は、以下の値に置き換えられます。

Value説明

attribute

read-attribute 操作を実行します。

operation-description

read-operation-description 操作を実行します。

operation-names

read-operation-names 操作を実行します。

resource

read-resource 操作を実行します。

resource-description

read-resource-description 操作を実行します。

snapshots

list-snapshots 操作を実行します。

以下の URL 例は、HTTP API を使用して読み取り操作を実行する方法を示しています。

例: リソースに対するすべての属性および値の読み取り

http://HOST_NAME:9990/management/subsystem/undertow/server/default-server/http-listener/default

これは、default HTTP リスナーのすべての属性とそれらの値を表示します。

注記

デフォルトの操作は read-resource です。

例: リソースに対する属性の値の読み取り

http://HOST_NAME:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled

これは、ExampleDS データソースの enabled 属性の値を読み取ります。

リソースの更新

HTTP POST メソッドを使用して設定値を更新するか、HTTP API を使用して他の操作を実行できます。これらの操作の認証を提供する必要があります。

以下の例は、HTTP API を使用してリソースを更新する方法を示しています。

例: リソースに対する属性の値の更新

$ curl --digest http://HOST_NAME:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"write-attribute", "address":["subsystem","datasources","data-source","ExampleDS"], "name":"enabled", "value":"false", "json.pretty":"1"}'

これは、ExampleDS データソースの enabled 属性の値を false に更新します。

例: サーバーに対する操作の実行

$ curl --digest http://localhost:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"reload"}'

これは、サーバーをリロードします。

HTTP API を使用して JBoss EAP にアプリケーションをデプロイする方法については、HTTP API を使用したアプリケーションのデプロイ を参照してください

3.5.1.1. custom-constant HTTP ヘッダー

JBoss EAP の HTTP 管理エンドポイントは、クライアントに送信されるすべての応答で事前定義された HTTP ヘッダーのセットを返します。この事前定義された HTTP ヘッダーのセットに加えて、custom-constant HTTP ヘッダーを定義できます。

JBoss EAP は、以下のように custom-constant HTTP ヘッダーをリクエストに適用します。

  • JBoss EAP は、リクエストパスに対して設定された接頭辞を照合して、custom-constant HTTP ヘッダーを適用します。

    たとえば、/ や /management などのリクエストパスのリクエストに、custom-constant HTTP ヘッダーをマップできます。

  • リクエストが複数の接頭辞に一致する場合、JBoss EAP はすべてのマッピングから custom-constant HTTP ヘッダーを適用します。

    たとえば、パス /management へのリクエストは、/ と /management の両方のマッピングと一致します。JBoss EAP は両方のマッピングからヘッダーを適用します。

  • リクエストの処理の最後に、応答がクライアントに返される前に、対応するエンドポイントによって設定されたヘッダーをオーバーライドします。

    たとえば、管理エンドポイントは各応答に X-Frame-Options ヘッダーを設定します。X-Frame-Options の名前で custom- constant HTTP ヘッダーを定義する場合、custom-constant HTTP ヘッダーがデフォルトのヘッダーを上書きします。

複数の custom-constant HTTP ヘッダーが、単一のマッピングのレスポンスで返されるように定義できます。

custom-constant HTTP ヘッダーを定義するルールは次のとおりです。

  • custom-constant HTTP ヘッダーには、RFC-7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content でサポートされている文字のみを使用できます。

  • 以下の事前定義された HTTP ヘッダーを上書きすることはできません。

    • Connection
    • Content-Length
    • Content-Type
    • Date
    • Transfer-Encoding

    事前定義されたヘッダーのいずれかを上書きすると、エラーが発生します。

    • たとえば、Date という名前で custom-constant HTTP ヘッダーを設定しようとすると、次のエラーが返されます。 

      {
    "outcome" => "failed",
    "failure-description" => "WFLYCTL0458:Disallowed HTTP Header name 'Date'",
    "rolled-back" => true
}

custom-constant HTTP ヘッダーを作成する際の重要な考慮事項:

  • JBoss EAP は指定されたパスにアクセスできるかどうかを検証しません。
  • サブシステムは、HTTP 管理インターフェイスがサポートするコンテキストを動的に追加できます。
  • custom-constant HTTP ヘッダーは、エンドポイントがリクエストへの応答を処理する方法を変更しません。

関連情報

3.5.1.2. custom-constant HTTP ヘッダーの定義

custom-constant HTTP ヘッダーが、要求されたパス接頭辞のリクエストに対するすべての応答で返されるように定義します。

重要

custom-constant HTTP ヘッダーを作成する前に、以下の考慮事項を理解する必要があります。

  • JBoss EAP は指定されたパスにアクセスできるかどうかを検証しません。
  • サブシステムは、HTTP 管理インターフェイスがサポートするコンテキストを動的に追加できます。
  • custom-constant HTTP ヘッダーは、エンドポイントがリクエストへの応答を処理する方法を変更しません。

手順

  1. custom-constant HTTP ヘッダーを定義します。 

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="PATH_PREFIX",headers=[{name="HEADER_NAME",value="HEADER_VALUE"}]}])
    重要

    write-attribute 操作を使用すると、reload-required プロンプトが表示されます。

  2. 変更を反映するためにサーバーをリロードします。 

    reload

    HTTP 管理インターフェイスへのリクエストが、事前定義された HTTP ヘッダーのセットに加えて、HEADER_VALUE の値で HTTP ヘッダー HEADER_NAME を返すようになりました。

    custom-constant HTTP ヘッダー X-Help の例

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="/",headers=[{name="X-Help",value="http://mywebsite.com/help"}]}])

検証手順

  • HTTP 管理インターフェイスにリクエストを送信します。 

    $ curl -s -D - -o /dev/null --digest http://localhost:9990/management/ -u USERNAME:PASSWORD

    custom-constant HTTP ヘッダー X-Help の例の応答例: 

    admin:redhat
HTTP/1.1 200 OK
Connection: keep-alive
X-Frame-Options: SAMEORIGIN
Content-Type: application/json; charset=utf-8
Content-Length: 3312
X-Help: http://mywebsite.com
Date: Tue, 27 Oct 2020 08:13:17 GMT

    応答には、X-HELP custom-constant HTTP ヘッダーが含まれます。

関連情報

3.5.1.3. custom-constant HTTP ヘッダーを定義する CLI コマンド

以下の CLI コマンドは、スタンドアロンおよび管理対象ドメインモードで custom-constant HTTP ヘッダーを定義します。

スタンドアロンモード

  • 単一の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。 

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADERVALUE}]}])

    このコマンドにより、XML 設定は以下のようになります。 

    <management-interfaces>
    <http-interface security-realm="ManagementRealm">
        <http-upgrade enabled="true"/>
        <socket-binding http="management-http"/>
        <constant-headers>
            <header-mapping path="/PREFIX">
                <header name="X-HEADER" value="HEADERVALUE"/>
            </header-mapping>
        </constant-headers>
    </http-interface>
</management-interfaces>

  • 複数の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。 

    /core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX1,headers=[{name=X-HEADER,value=HEADERVALUE-FOR-X}]},{path=/PREFIX2,headers=[{name=Y-HEADER,value=HEADERVALUE-FOR-Y}]}])
ドメインモード

  • 単一の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。 

    /host=master/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADER-VALUE}]}])

    このコマンドにより、XML 設定は以下のようになります。 

    <management-interfaces>
    <http-interface security-realm="ManagementRealm">
        <http-upgrade enabled="true"/>
        <socket interface="management" port="${jboss.management.http.port:9990}"/>
        <constant-headers>
            <header-mapping path="/PREFIX">
                <header name="X-HEADER" value="HEADER-VALUE"/>
            </header-mapping>
        </constant-headers>
    </http-interface>
</management-interfaces>

  • 複数の custom-constant HTTP ヘッダーを定義するには、以下のコマンドを使用します。 

    /host=master/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[ {path=/PREFIX-1,headers=[{name=X-HEADER,value=HEADER-VALUE-FOR-X}]},{path=/PREFIX-2,headers=[{name=Y-HEADER,value=HEADER-VALUE-FOR-Y}]}])

関連情報