第5章 KIE Server テンプレートおよびインスタンス用の Process Automation Manager コントローラー REST API

Red Hat Process Automation Manager は Process Automation Manager コントローラー REST API を提供し、これを使用することで Business Central ユーザーインターフェースを使用せずに KIE Server の テンプレート (設定) や KIE Server インスタンス (リモートサーバー)、関連する KIE コンテナー (デプロイメントユニット) を操作することができます。この API のサポートにより、Red Hat Process Automation Manager サーバーおよびリソースをより効率的に維持でき、Red Hat Process Automation Manager の統合と開発を最適化できるようになります。

Process Automation Manager コントローラー REST API を使用すると、以下のアクションが可能になります。

  • KIE Server テンプレート、インスタンス、および関連する KIE コンテナーに関する情報の取得
  • KIE Server テンプレートおよびインスタンスに関連付けられた KIE コンテナーの更新、起動、または停止
  • KIE Server テンプレートの作成、更新、または削除
  • KIE Server インスタンスの作成、更新、または削除

Process Automation Manager コントローラー REST API への要求には、以下のコンポーネントが必要です。

認証

Process Automation Manager コントローラー REST API は、コントローラーのタイプによって、以下のユーザーロールに HTTP の Basic 認証またはトークンベースの認証を必要とします。

  • Business Central をインストールしていて、ビルトインの Process Automation Manager コントローラーを使用する場合は、rest-all のユーザーロール。
  • ヘッドレス Process Automation Manager コントローラーを Business Central とは別にインストールしている場合は、kie-server のユーザーロール。

お使いの Red Hat Process Automation Manager に設定されているユーザーロールを表示するには、~/$SERVER_HOME/standalone/configuration/application-roles.properties~/application-users.properties に移動します。

ユーザーに kie-server ロールか rest-all ロール、もしくはそれら両方を追加するには、~/$SERVER_HOME/bin に移動し、ロールを指定して以下のコマンドを実行します。

$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server,rest-all

Process Automation Manager コントローラーのアクセスで kie-server または rest-all ユーザーを設定するには、~/$SERVER_HOME/standalone/configuration/standalone-full.xml に移動し、(該当する場合は) org.kie.server プロパティーのコメントを解除して、コントローラーユーザーログイン認証情報とコントローラーの位置を (必要に応じて) 追加します。

<property name="org.kie.server.location" value="http://localhost:8080/kie-server/services/rest/server"/>
<property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"/>
<property name="org.kie.server.controller.user" value="baAdmin"/>
<property name="org.kie.server.controller.pwd" value="password@1"/>
<property name="org.kie.server.id" value="default-kieserver"/>

ユーザーロールと Red Hat Process Automation Manager のインストールオプションの詳細は、『 Red Hat Process Automation Manager インストールの計画』 を参照してください。

HTTP ヘッダー

Process Automation Manager コントローラー REST API は、API 要求に以下の HTTP ヘッダーを必要とします。

  • Accept: 要求元のクライアントが受け付けるデータ形式:

    • application/json (JSON)
    • application/xml (XML、JAXB 用)
  • Content-Type: POST または PUT API 要求データ向けのデータ形式:

    • application/json (JSON)
    • application/xml (XML、JAXB 用)
HTTP メソッド

Process Automation Manager コントローラー REST API は、API 要求に以下の HTTP メソッドをサポートします。

  • GET: 指定したリソースのエンドポイントから指定した情報を取得する
  • POST: リソースまたはリソースインスタンスを更新する
  • PUT: リソースまたはリソースインスタンスを作成する
  • DELETE: リソースまたはリソースインスタンスを削除する
ベース URL
Process Automation Manager コントローラー REST API リクエストのベース URL は http://SERVER:PORT/CONTROLLER/rest/ で、Business Central のビルトイン Process Automation Manager コントローラーを使用している場合は http://localhost:8080/business-central/rest/ のようになります。
エンドポイント

指定した KIE Server テンプレートにおける /controller/management/servers/{serverTemplateId} などの Process Automation Manager コントローラー REST API のエンドポイントは、Process Automation Manager コントローラー REST API のベース URL に追記する URI で、Red Hat Process Automation Manager の対応するサーバーリソースやサーバーリソースのタイプにアクセスするためのものです。

