Amazon SQS メッセージング API の使用法
インターシステムズでは、Amazon Simple Queue Service (SQS) によるメッセージの作成と利用に使用できる API を用意しています。コードは、クライアントを作成した後、メッセージの送信または受信のアクションを実行する、そのクライアントのメソッドを呼び出すことにより、メッセージのプロデューサまたはコンシューマとして機能します。InterSystems IRIS も、Amazon SQS のキューを作成するメソッドと削除するメソッドを提供しています。
Amazon SQS API は、他のメッセージング・プラットフォームと共有する共通のメッセージング・クラスを基本としています。このページでは、このような共通のクラスで確立されているワークフローに対し、プラットフォーム固有で発生するバリエーションについて説明します。
インターシステムズでは、ここで説明している API のほか、相互運用プロダクションの過程で Amazon SQS へのメッセージ送信と Amazon SQS からのメッセージ取得に使用できる専用のクラスを用意しています。
Amazon SQS への接続
Amazon SQS との接続を作成するには以下の手順に従います。
-
設定オブジェクトを作成します。そのためには、%External.Messaging.SQSSettingsOpens in a new tab のインスタンスを作成し、そのプロパティを以下のように設定します。
-
credentialsFile :Amazon Simple Storage Service (S3) の認証情報ファイルが保存されている場所を指定した文字列。
-
accessKey :使用している Amazon S3 アクセス キーを記述した文字列。credentialsFile を指定していれば、このプロパティの設定は不要です。
-
secretKey :使用している Amazon S3 秘密鍵を記述した文字列。credentialsFile を指定していれば、このプロパティの設定は不要です。
-
sessionToken :使用している Amazon S3 セッション・トークンを記述した文字列。セッション・トークンを記述した credentialsFile を指定していれば、このプロパティの設定は不要です。
-
region :Amazon S3 のリージョンを指定した文字列。
例えば以下のようにします。
Set settings = ##class(%External.Messaging.SQSSettings).%New() Set settings.credentialsFile = "~/.aws/credentials/cred.ini" Set settings.region = "us-east-1"
-
-
メッセージング・クライアント・オブジェクトを作成します。そのためには、汎用 %External.Messaging.ClientOpens in a new tab クラスの CreateClient() メソッドを呼び出し、設定オブジェクトを 1 番目の引数として渡します。例えば以下のようにします。
Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC) If $$$ISERR(tSC) { //handle error scenario }
このメソッドからは、参照渡しでステータス・コードが 2 番目の引数として返されます。コードでは、このステータスを確認したうえで処理を継続する必要があります。
settings オブジェクトは %External.Messaging.SQSSettingsOpens in a new tab のインスタンスなので、返されるオブジェクト (client) は %External.Messaging.SQSClientOpens in a new tab のインスタンスです。
Amazon SQS プロデューサ
InterSystems IRIS は、メッセージを作成する API メソッドを呼び出し、作成したメッセージを送信することにより、Amazon SQS パブリッシャとして機能できます。メッセージの送信先とするトピックをアプリケーションで作成する必要がある場合は、"キューの操作" を参照してください。以下のフローでは、クライアント・オブジェクトを使用し、パブリッシャとして Amazon SQS を操作しています。
Amazon SQS メッセージ属性を使用してメッセージにカスタム・メタデータを添付するには、SQS メッセージ属性オブジェクトの InterSystems IRIS %ListOfObjects Opens in a new tabコレクションを作成する必要があります。次のセクションで作成する Amazon SQS メッセージ・オブジェクトでは、この属性のコレクション (一覧) をオプションのプロパティとして受け入れます。属性ごとに以下を定義します。
-
%External.Messaging.SQSMessageAttributeOpens in a new tab オブジェクトの新しいインスタンスを作成します。
-
次のように、このメッセージ属性オブジェクトのプロパティを設定します。
-
key :メッセージ属性キー
-
dataType :メッセージ属性値のデータ型 ("String"、"Number"、または "Binary")
-
stringValue または binaryValue :メッセージ属性値。指定したデータ型に適切な方のプロパティを設定します。
-
-
メッセージ属性オブジェクトの一覧に、各メッセージ属性オブジェクトを追加します。
メッセージ属性の詳細は、Amazon SQS メッセージ・メタデータのドキュメントOpens in a new tabを参照してください。以下の例ではタイム・スタンプ属性を作成しています。
Set attrList = ##class(%ListOfObjects).%New()
Set key = "timestamp"
Set dataType = "String"
Set value = $zdatetime($horolog)
Set msgAttr1 = ##class(%External.Messaging.SQSMessageAttribute).%New()
Set msgAttr1.key = key
Set msgAttr1.dataType = dataType
Set msg.stringValue = value
Set tSC = attrList.Insert(msgAttr1)
送信するメッセージを作成するには、%External.Messaging.SQSMessageOpens in a new tab オブジェクトの新しいインスタンスを作成します。つづいて、そのメッセージ・オブジェクトのプロパティを定義します。メッセージの送信先名である queue とメッセージの body を指定する必要があります。前のセクションで説明したカスタム・メッセージ属性を定義している場合は、messageAttributes プロパティとしてメッセージ属性オブジェクトの一覧を指定します。例えば以下のようにします。
Set queue = "quick-start-events"
Set body = "MyMessage"
Set msg = ##class(%External.Messaging.SQSMessage).%New()
Set msg.queue = queue
Set msg.body = body
Set msg.messageAttributes = attrList
作成したメッセージは、Amazon SQS クライアント・オブジェクトの SendMessage() メソッドを実行することにより、トピックに送信できます:
set tSC = client.SendMessage(msg)
if $$$ISERR(tSC) {
//handle error scenario
}
Amazon SQS コンシューマ
InterSystems IRIS は、トピックのメッセージを取得する API メソッドを呼び出すことにより、Amazon SQS コンシューマとして機能できます。以下のフローでは、クライアント・オブジェクトを使用し、コンシューマとして Amazon SQS を操作しています。
Amazon SQS クライアントは、ReceiveMessage() メソッドを使用して Amazon SQS コンシューマとして機能できます。このメソッドでは、JSON 形式の文字列をオプションの引数として指定することで、メッセージ取得操作の設定を指定できます。そのためには、%External.Messaging.SQSReceiveSettingsOpens in a new tab クラスの新しいインスタンスを作成し、必要に応じてそのプロパティを設定します。利用できるプロパティは以下のとおりです。
-
maxNumberOfMessages :返すメッセージの最大数を指定した整数
-
waitTimeSeconds :ポーリングがタイムアウトするまでの時間 (秒数) を指定した整数
-
visibilityTimeout :メソッドから返されたメッセージを他のコンシューマが実質的に確認できる時間 (秒数) を指定した整数
例えば以下のようにします。
Set rset = ##class(%External.Messaging.SQSReceiveSettings).%New()
Set rset.waitTimeSeconds = 5
Set rset.visibilityTimeout = 30
メッセージを取得するには、Amazon SQS クライアント・オブジェクトが継承した ReceiveMessage() メソッドを呼び出します。このメソッドは、キューの名前を引数として取り、参照渡しで %ListOfObjectsOpens in a new tab としてメッセージを返します。前のセクションで説明したメッセージ取得設定を指定している場合は、ToJSON() メソッドを使用して、その設定を 3 番目の引数として指定します。例えば以下のようにします。
#dim messages As %ListOfObjects
Set tSC = client.ReceiveMessage(queue, .messages, rset.ToJSON())
キューのメッセージを受信して処理した Amazon SQS コンシューマは、キューからそのメッセージを削除する必要があります。メッセージを削除するには、クライアント・オブジェクトの DeleteMessage() メソッドを呼び出します。DeleteMessage() では、キューの名前を 1 番目の引数、メッセージの受信ハンドルを 2 番目の引数としてそれぞれ指定する必要があります。受信ハンドルは、ReceiveMessage() メソッドから返された、メッセージごとの receiptHandle プロパティに保存されています。
For i=1:1:messages.Size {
Set msg = messages.GetAt(i)
Write "Message: ", msg.ToJSON(), !
Set tSC = client.DeleteMessage(queue, msg.receiptHandle)
}
キューの操作
InterSystems IRIS は、Amazon SQS キューの作成と削除に使用できる API を提供します。
キューの設定を指定する場合は、%External.Messaging.SQSQueueSettings オブジェクトを作成し、そのオブジェクトのプロパティのうち、目的の設定に対応するものを設定します。使用できる構成オプションの詳細は、Amazon SQS のドキュメントOpens in a new tabを参照してください。
例えば、以下のコードでは、先入れ先出しキューを指定するキュー設定オブジェクトを作成し、そのキューへ 5 秒間の遅延ですべてのメッセージを配信します。
Set queueSet = ##class(%External.Messaging.SQSQueueSettings).%New()
Set queueSet.FifoQueue = 1
Set queueSet.DelaySeconds = 5
キューを作成するには、クライアント・オブジェクトの CreateQueue() メソッドを呼び出します。CreateQueue() では、キュー名を引数で指定する必要があります。前のセクションの説明にあるようにキューのキュー設定オブジェクトを作成していれば、そのオブジェクトを 2 番目のオプションの引数として指定できます。
Set queue = "quick-start-events"
Set tSC = client.CreateQueue(queue, queueSet)
また、すべてのメッセージング・プラットフォームに共通のメソッドを使用して、キューを作成することもできます。この代替手法を使用する場合は、ToJSON() メソッドを使用して、キュー設定オブジェクトのコンテンツを JSON オブジェクトとして指定できます。詳細は、"%External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab" を参照してください。
アプリケーションで クライアント・オブジェクトの DeleteTopic() メソッドを呼び出すことで、Amazon SQS キューを削除できます。このメソッドは、キューの名前を引数として受け入れます。
Set tSC = client.DeleteQueue(queue)
また、すべてのメッセージング・プラットフォームに共通のメソッドを使用して、キューを削除することもできます。詳細は、"%External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab" を参照してください。
クライアントの終了
Amazon SQS との通信を完了した InterSystems IRIS アプリケーションは、Close() メソッドを使用してクライアントを閉じる必要があります。例えば以下のようにします。
Do:client'="" client.Close()