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

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

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

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

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

認証

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

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

お使いの Red Hat Decision 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

Decision 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/decision-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 Decision Manager のインストールオプションについての詳細は、『RED HAT DECISION MANAGER インストールのプラニング』を参照してください。

HTTP ヘッダー

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

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

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

    • application/json (JSON)
    • application/xml (XML, for JAXB)
HTTP メソッド

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

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

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

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

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

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

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

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

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

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

PUT 要求 URL と JSON 要求の本文データの例

http://localhost:8080/decision-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 ユーティリティーを使用した Decision Manager コントローラー REST API による要求送信

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

前提条件

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

手順

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

    REST クライアントの場合:

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

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

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

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

      • accept: application/json
    • -X: GET に設定します。
    • URL: Decision Manager コントローラー REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/decision-central/rest/controller/management/servers となります。
    curl -u 'baAdmin:password@1' -H "accept: application/json" -X GET "http://localhost:8080/decision-central/rest/controller/management/servers"
  3. 要求を実行し、Decision 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 ユーティリティーで、/controller/management/servers/{serverTemplateId} への PUT 要求を以下のコンポーネントで送信し、新規の Decision Server テンプレートを作成します。ご自分のユースケースに合わせて、要求詳細を調整します。

    REST クライアントの場合:

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

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

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

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

      • accept: application/json
      • content-type: application/json
    • -X: PUT に設定します。
    • URL: Decision Manager コントローラー REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/decision-central/rest/controller/management/servers/new-kieserver となります。
    • -d: 新規 Decision Server テンプレート用の設定がある JSON 要求の本文またはファイル (@file.json) を追加します。
    curl -u 'baAdmin:password@1' -H "accept: application/json" -H "content-type: application/json" -X PUT "http://localhost:8080/decision-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/decision-central/rest/controller/management/servers/new-kieserver" -d @my-server-template-configs.json
  5. 要求を実行し、Decision Manager コントローラーの応答が正常であることを確認します。

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

5.2. Swagger インターフェースを使用した Decision Manager コントローラー REST API による要求送信

Decision Manager コントローラー REST API は Swagger web インターフェースをサポートしています。スタンドアロンの REST クライアントや curl ユーティリティーの代わりのこれを使用すると、Business Central ユーザーインターフェースを使わずに Decision Server の テンプレート、インスタンス、関連する KIE コンテナーを Red Hat Decision Manager で操作することができます。

注記

デフォルトでは、org.kie.workbench.swagger.disabled=false のシステムプロパティーが指定されており、Decision Manager の Swagger Web インターフェースが有効になっています。Decision Manager で Swagger Web インターフェースを無効にするには、このシステムプロパティーを true に設定してください。

前提条件

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

手順

  1. web ブラウザーで http://SERVER:PORT/CONTROLLER/docs に移動します。たとえば、http://localhost:8080/decision-central/docs などです。rest-all ロールのある Decision Manager コントローラーユーザーまたは kie-server ロールを持つヘッドレス Decision Manager コントローラーユーザーのユーザー名とパスワードでログインします。

    注記

    Business Central に組み込まれている Decision Manager コントローラーを使用している場合、Decision Manager コントローラーに関連付けられている Swagger ページは、Business Central REST サービスでは「Business Central API」と識別されます。Business Central なしでヘッドレス Decision Manager コントローラーを使用している場合は、ヘッドレス Decision Manager コントローラーに関連付けられている Swagger ページは、「Controller API」と識別されます。いずれの場合も、Decision Manager コントローラー REST API エンドポイントは、同じです。

  2. Swagger ページで、要求の送信先となる関連 API エンドポイントを選択します。たとえば、Controller :: KIE Server templates and KIE containers[GET] /controller/management/servers で Decision Server テンプレートを Decision Manager コントローラーから取得します。
  3. 該当する場合は Try it out をクリックして、結果のフィルタリングに使用するオプションのパラメーターを提供します。
  4. Response content type ドロップダウンメニューで、サーバー応答のフォーマットを選択します。たとえば、JSON フォーマットでは application/json となります。
  5. Execute をクリックし、Decision Server の応答を確認します。

    サーバー応答の例 (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"
          ]
        }
      ]
    }
  6. Swagger ページで Controller :: KIE Server templates and KIE containers[GET] /controller/management/servers/{serverTemplateId} エンドポイントに移動し、新たな Decision Server テンプレートを作成するための別の要求を送信します。ご自分のユースケースに合わせて、要求詳細を調整します。
  7. Try it out をクリックして、以下の要求のコンポーネントを入力します。

    • serverTemplateId: 新規 Decision Server テンプレートの ID を入力します。例: new-kieserver
    • body: Parameter content type を任意の要求本文形式 (JSON の場合は application/json など) に設定し、要求の本文に新規 Decision Server テンプレートの設定を追加します。
    {
      "server-id": "new-kieserver",
      "server-name": "new-kieserver",
      "container-specs": [],
      "server-config": {},
      "capabilities": [
        "RULE",
        "PROCESS",
        "PLANNING"
      ]
    }
  8. Response content type ドロップダウンメニューで、サーバー応答のフォーマットを選択します。たとえば、JSON フォーマットでは application/json となります。
  9. Execute をクリックし、Decision Manager コントローラーの応答が正常であることを確認します。

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

5.3. サポート対象の Decision Manager コントローラー REST API エンドポイント

Decision Manager コントローラー REST API には、Decision Server テンプレート (設定)、Decision Server インスタンス (リモートサーバー)、関連の KIE コンテナー (デプロイメントユニット) を操作するエンドポイントが含まれます。Decision Manager コントローラー REST API のベース URL は、http://SERVER:PORT/CONTROLLER/rest/ です。すべての要求では、Business Central がインストールされており、ビルトインの Decision Manager コントローラーを使用する場合には、rest-all ユーザーロールの HTTP Basic 認証またはトークベースの認証が必要で、Business Central とは別にヘッドレス Decision Manager コントローラーをインストール済みの場合には、kie-server ユーザーロールの HTTP Basic 認証またはトークンベースの認証が必要です。

Decision Manager コントローラー REST API エンドポイントの完全一覧と説明については、以下のリソースを参照してください。

  • jBPM ドキュメントページ (静的) の Controller REST API
  • http://SERVER:PORT/CONTROLLER/docs (動的。稼働中の Decision Manager コントローラーが必要) ページの Decision Manager コントローラー REST API 用 Swagger UI

    注記

    デフォルトでは、org.kie.workbench.swagger.disabled=false のシステムプロパティーが指定されており、Decision Manager の Swagger Web インターフェースが有効になっています。Decision Manager で Swagger Web インターフェースを無効にするには、このシステムプロパティーを true に設定してください。

    Business Central に組み込まれている Decision Manager コントローラーを使用している場合、Decision Manager コントローラーに関連付けられている Swagger ページは、Business Central REST サービスでは「Business Central API」と識別されます。Business Central なしでヘッドレス Decision Manager コントローラーを使用している場合は、ヘッドレス Decision Manager コントローラーに関連付けられている Swagger ページは、「Controller API」と識別されます。いずれの場合も、Decision Manager コントローラー REST API エンドポイントは、同じです。