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 ヘッダーのセットに加えて、カスタム制約のある HTTP ヘッダーを定義できます。

JBoss EAP は、以下のようにカスタム制約の HTTP ヘッダーをリクエストに適用します。

  • JBoss EAP は、設定されたプレフィックスをリクエストパスに一致させることで、カスタム制約の HTTP ヘッダーを適用します。

    たとえば、カスタム制約のある HTTP ヘッダーを / や / management などのリクエストパスでリクエストへマップできます。

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

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

  • リクエストの処理の最後に、応答がクライアントに戻る前に、対応するエンドポイントによって設定されたヘッダーを上書きすることで、応答がクライアントに戻されます。

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

単一のマッピングの応答で返される、カスタム制約のある HTTP ヘッダーを複数定義できます。

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

  • custom-constant HTTP ヘッダーには、RFC-7231 - Hypertext Transfer Protocol(HTTP/1.1)でサポートされる文字のみを含めることができます。
  • 以下の事前定義された HTTP ヘッダーを上書きすることはできません。

    • 接続
    • Content-Length
    • Content-Type
    • 日付
    • transfer-Encoding

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

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

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

カスタムに制約のある HTTP ヘッダーを作成する際の重要な考慮事項:

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

3.5.1.2. カスタム化された HTTP ヘッダーの定義

必要なパス接頭辞の要求に対して、すべての応答でカスタム制約のある HTTP ヘッダーを定義します。

重要

カスタム制約のある HTTP ヘッダーを作成する前に、以下の考慮事項を理解する必要があります。

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

手順

  1. カスタムに制約のある 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 ヘッダーセットに加えて HTTP ヘッダー HEADER_NAME を値 HEADER_VALUE を返すようになりました。

    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. カスタム制約のある HTTP ヘッダーを定義する CLI コマンド

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

スタンドアロンモード
  • 単一のカスタム制約のある 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>
  • 複数のカスタム制約のある 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}]}])
ドメインモード
  • 単一のカスタム制約のある 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>
  • 複数のカスタム制約のある 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}]}])