第1章 KIE コンテナーおよびビジネスアセット用の Decision Server REST API

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

Decision Server REST API を使用すると、以下のアクションが可能になります。

  • KIE コンテナーのデプロイまたは破棄
  • KIE コンテナー情報の取得および更新
  • Decision Server ステータスおよび基本的情報の確認
  • ビジネスアセット情報の取得および更新
  • ビジネスアセット (ルールやプロセス) の実行

Decision Server REST API 要求には以下のコンポーネントが必要です。

認証

Decision Server REST API は、ユーザーロール kie-server に HTTP の Basic 認証またはトークンベースの認証を必要とします。お使いの Red Hat Decision Manager に設定されているユーザーロールを表示するには、~/$SERVER_HOME/standalone/configuration/application-roles.properties~/application-users.properties に移動します。

ユーザーに kie-server ロールを追加するには、~/$SERVER_HOME/bin に移動して以下のコマンドを実行します。

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

ユーザーロールと Red Hat Decision Manager のインストールオプションについての詳細は、『RED HAT DECISION MANAGER インストールのプラニング』を参照してください。

HTTP ヘッダー

Decision Server REST API は、API 要求に以下の HTTP ヘッダーを必要とします。

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

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

    • application/json (JSON)
    • application/xml (XML、JAXB または XSTREAM 用)
  • X-KIE-ContentType: application/xml XSTREAM API 要求および応答に必要なヘッダー:

    • XSTREAM
HTTP メソッド

Decision Server REST API は、API 要求に以下の HTTP メソッドを必要とします。

  • GET: 指定したリソースのエンドポイントから指定した情報を取得する
  • POST: リソースまたはリソースインスタンスを更新する
  • PUT: リソースまたはリソースインスタンスを更新もしくは作成する
  • DELETE: リソースまたはリソースインスタンスを削除する
ベース URL
Decision Server REST API 要求のベース URL は http://SERVER:PORT/kie-server/services/rest/ で、たとえば http://localhost:8080/kie-server/services/rest/ となります。
Endpoints (エンドポイント)

特定の KIE コンテナーにおける /server/containers/{containerId} など、Decision Server REST API のエンドポイントは、Decision Server REST API ベース URL に追記する URI で、Red Hat Decision Manager の対応するリソースやリソースタイプにアクセスするためのものです。

/server/containers/{containerId} エンドポイントの要求 URL 例

http://localhost:8080/kie-server/services/rest/server/containers/MyContainer

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

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

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

http://localhost:8080/kie-server/services/rest/server/containers?groupId=com.redhat&artifactId=Project1&version=1.0&status=STARTED

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

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

http://localhost:8080/kie-server/services/rest/server/containers/MyContainer/release-id

{
  "release-id": {
    "artifact-id": "Project1",
    "group-id": "com.redhat",
    "version": "1.1"
  }
}

1.1. REST クライアントまたは curl ユーティリティーを使用した Decision Server REST API による要求送信

Decision Server REST API を使用すると、Business Central ユーザーインターフェースを使わずに Red Hat Decision Manager の KIE コンテナーやビジネスアセット (ビジネスルールやプロセス、ソルバーなど) を操作することができます。Decision Server REST API 要求は、REST クライアントまたは curl ユーティリティーを使って送信できます。

前提条件

  • Decision Server をインストールし、実行している。
  • kie-server ユーザーロールで Decision Server にアクセスできる。