/spaces/{serverTemplateId} エンドポイントの要求 URL 例

http://localhost:8080/business-central/rest/controller/management/servers/default-kieserver

要求パラメーターおよび要求データ

Process Automation Manager コントローラー REST API 要求のなかには、特定リソースを特定またはフィルタリングし、特定のアクションを実行するために、要求 URL パスで特定のパラメーターを必要とします。URL パラメーターは、?<PARAM>=<VALUE>&<PARAM>=<VALUE> の形式でエンドポイントに追記します。

DELETE 要求 URL のパラメーター例

http://localhost:8080/business-central/rest/controller/server/new-kieserver-instance?location=http://localhost:8080/kie-server/services/rest/server

HTTP POSTPUT の要求は、さらに要求のボディもしくはデータのあるファイルが必要になる場合があります。

PUT 要求 URL と JSON 要求のボディデータの例

http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver

{
  "server-id": "new-kieserver",
  "server-name": "new-kieserver",
  "container-specs": [],
  "server-config": {},
  "capabilities": [
    "RULE",
    "PROCESS",
    "PLANNING"
  ]
}

5.1. REST クライアントまたは curl ユーティリティーを使用した Process Automation Manager コントローラー REST API による要求送信

Process Automation Manager コントローラーは REST API を提供し、これを使用することで Business Central ユーザーインターフェースを使わずに KIE Server のテンプレート (設定) や KIE Server インスタンス (リモートサーバー)、関連する KIE コンテナー (デプロイメントユニット) を操作することができます。Process Automation Manager コントローラー REST API リクエストは、REST クライアントや curl ユーティリティーを使って送信することができます。

前提条件

  • KIE Server をインストールし、実行している。
  • Process Automation Manager コントローラーまたはヘッドレス Process Automation Manager コントローラーがインストールされ、実行中である。
  • Business Central をインストールしている場合は Process Automation Manager コントローラーにアクセスする rest-all ユーザーロールがある。もしくは、Business Central とは別にインストールされたヘッドレス Process Automation Manager コントローラーにアクセスする kie-server ユーザーロールがある。

