Microsoft MSMQ Connector の概要

Microsoft Message Queuing (MSMQ) 用 Anypoint Connector (MSMQ Connector) は、典型的な 2 層クライアントサーバーアーキテクチャ、Mule Runtime で実行されるコネクタまたはクライアント、サーバー側で実行される Windows ゲートウェイを使用します。Windows ゲートウェイは、MSMQ からメッセージを送受信するための HTTP Web API を公開します。

始める前に

このコネクタを使用するには、以下に精通している必要があります。

  • Microsoft MSMQ

  • Mule Runtime Engine (Mule)、Mule 概念、Mule フローの要素、グローバル要素

  • Anypoint Connector

  • Anypoint Studio

アプリケーションを作成する前に、以下が必要です。

  • 対象リソースへの接続をテストするための Microsoft ログイン情報

  • Anypoint Windows ゲートウェイサービスがインストールされていること

ソフトウェアの要件および互換性情報については、「コネクタリリースノート」を参照してください。

アーキテクチャ

次の図は、ソリューションアーキテクチャの概要を示しています。

Windows ゲートウェイサービス

POM ファイル情報

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-microsoft-mq-connector</artifactId>
  <version>x.x.x</version>
  <classifier>mule-plugin</classifier>
</dependency>

x.x.x​ を使用しているコネクタに対応するバージョンに置き換えます。

最新の ​pom.xml​ ファイル情報を取得するには、​ Anypoint Exchange​ でコネクタにアクセスし、​[Dependency Snippets (連動関係スニペット)]​ をクリックします。

ユースケースについて

MSMQ Connector は主に 2 つのユースケースをサポートしています。

  • 1 つのメッセージを MSMQ に送信する (HTTP POST)

  • MSMQ から 1 つ以上のメッセージを受信する (HTTP GET)

ユースケース: HTTP POST

POST のシナリオでは、Mule Runtime はコネクタを使用して、MSMQ への現在のフローにある Mule メッセージの未加工表現を HTTP 経由で Windows ゲートウェイに送信します。メッセージは HTTP POST として送信されます。HTTP 要求のペイロードは、Mule メッセージのシリアル化されたペイロード (バイナリまたはテキスト) です。Web API は Windows ゲートウェイで実行され、MSMQ を使用してメッセージをキューに転送します。

次のメッセージは HTTP POST 要求の構造を示しています。

POST 要求メッセージ

POST: https://localhost:9333/msmq
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\qout
Mule-Api-Version: 1
Body: THIS IS A SAMPLE MESSAGE

POST 応答メッセージ

Http /1.1 201 Created

ユースケース: HTTP GET

GET のシナリオでは、Mule Runtime はコネクタを使用して MSMQ から 1 つ以上のメッセージを受信します。これは、Windows ゲートウェイへの HTTP GET として行われます。Web API はゲートウェイで実行され、MSMQ キューにあるメッセージを返します。メッセージは MIME ​multipart/mixed​ コンテンツタイプを使用して、1 回の HTTP 応答で返されます。

次のメッセージは HTTP GET 要求の構造を示しています。

GET 要求メッセージ

GET: https://localhost:9333/msmq?count=50
Authorization: mule test-token
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1

GET 応答メッセージ

Transfer-Encoding: chunked
Content-Type: multipart/mixed; boundary="42c5468b-f831-900d-d099-a123ef456dcc7"

28
--42c5468b-f831-900d-d099-a123ef456dcc7

218
Content-Type: application/octet-stream
mule-msmq-acknowledgment-type: None
mule-msmq-acknowledgment: None
mule-msmq-attach-sender-id: True
mule-msmq-body-type: 0
mule-msmq-connector-type: 0
mule-msmq-correlation-id: 00000000-0000-0000-0000-000000000000\0
mule-msmq-id: 12ab345c-6d7e-900d-d099-89f012a345bc\6789
mule-msmq-label:
mule-msmq-lookup-id: 288230376151717889
mule-msmq-message-type: Normal
mule-msmq-priority: Normal
mule-msmq-source-machine: win-dt3v2pm5d7l
mule-msmq-extension:
mule-msmq-app-specific: 0

11
THIS IS A MESSAGE
2C

--42c5468b-f831-900d-d099-a123ef456dcc7--