手順

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

    REST クライアントの場合:

    • Authentication: kie-server ロールを持つ Decision Server ユーザーのユーザー名とパスワードを入力します。
    • HTTP Headers: 以下のヘッダーを設定します。

      • Accept: application/json
    • HTTP method: GET に設定します。
    • URL: Decision Server REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/kie-server/services/rest/server/containers となります。

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

    • -u: kie-server ロールを持つ Decision Server ユーザーのユーザー名とパスワードを入力します。
    • -H: 以下のヘッダーを設定します。

      • accept: application/json
    • -X: GET に設定します。
    • URL: Decision Server REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/kie-server/services/rest/server/containers となります。
    curl -u 'baAdmin:password@1' -H "accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/server/containers"
  3. 要求を実行し、Decision Server の応答を確認します。

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

    {
      "type": "SUCCESS",
      "msg": "List of created containers",
      "result": {
        "kie-containers": {
          "kie-container": [
            {
              "container-id": "itorders_1.0.0-SNAPSHOT",
              "release-id": {
                "group-id": "itorders",
                "artifact-id": "itorders",
                "version": "1.0.0-SNAPSHOT"
              },
              "resolved-release-id": {
                "group-id": "itorders",
                "artifact-id": "itorders",
                "version": "1.0.0-SNAPSHOT"
              },
              "status": "STARTED",
              "scanner": {
                "status": "DISPOSED",
                "poll-interval": null
              },
              "config-items": [],
              "container-alias": "itorders"
            }
          ]
        }
      }
    }
  4. この例では、プロジェクトの group-idartifact-id、および version (GAV) のデータを応答で返されたデプロイ済み KIE コンテナーのいずれかからコピーするか、書き留めます。
  5. REST クライアントまたは curl ユーティリティーで、/server/containers/{containerId} への PUT 要求を以下のコンポーネントで送信し、コピーしたプロジェクトの GAV データで新規 KIE コンテナーをデプロイします。ご自分のユースケースに合わせて、要求詳細を調整します。

    REST クライアントの場合:

    • Authentication: kie-server ロールを持つ Decision Server ユーザーのユーザー名とパスワードを入力します。
    • HTTP Headers: 以下のヘッダーを設定します。

      • Accept: application/json
      • Content-Type: application/json
    • HTTP method: PUT に設定します。
    • URL: Decision Server REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/kie-server/services/rest/server/containers/MyContainer となります。
    • 要求の本文: 新規 KIE コンテナー用の設定アイテムのある JSON 要求の本文を追加します。
    {
      "config-items": [
        {
          "itemName": "RuntimeStrategy",
          "itemValue": "SINGLETON",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "MergeMode",
          "itemValue": "MERGE_COLLECTIONS",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "KBase",
          "itemValue": "",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "KSession",
          "itemValue": "",
          "itemType": "java.lang.String"
        }
      ],
      "release-id": {
        "group-id": "itorders",
        "artifact-id": "itorders",
        "version": "1.0.0-SNAPSHOT"
      },
      "scanner": {
        "poll-interval": "5000",
        "status": "STARTED"
      }
    }

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

    • -u: kie-server ロールを持つ Decision Server ユーザーのユーザー名とパスワードを入力します。
    • -H: 以下のヘッダーを設定します。

      • accept: application/json
      • content-type: application/json
    • -X: PUT に設定します。
    • URL: Decision Server REST API ベース URL とエンドポイントを入力します。たとえば、http://localhost:8080/kie-server/services/rest/server/containers/MyContainer となります。
    • -d: 新規 KIE コンテナー用の設定アイテムのある JSON 要求の本文またはファイル (@file.json) を追加します。
    curl -u 'baAdmin:password@1' -H "accept: application/json" -H "content-type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d "{ \"config-items\": [ { \"itemName\": \"RuntimeStrategy\", \"itemValue\": \"SINGLETON\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"MergeMode\", \"itemValue\": \"MERGE_COLLECTIONS\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KBase\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KSession\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" } ], \"release-id\": { \"group-id\": \"itorders\", \"artifact-id\": \"itorders\", \"version\": \"1.0.0-SNAPSHOT\" }, \"scanner\": { \"poll-interval\": \"5000\", \"status\": \"STARTED\" }}"
    curl -u 'baAdmin:password@1' -H "accept: application/json" -H "content-type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d @my-container-configs.json
  6. 要求を実行し、Decision Server の応答を確認します。

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

    {
      "type": "SUCCESS",
      "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.",
      "result": {
        "kie-container": {
          "container-id": "MyContainer",
          "release-id": {
            "group-id": "itorders",
            "artifact-id": "itorders",
            "version": "1.0.0-SNAPSHOT"
          },
          "resolved-release-id": {
            "group-id": "itorders",
            "artifact-id": "itorders",
            "version": "1.0.0-SNAPSHOT"
          },
          "status": "STARTED",
          "scanner": {
            "status": "STARTED",
            "poll-interval": 5000
          },
          "config-items": [],
          "messages": [
            {
              "severity": "INFO",
              "timestamp": {
                "java.util.Date": 1540584717937
              },
              "content": [
                "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT."
              ]
            }
          ],
          "container-alias": null
        }
      }
    }

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

1.2. Swagger インターフェースを使用した Decision Server REST API による要求送信

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

注記

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

前提条件

  • Decision Server をインストールし、実行している。
  • kie-server ユーザーロールで Decision Server にアクセスできる。