手順

  1. 要求の送信先となる関連する API エンドポイント を特定します。Process Automation Manager コントローラーから KIE Server テンプレートを取得する [GET] /controller/management/servers などです。
  2. REST クライアントまたは curl ユーティリティーで、controller/management/servers への GET 要求に以下のコンポーネントを記入します。ご自分のユースケースに合わせて、要求詳細を調整します。

    REST クライアントの場合:

    • Authentication: rest-all ロールのある Process Automation Manager コントローラーユーザーまたは kie-server ロールを持つヘッドレス Process Automation Manager コントローラーユーザーのユーザー名とパスワードを入力します。
    • HTTP Headers: 以下のヘッダーを設定します。

      • Accept: application/json
    • HTTP method: GET に設定します。
    • URL: Process Automation Manager コントローラー REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/business-central/rest/controller/management/servers となります。

    curl ユーティリティーの場合:

    • -u: rest-all ロールのある Process Automation Manager コントローラーユーザーまたは kie-server ロールを持つヘッドレス Process Automation Manager コントローラーユーザーのユーザー名およびパスワードを入力します。
    • -H: 以下のヘッダーを設定します。

      • Accept: application/json
    • -X: GET に設定します。
    • URL: Process Automation Manager コントローラー REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/business-central/rest/controller/management/servers となります。
    curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/business-central/rest/controller/management/servers"
  3. 要求を実行し、Process Automation Manager コントローラーの応答を確認します。

    サーバー応答の例 (JSON):

    {
      "server-template": [
        {
          "server-id": "default-kieserver",
          "server-name": "default-kieserver",
          "container-specs": [
            {
              "container-id": "employeerostering_1.0.0-SNAPSHOT",
              "container-name": "employeerostering",
              "server-template-key": {
                "server-id": "default-kieserver",
                "server-name": "default-kieserver"
              },
              "release-id": {
                "group-id": "employeerostering",
                "artifact-id": "employeerostering",
                "version": "1.0.0-SNAPSHOT"
              },
              "configuration": {
                "RULE": {
                  "org.kie.server.controller.api.model.spec.RuleConfig": {
                    "pollInterval": null,
                    "scannerStatus": "STOPPED"
                  }
                },
                "PROCESS": {
                  "org.kie.server.controller.api.model.spec.ProcessConfig": {
                    "runtimeStrategy": "SINGLETON",
                    "kbase": "",
                    "ksession": "",
                    "mergeMode": "MERGE_COLLECTIONS"
                  }
                }
              },
              "status": "STARTED"
            },
            {
              "container-id": "mortgage-process_1.0.0-SNAPSHOT",
              "container-name": "mortgage-process",
              "server-template-key": {
                "server-id": "default-kieserver",
                "server-name": "default-kieserver"
              },
              "release-id": {
                "group-id": "mortgage-process",
                "artifact-id": "mortgage-process",
                "version": "1.0.0-SNAPSHOT"
              },
              "configuration": {
                "RULE": {
                  "org.kie.server.controller.api.model.spec.RuleConfig": {
                    "pollInterval": null,
                    "scannerStatus": "STOPPED"
                  }
                },
                "PROCESS": {
                  "org.kie.server.controller.api.model.spec.ProcessConfig": {
                    "runtimeStrategy": "PER_PROCESS_INSTANCE",
                    "kbase": "",
                    "ksession": "",
                    "mergeMode": "MERGE_COLLECTIONS"
                  }
                }
              },
              "status": "STARTED"
            }
          ],
          "server-config": {},
          "server-instances": [
            {
              "server-instance-id": "default-kieserver-instance@localhost:8080",
              "server-name": "default-kieserver-instance@localhost:8080",
              "server-template-id": "default-kieserver",
              "server-url": "http://localhost:8080/kie-server/services/rest/server"
            }
          ],
          "capabilities": [
            "RULE",
            "PROCESS",
            "PLANNING"
          ]
        }
      ]
    }
  4. REST クライアントまたは curl ユーティリティーで、PUT 要求用の以下のコンポーネントで別の API 要求を /controller/management/servers/{serverTemplateId} へ送信し、新規の KIE Server テンプレートを作成します。ご自分のユースケースに合わせて、要求詳細を調整します。

    REST クライアントの場合:

    • Authentication: rest-all ロールのある Process Automation Manager コントローラーユーザーまたは kie-server ロールを持つヘッドレス Process Automation Manager コントローラーユーザーのユーザー名とパスワードを入力します。
    • HTTP Headers: 以下のヘッダーを設定します。

      • Accept: application/json
      • Content-Type: application/json
    • HTTP method: PUT に設定します。
    • URL: Process Automation Manager コントローラー REST API ベース URL およびエンドポイントを入力します。たとえば、http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver となります。
    • 要求のボディ: 新規 KIE Server テンプレート用の設定を含めて JSON 要求のボディを追加します。
    {
      "server-id": "new-kieserver",
      "server-name": "new-kieserver",
      "container-specs": [],
      "server-config": {},
      "capabilities": [
        "RULE",
        "PROCESS",
        "PLANNING"
      ]
    }

    curl ユーティリティーの場合:

    • -u: rest-all ロールのある Process Automation Manager コントローラーユーザーまたは kie-server ロールを持つヘッドレス Process Automation Manager コントローラーユーザーのユーザー名およびパスワードを入力します。
    • -H: 以下のヘッダーを設定します。

      • Accept: application/json
      • Content-Type: application/json
    • -X: PUT に設定します。
    • URL: Process Automation Manager コントローラー REST API ベース URL およびエンドポイントを入力します。たとえば、http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver となります。
    • -d: 新規 KIE Server テンプレート用の設定を含めて JSON 要求のボディまたはファイル (@file.json) を追加します。
    curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver" -d "{ \"server-id\": \"new-kieserver\", \"server-name\": \"new-kieserver\", \"container-specs\": [], \"server-config\": {}, \"capabilities\": [ \"RULE\", \"PROCESS\", \"PLANNING\" ]}"
    curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/business-central/rest/controller/management/servers/new-kieserver" -d @my-server-template-configs.json
  5. 要求を実行し、Process Automation Manager コントローラーの応答が正常であることを確認します。

    要求エラーが発生した場合は、返されたエラーコードメッセージを確認して、それに応じて要求を調整します。