メッセージング API の使用法
InterSystems IRIS は、JMS、Kafka、RabbitMQ、Amazon Simple Notification Service (SNS)、Amazon Simple Queue Service (SQS) の各メッセージング・プラットフォームと直接通信するために使用できるメッセージング API を提供します。これらの API クラスは %External.Messaging パッケージに用意されています。
どのプラットフォームでも、大半のコード・フローは同一です。このページでは、この共通のフローについて説明し、共通のクラスとメソッドに関する詳細情報を提供します。特定のメッセージ・プラットフォームについて説明している技術文書もあります。上記の各リンクを参照してください。
(インターシステムズでは、このページで取り上げている各 API のほか、相互運用プロダクションで使用する特殊クラスも用意しています。これらのクラスを使用すると、上記と同様のメッセージング・プラットフォームと直接通信できます。詳細は、上記のリンクを参照してください。)
トピックまたはキューの作成
メッセージを送信するには、使用しているプラットフォームとの関連性に応じてトピックまたはキューが必要になることがあります。
トピックまたはキューのプラットフォーム固有の設定は文字列として共通メソッドに渡されますが、これらの設定はオブジェクトを使用して定義されています。したがって、この設定を渡すときにはそのオブジェクトの ToJSON() メソッドを呼び出す必要があります。以下のコードは、共通メソッドを使用して新しい Kafka トピックを作成します。
Set topic = "quick-start-events"
Set queueSettings = ##class(%External.Messaging.KafkaTopicSettings).%New()
Set queueSettings.numberOfPartitions = 1, queueSettings.replicationFactor = 1
Set tSC = client.CreateQueueOrTopic(topic, queueSettings.ToJSON())
一部のメッセージング・プラットフォームには、高度な機能を含む可能性のあるトピック/キューを作成するための独自のメソッドがあることに注意してください。
メッセージの送信
メッセージ・クライアント・オブジェクトおよび関連するトピック・オブジェクトまたはキュー・オブジェクトをすべて用意していれば、そのクライアント・オブジェクトのメソッドを次のように呼び出し、メッセージを送信します。
-
メッセージ・オブジェクトを作成します。これはメッセージ・クラスのインスタンスです。インターシステムズでは、プラットフォーム固有の各種メッセージ・クラスを提供しています。これらはすべて %External.Messaging.MessageOpens in a new tab のサブクラスです。
以下に Kafka での例を挙げます。
Set msg = ##class(%External.Messaging.Messaging).%New()
Set msg.topic = "quick-start-events"
Set msg.value = "body of the message"
Set msg.key = "somekey"
-
クライアント・オブジェクトの SendMessage() メソッドを呼び出し、メッセージ・オブジェクトを引数として渡します。例えば以下のようにします。
Set tSC = client.SendMessage(msg)
If $$$ISERR(tSC) { //handle error scenario }
このメソッドからはステータス・コードが返されます。このステータス・コードをコードで確認したうえで処理を続行する必要があります。
-
アプリケーションでトピックやキューを必要としなくなった時点で、クライアント・オブジェクトの DeleteTopicOrQueue() メソッドをコードで使用してトピックまたはキューを安全に削除できます。
Do client.DeleteQueueOrTopic(topic)
一部のメッセージング・プラットフォームには、高度な機能を含む可能性のあるトピック/キューを削除するための独自のメソッドがあることに注意してください。
メッセージの受信
メッセージを受信できるメッセージング・プラットフォームでは、クライアント・オブジェクトの ReceiveMessage() メソッドを使用してメッセージを受信します。このメソッドの 1 番目の引数はトピックまたはキューの名前です。2 番目の引数は %ListOfObjectsOpens in a new tab のインスタンスです。このメソッドからは、この 2 番目の引数を使用して参照渡しでメッセージが返されます。
ReceiveMessage() では、settings の JSON 形式文字列もオプションの 3 番目の引数として受け入れます。使用できる設定はプラットフォームによって異なり、プラットフォームごとに ReceiveSettings クラスのプロパティとして定義されています。このような設定を作成するには、ReceiveSettings クラスの新しいインスタンスを作成し、必要に応じてそのプロパティを設定します。つづいて、ReceiveSettings オブジェクトで継承した ToJSON() メソッドを使用して、目的の設定を ReceiveMessage() メソッドに指定します。
ReceiveMessage() メソッドからはステータス・コードが返されます。このステータス・コードをプログラムで確認したうえで処理を続行する必要があります。
以下の例では、JMS キュー (queue) から JMS クライアント (client) がメッセージを受信します。メッセージ取得のタイムアウトとして 200 ミリ秒を設定しています。
Set rset = ##class(%External.Messaging.JMSReceiveSettings).%New()
Set rset.receiveTimeout = 200
#dim messages As %ListOfObjects
Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
If $$$ISERR(tSC) { //handle error scenario }
%ListOfObjectsOpens in a new tab のインスタンスである messages に、トピックまたはキューから取得したメッセージが保存されます。
トピックまたはキューの削除
アプリケーションでトピックやキューを必要としなくなった時点で、クライアント・オブジェクトの DeleteTopicOrQueue() メソッドをコードで使用してトピックまたはキューを安全に削除できます。
Do client.DeleteQueueOrTopic(topic)
一部のメッセージング・プラットフォームには、高度な機能を含む可能性のあるトピック/キューを削除するための独自のメソッドがあることに注意してください。
メッセージ・プラットフォームからの切断
メッセージ・プラットフォームとの通信を終了した時点で、コードからクライアント・オブジェクトの Close() メソッドを呼び出します。例えば以下のようにします。
Do:client'="" client.Close()