手順

  1. Web ブラウザーで http://SERVER:PORT/kie-server/docs を開きます。たとえば、http://localhost:8080/kie-server/docs となります。kie-server ロールを持つ Decision Server ユーザーのユーザー名とパスワードでログインします。
  2. Swagger ページで、要求の送信先となる関連 API エンドポイントを選択します。たとえば、KIE Server and KIE containers[GET] /server/containers で KIE コンテナーを Decision Server から取得します。
  3. Try it out をクリックして、結果のフィルタリングに使用するオプションのパラメーターを提供します。
  4. Response content type ドロップダウンメニューで、サーバー応答のフォーマットを選択します。たとえば、JSON フォーマットでは application/json となります。
  5. Execute をクリックし、Decision Server の応答を確認します。

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

    {
      "type": "SUCCESS",
      "msg": "List of created containers",
      "result": {
        "kie-containers": {
          "kie-container": [
            {
              "container-id": "itorders_1.0.0-SNAPSHOT",
              "release-id": {
                "group-id": "itorders",
                "artifact-id": "itorders",
                "version": "1.0.0-SNAPSHOT"
              },
              "resolved-release-id": {
                "group-id": "itorders",
                "artifact-id": "itorders",
                "version": "1.0.0-SNAPSHOT"
              },
              "status": "STARTED",
              "scanner": {
                "status": "DISPOSED",
                "poll-interval": null
              },
              "config-items": [],
              "container-alias": "itorders"
            }
          ]
        }
      }
    }
  6. この例では、プロジェクトの group-idartifact-id、および version (GAV) のデータを応答で返されたデプロイ済み KIE コンテナーのいずれかからコピーするか、書き留めます。
  7. Swagger ページで KIE Server and KIE containers[PUT] /server/containers/{containerId} エンドポイントに移動し、コピーしたプロジェクト GAV データで新規 KIE コンテナーをデプロイするための別の要求を送信します。ご自分のユースケースに合わせて、要求詳細を調整します。
  8. Try it out をクリックして、以下の要求のコンポーネントを入力します。

    • containerId: 新規 KIE コンテナーの ID を入力します。例: MyContainer
    • body: Parameter content type を任意の要求の本文 (JSON の場合は application/json など) に設定し、要求の本文に新規 KIE コンテナーの設定アイテムを追加します。
    {
      "config-items": [
        {
          "itemName": "RuntimeStrategy",
          "itemValue": "SINGLETON",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "MergeMode",
          "itemValue": "MERGE_COLLECTIONS",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "KBase",
          "itemValue": "",
          "itemType": "java.lang.String"
        },
        {
          "itemName": "KSession",
          "itemValue": "",
          "itemType": "java.lang.String"
        }
      ],
      "release-id": {
        "group-id": "itorders",
        "artifact-id": "itorders",
        "version": "1.0.0-SNAPSHOT"
      },
      "scanner": {
        "poll-interval": "5000",
        "status": "STARTED"
      }
    }
  9. Response content type ドロップダウンメニューで、サーバー応答のフォーマットを選択します。たとえば、JSON フォーマットでは application/json となります。
  10. Execute をクリックし、Decision Server の応答を確認します。

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

    {
      "type": "SUCCESS",
      "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.",
      "result": {
        "kie-container": {
          "container-id": "MyContainer",
          "release-id": {
            "group-id": "itorders",
            "artifact-id": "itorders",
            "version": "1.0.0-SNAPSHOT"
          },
          "resolved-release-id": {
            "group-id": "itorders",
            "artifact-id": "itorders",
            "version": "1.0.0-SNAPSHOT"
          },
          "status": "STARTED",
          "scanner": {
            "status": "STARTED",
            "poll-interval": 5000
          },
          "config-items": [],
          "messages": [
            {
              "severity": "INFO",
              "timestamp": {
                "java.util.Date": 1540584717937
              },
              "content": [
                "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT."
              ]
            }
          ],
          "container-alias": null
        }
      }
    }

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

1.3. サポート対象の Decision Server REST API エンドポイント

Decision Server REST API は、Red Hat Decision Manager で以下のタイプのリソースにエンドポイントを提供します。

  • Decision Server および KIE コンテナー
  • KIE セッションアセット (ランタイムコマンド用)
  • DMN アセット
  • プラニングソルバー

Decision Server REST API のベース URL は http://SERVER:PORT/kie-server/services/rest/ です。ユーザーロール kie-server では、すべての要求で HTTP Basic 認証またはトークンベースの認証が必要です。

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

  • jBPM ドキュメントページ (静的) の Execution Server REST API
  • http://SERVER:PORT/kie-server/docs (動的。稼働中の Decision Server が必要) ページの Decision Server REST API 用 Swagger UI

    注記

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