0

ゲートウェイサービスへのメッセージの送受信に使用される HTTP ヘッダーについては、このドキュメントで後ほど詳しく説明します。

メッセージ配信について

MSMQ Connector では、2 フェーズプロトコルを使用して、メッセージを損失せずにゲートウェイと通信を行うことができます。高いスループットが必要で、各メッセージの少なくとも 1 回 (at least once) の受信を確認する必要がない場合は、肯定応答なし (no acknowledgment) プロトコルを使用するように設定できます。

メッセージ配信は 2 つのオプションから選択できます。[Message Delivery (メッセージ配信)] 設定でメッセージ配信の動作モードを確立します。次に、選択可能な各オプションについて説明します。

No Acknowledgment (肯定応答なし) について

従来のシナリオでは、ゲートウェイでメッセージが読み取られたら、そのメッセージはキューから削除されます。ESB に接続障害またはメッセージを読み取れなくする別の問題がある場合、そのメッセージは失われます (このメッセージ配信モードは、対応する設定で [NoAcknowledgment (肯定応答なし)] を選択して設定できます)。それでも、この配信モードが最速なので、各メッセージを少なくとも 1 回配信する必要がない場合は、このモードを選択してください。

At Least Once (少なくとも 1 回) (デフォルト) について

2 フェーズコミットプロトコルを使用するシナリオでは、メインキューから読み取られたメッセージはバックアップとして下位キューで保持されます。コネクタは、メッセージのコピーを受信した後、サブキューからメッセージを削除するようにゲートウェイに追加の要求を送信します。このコミットアクションが完了しなかった場合は、メッセージはそのままサブキューに残ります。しばらくすると、下位キューのメッセージは (孤立とみなされ)、親キューに戻されてそこで再試行されます。誤解のないように言うと、このメカニズムは、コミットフェーズが完了する前にフローが中断されない限り、フローで発生している外部の例外の影響を受けません (このメッセージ配信モードは、対応する設定で [AtLeastOnce (少なくとも 1 回)] を選択して設定できます)。

すでに説明したように、メッセージ配信モードは [Message Delivery (メッセージ配信)] 設定によって決まります。2 フェーズコミットプロトコルを確実に使用したい場合は、この設定を ​AtLeastOnce​ (デフォルト) に設定します。このパラメーターを ​NoAcknowledgment​ に設定すると、各メッセージは Mule に配信されますが、Mule から受信の肯定応答はありません。

Studio プロジェクトへのコネクタの追加

Anypoint Studio には、Studio プロジェクトにコネクタを追加する 2 つの方法があります。Studio タスクバーの Exchange ボタンから追加するか、[Mule Palette (Mule パレット)] ビューから追加します。

Exchange を使用してコネクタを追加する

  1. Studio で Mule プロジェクトを作成します。

  2. Studio タスクバーの左上にある Exchange アイコン ​(X)​ をクリックします。

  3. Exchange で、​[Login (ログイン)]​ をクリックし、Anypoint Platform のユーザー名とパスワードを指定します。

  4. Exchange で、「msmq」を検索します。

  5. コネクタを選択して ​[Add to project (プロジェクトに追加)]​ をクリックします。

  6. 画面の指示に従ってコネクタをインストールします。

Studio でコネクタに追加する

  1. Studio で Mule プロジェクトを作成します。

  2. [Mule Palette (Mule パレット)] ビューで、​[(X) Search in Exchange ((X) Exchange 内を検索)]​ をクリックします。

  3. [Add Modules to Project (モジュールをプロジェクトに追加)]​ で、検索項目に「msmq」と入力します。

  4. [Available modules (使用可能なモジュール)]​ で、このコネクタの名前をクリックします。

  5. [Add (追加)]​ をクリックします。

  6. [Finish (完了)]​ をクリックします。

