メッセージング API の使用法
InterSystems IRIS は、JMS、Kafka、RabbitMQ、Amazon Simple Notification Service (SNS)、Amazon Simple Queue Service (SQS) の各メッセージング・プラットフォームと直接通信するために使用できるメッセージング API を提供します。これらの API クラスは %External.Messaging パッケージに用意されています。
どのプラットフォームでも、大半のコード・フローは同一です。このページでは、この共通のフローについて説明し、共通のクラスとメソッドに関する詳細情報を提供します。特定のメッセージ・プラットフォームについて説明している技術文書もあります。上記の各リンクを参照してください。
(インターシステムズでは、このページで取り上げている各 API のほか、相互運用プロダクションで使用する特殊クラスも用意しています。これらのクラスを使用すると、上記と同様のメッセージング・プラットフォームと直接通信できます。詳細は、上記のリンクを参照してください。)
メッセージング・プラットフォームとの接続
メッセージを送受信するには、コードで以下の各処理を実行する必要があります。
-
プラットフォームとの接続に関する情報を収めた設定オブジェクトを作成します。このオブジェクトは、いずれかの設定クラスのインスタンスです。インターシステムズでは、プラットフォーム固有の各種設定クラスを提供しています。これらはすべて %External.Messaging.SettingsOpens in a new tab のサブクラスです。適用できるクラスのインスタンスを作成し、必要に応じてそのプロパティを設定します。
以下に Kafka での例を挙げます。
Set settings = ##class(%External.Messaging.KafkaSettings).%New() Set settings.username = "amandasmith" Set settings.password = "234sdsge" Set settings.servers = "100.0.70.179:9092, 100.0.70.089:7070" Set settings.clientId = "BazcoApp" // If Consumer, specify a consumer group Set settings.groupId = "G1"
-
同様にプラットフォーム固有のメッセージング・クライアント・オブジェクトを作成します。このオブジェクトは、すべてが %External.Messaging.ClientOpens in a new tab のサブクラスであるクライアント・クラスのいずれかのインスタンスです。
メッセージング・クライアント・オブジェクトを作成するには、%External.Messaging.ClientOpens in a new tab の CreateClient() メソッドを呼び出して、設定オブジェクトを 1 番目の引数として渡します。例えば以下のようにします。
Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC) // if tSC is an error, handle error scenario
このメソッドからは、参照渡しでステータス・コードが 2 番目の引数として返されます。コードでは、このステータスを確認したうえで処理を継続する必要があります。
CreateClient() からは、該当するクライアント・クラスのインスタンスが返されます。例えば、settings 変数が %External.Messaging.KafkaSettingsOpens in a new tab のインスタンスであれば、返されるオブジェクトは %External.Messaging.KafkaClientOpens in a new tab のインスタンスです。
同様に、settings が %External.Messaging.SNSSettingsOpens in a new tab のインスタンスであれば、返されるオブジェクトは %External.Messaging.SNSClientOpens in a new tab のインスタンスです。
トピックまたはキューの作成
メッセージを送信するには、使用しているプラットフォームとの関連性に応じてトピックまたはキューが必要になることがあります。
トピックまたはキューのプラットフォーム固有の設定は文字列として共通メソッドに渡されますが、これらの設定はオブジェクトを使用して定義されています。したがって、この設定を渡すときにはそのオブジェクトの 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 tSC is an error, 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 tSC is an error, handle error scenario
%ListOfObjectsOpens in a new tab のインスタンスである messages に、トピックまたはキューから取得したメッセージが保存されます。
トピックまたはキューの削除
アプリケーションでトピックやキューを必要としなくなった時点で、クライアント・オブジェクトの DeleteTopicOrQueue() メソッドをコードで使用してトピックまたはキューを安全に削除できます。
Do client.DeleteQueueOrTopic(topic)
一部のメッセージング・プラットフォームには、高度な機能を含む可能性のあるトピック/キューを削除するための独自のメソッドがあることに注意してください。
メッセージ・プラットフォームからの切断
メッセージ・プラットフォームとの通信を終了した時点で、コードからクライアント・オブジェクトの Close() メソッドを呼び出します。例えば以下のようにします。
Do:client'="" client.Close()