Studio に設定する方法

  1. HTTP リスナーを Studio キャンバスにドラッグします。

    Studio の MSMQ デモフロー
  2. [Path (パス)] を設定します。

  3. 緑のプラス記号をクリックしてリスナーを設定します。

  4. MSMQ Connector の操作を Studio キャンバスにドラッグします。

  5. 緑のプラス記号をクリックしてコネクタに設定を追加します。

  6. 次の項目に入力します。

    「Global Element Properties (グローバル要素のプロパティ)」
    • Gateway Service Address (ゲートウェイサービスアドレス): Windows ゲートウェイの URL。

    • Gateway Access Token (ゲートウェイアクセストークン): Windows ゲートウェイのアクセストークン。

    • Queue Name (キュー名): メッセージの送信先のキュー。

    • Message Formatter (メッセージフォーマッター): 必要なメッセージ形式。

  7. [OK] をクリックします。

  8. 次の項目を設定します。

    MSMQ プロパティ画面
    • Message Formatter (メッセージフォーマッター) (未設定の場合): 必要なメッセージ形式

    • Payload (ペイロード): メッセージのコンテンツ

    • Time To Reach Queue (キュー到達時間): メッセージをゲートウェイで受信してから MSMQ サーバーに到達するまでの最大秒数。デフォルトはタイムアウトしない設定になっています (InfiniteTimeout)。

    • Time To Be Received (受信までの時間): メッセージがキューに留まっていられる秒数。これを過ぎるとサードパーティアプリケーションにデキューされます。デフォルトはタイムアウトしない設定になっています (InfiniteTimeout)。

ユースケース: Studio

「Studio フローの [Listener (リスナー)]、[Logger (ロガー)]、[Send (送信)]、[DataWeave] の各アイコン。」

ユースケース: XML

<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:file="http://www.mulesoft.org/schema/mule/file"
xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:msmq="http://www.mulesoft.org/schema/mule/msmq"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/msmq
http://www.mulesoft.org/schema/mule/msmq/current/mule-msmq.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.xsd
http://www.mulesoft.org/schema/mule/file
http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd">

<http:listener-config name="HTTP_Listener_config"
doc:name="HTTP Listener config" basePath="/">
    <http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>

<configuration-properties file="gateway-connection.properties" />

<http:request-config name="HTTP_Request_configuration"
doc:name="HTTP Request configuration"/>
<msmq:msmq-sender-config name="MSMQ_Connector_Msmq_sender_config"
messageFormatter="None" doc:name="MSMQ Connector Msmq sender config">
    <msmq:msmq-connection serviceAddress="${msmqConfig.serviceAddress}"
     accessToken="${msmqConfig.accessToken}"
     queueName="${msmqConfig.rootQueueName}"
     ignoreSSLWarnings="true" />
</msmq:msmq-sender-config>
<msmq:msmq-receiver-config name="MSMQ_Connector_Msmq_receiver_config"
messageCount="1" pollingFrequency="1" messageFormatter="None"
doc:name="MSMQ Connector Msmq receiver config"
messageDelivery="AtLeastOnce" >
    <msmq:msmq-connection serviceAddress="${msmqConfig.serviceAddress}"
     accessToken="${msmqConfig.accessToken}"
     queueName="${msmqConfig.rootQueueName}"
     ignoreSSLWarnings="true" />
</msmq:msmq-receiver-config>
<flow name ="Parse-template">
    <http:listener doc:name="Listener"
    config-ref="HTTP_Listener_config" path="/"/>
    <parse-template doc:name="Parse Template"
    location="form.html"/>

</flow>
<flow name="msmq-demo-send-operation">
<http:listener doc:name="Listener"
config-ref="HTTP_Listener_config" path="/send"/>
<logger level="INFO" doc:name="Logger"
message="#[payload]"/>
<msmq:send doc:name="Send"
 config-ref="MSMQ_Connector_Msmq_sender_config"
 messageFormatter="None" queueName="${msmqConfig.rootQueueName}">
    <msmq:payload ><![CDATA[#[attributes.queryParams.message]]]></msmq:payload>
</msmq:send>
<ee:transform doc:name="Transform Message" >
    <ee:message >
                <ee:set-payload ><![CDATA[%dw 2.0
output text/plain
---
"Message sent successfully"]]></ee:set-payload>
            </ee:message>
        </ee:transform>
    </flow>
    <flow name="msmq-demo-receive-source" >
    <msmq:msmq doc:name="Msmq" config-ref="MSMQ_Connector_Msmq_receiver_config" />
        <logger level="INFO" doc:name="Logger" message="#[payload]"/>
    </flow>
</mule>