電子メール受信アダプタの使用法
この章では、Ensemble 電子メール受信アダプタ (EnsLib.EMail.InboundAdapterOpens in a new tab) のデフォルトの動作とプロダクションでのこのアダプタの使用方法について説明します。以下のトピックについて説明します。
このドキュメントに記載されていない設定は、"Ensemble プロダクションの管理" の “すべてのプロダクションに含まれる設定” を参照してください。
全般的な動作
まず、アダプタに対して指定する詳細について理解しておくと役立ちます。EnsLib.EMail.InboundAdapterOpens in a new tab クラスには、以下のような項目の指定に使用する実行時設定が用意されています。
-
使用する POP3 サーバ、およびメッセージが格納されるメールボックスに対するログイン情報
-
対象のメッセージを指定する一致条件
-
アダプタが新規入力をチェックする頻度を制御する、ポーリング間隔
通常、受信電子メール・アダプタ (EnsLib.EMail.InboundAdapterOpens in a new tab) は定期的にメールボックスをチェックし、条件に一致するものを検索し、(%Net.MailMessageOpens in a new tab のインスタンスとして) 関連するビジネス・サービスにメッセージを送信し、電子メール・サーバからそのメッセージを削除します。ユーザが作成および構成するビジネス・サービスでは、このメッセージを使用してプロダクションの他の部分と通信します。以下の図は、全体的なフローを示しています。
さらに具体的に説明します。
-
アダプタは定期的に OnTask() メソッドを実行します。このメソッドは、特定のユーザ名とパスワードを使用して、POP3 サーバに接続してログオンします。ポーリング間隔は CallInterval 設定によって決定されます。
-
アダプタはこのメールボックス内のすべてのメッセージを調べ、一致条件と比較します。
-
アダプタは、条件に一致するメッセージを見つけると、以下を実行します。
-
アダプタは %Net.MailMessageOpens in a new tab クラスのインスタンスを作成し、電子メール・データをインスタンスに入れます。
-
アダプタは、関連するビジネス・サービス・クラスの内部 ProcessInput() メソッドを呼び出し、%Net.MailMessageOpens in a new tab インスタンスを入力として渡します。
-
アダプタは、サーバからメール・メッセージを削除します。
-
-
ビジネス・サービス・クラスの内部 ProcessInput() メソッドが実行されます。このメソッドは、すべてのビジネス・サービスが必要とする内部情報の保持など、基本的な Ensemble タスクを実行します。ビジネス・サービス・クラスが継承するこのメソッドは、カスタマイズや上書きを行いません。
-
ProcessInput() メソッドがカスタムの OnProcessInput() メソッドを呼び出し、%Net.MailMessageOpens in a new tab インスタンスを入力として渡します。このメソッドの要件については、後出の “OnProcessInput() メソッドの実装” で説明します。
応答メッセージは、同じパスを逆向きにたどります。
電子メール受信アダプタを使用するビジネス・サービスの作成
このアダプタをプロダクションで使用するには、ここに記載されているように新しいビジネス・サービス・クラスを作成します。後で、そのサービス・クラスをプロダクションに追加して構成します。存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。
ビジネス・サービス・クラスの基本要件を以下に列挙します。
-
ビジネス・サービス・クラスは Ens.BusinessServiceOpens in a new tab を拡張するものでなければなりません。
-
クラスの ADAPTER パラメータは EnsLib.EMail.InboundAdapterOpens in a new tab である必要があります。
-
クラスには OnProcessInput() メソッドを実装する必要があります。これについては、“OnProcessInput() メソッドの実装” で説明します。
-
その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・サービス・クラスの定義” を参照してください。
以下の例は、必要となる一般的な構造を示しています。
Class EEMA.EmailService Extends Ens.BusinessService
{
Parameter ADAPTER = "EnsLib.EMail.InboundAdapter";
Method OnProcessInput(pInput As %Net.MailMessage,
pOutput As %RegisteredObject) As %Status
{
set tsc=$$$OK
//your code here
Quit tsc
}
}
スタジオには、上記のようなビジネス・サービス・スタブの作成に使用できるウィザードが用意されています。このウィザードにアクセスするには、[ファイル]→[新規作成] をクリックし、[プロダクション] タブをクリックします。次に [ビジネス・サービス] をクリックして [OK] をクリックします。このウィザードには、汎用入力引数が用意されています。ウィザードを使用する場合は、このアダプタに必要な特定の入力引数を使用するためにメソッド・シグニチャを編集することをお勧めします。入力引数のタイプは %Net.MailMessageOpens in a new tab です。
OnProcessInput() メソッドの実装
カスタム・ビジネス・サービス・クラスにおいて、OnProcessInput() メソッドは以下のシグニチャを持つ必要があります。
Method OnProcessInput(pInput As %Net.MailMessage,
pOutput As %RegisteredObject) As %Status
ここで、pInput は、アダプタがこのビジネス・サービスに送信する電子メール・メッセージ・オブジェクトです。これは %Net.MailMessageOpens in a new tab のインスタンスです。また、pOutput は、メソッド・シグニチャに必要な汎用出力引数です。
OnProcessInput() メソッドは、以下の一部またはすべてを実行する必要があります。
-
電子メール・メッセージを調べて、それをどのように使用するかを決定します。
電子メール・メッセージの構造はさまざまであり、それぞれ異なる処理が必要です。まず、メッセージの構造が期待どおりであることを確認したい場合があります。つまり、マルチパート・メッセージであるかどうか、また、各パートがバイナリかどうかを確認します。詳細は、“電子メール・メッセージの使用法” を参照してください。
-
メッセージの構造が確認できたら、%Net.MailMessageOpens in a new tab の別のプロパティを使用してメッセージ本文またはヘッダにアクセスします。“電子メール・メッセージの使用法” を参照してください。
-
ビジネス・サービスから送信される要求メッセージのインスタンスを作成します。
メッセージ・クラスの作成方法は、"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。
-
要求メッセージに対し、電子メール・メッセージの値を使用して適切にプロパティを設定します。
-
ビジネス・サービスの適切なメソッドを呼び出して、要求をプロダクション内の宛先に送信します。具体的には、SendRequestSync()、SendRequestAsync()、または (あまり一般的ではない) SendDeferredResponse() を呼び出します。詳細は、"Ensemble プロダクションの開発" の “要求メッセージの送信” を参照してください。
これらの各メソッドは、ステータス (具体的には、%StatusOpens in a new tab のインスタンス) を返します。
-
必ず出力引数 (pOutput) を設定します。通常、受信した応答メッセージと同じように設定します。この手順は必須です。
-
適切なステータスを返します。この手順は必須です。
簡単な例を以下に示します。
Method OnProcessInput(pInput As %Net.MailMessage,
pOutput As %RegisteredObject) As %Status
{
//Check if mail message has multiple parts
Set multi=pInput.IsMultiPart
If multi
{$$$TRACE("This message has multiple parts; not expected")
Quit $$$ERROR($$$GeneralError,"Message has multiple parts")
}
//Check if mail message is binary
Set bin=pInput.IsBinary
If bin
{$$$TRACE("This message is binary; not expected")
Quit $$$ERROR($$$GeneralError,"Message is binary")
}
//Check if mail message is HTML
Set html=pInput.IsHTML
If html
{$$$TRACE("This message is HTML not expected")
Quit $$$ERROR($$$GeneralError,"Message is HTML")
}
//now safe to get text of message
Set pReq=##class(EEMA.EmailContents).%New()
Set pReq.MessageText=pInput.TextData
Set tSc=..SendRequestSync("EEMA.EmailProcessor",pReq,.pResp)
Set pOutput=pResp
Quit tSc
}
電子メール・メッセージの使用法
前述したとおり、電子メール・メッセージ (%Net.MailMessageOpens in a new tab) を取得した後、通常はメッセージの種類とメッセージを読む方法を確認します。つまり、マルチパート・メッセージかどうか、および各パートがバイナリかどうかを判断します。
この手順では ContentType プロパティを使用できます。このプロパティは、Content-Type プロパティと同じです。または、IsBinary、IsHTML、および IsMultiPart プロパティを使用できます。これらのプロパティは、ContentType と同じ情報を間接的に提供します。
メッセージがマルチパート・メッセージの場合、各パートは %Net.MailMessagePartOpens in a new tab のインスタンスです。
メッセージにはメッセージ・ヘッダがあります。メッセージの各パートにメッセージ・ヘッダがある場合もあります。%Net.MailMessageOpens in a new tab や %Net.MailMessagePartOpens in a new tab のさまざまなプロパティを介してヘッダにアクセスできます。
メッセージ・コンテンツ
全般的なメッセージ構造がわかったら、以下の方法でコンテンツを取得します。
-
マルチパート・メッセージの場合は、Parts プロパティを使用します。これはパートの配列です。Count() メソッドを使用してパート数を取得します。GetAt() メソッドを使用して指定されたパートを取得します。各パートのキーは整数で、最初のパートは 1 から始まります。
-
バイナリ・メッセージ (またはメッセージ・パート) には、BinaryData プロパティを使用します。
-
テキスト・メッセージ (またはメッセージ・パート) には、TextData プロパティを使用します。
-
IsHTML が 0 の場合、TextData プロパティは通常のテキスト文字列です。
-
IsHTML が 1 の場合、TextData プロパティは HTML テキスト文字列です。
-
メッセージを送信する電子メール・クライアントが、メッセージ内のラッピングを判断します。メール・サーバも Caché もこれを制御できません。
メッセージ・ヘッダ
メッセージ自体およびメッセージの各パートには、一連のヘッダがあります。
%Net.MailMessageOpens in a new tab クラスは、最も一般的に使用されるヘッダ用のプロパティを提供します。
-
To — このメッセージの送信先の電子メール・アドレスのリスト。このプロパティは標準の Caché リストです。これを操作するには、標準リスト・メソッドの Insert()、GetAt()、RemoveAt()、Count()、および Clear() を使用します。
-
From — このメッセージの送信元の電子メール・アドレス。
-
Date — このメッセージの日付。
-
Subject — このメッセージの件名を含む文字列。
-
Sender — メッセージの実際の送信者。
-
Cc — このメッセージの送信先のカーボン・コピー・アドレスのリスト。
-
Bcc — このメッセージの送信先のブラインド・カーボン・コピー・アドレスのリスト。メッセージの受信者がブラインド・カーボン・コピー・リストに記載されている場合、このプロパティにはその受信者のアドレスが含まれます。それ以外の場合は NULL です。
%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab は共に、以下のプロパティを提供します。これらのプロパティは、その他のヘッダを提供します。
-
ContentType — メッセージまたはメッセージ・パートの Content-Type ヘッダ。
-
ContentTransferEncoding — メッセージまたはメッセージ・パートの Content-Transfer-Encoding ヘッダ。
-
Headers — 任意の追加ヘッダへのアクセスを提供する、多次元配列。
また、GetAttribute() メソッドも使用できます。ヘッダ名と属性を指定すると、このメソッドはその属性の値を返します。
その他のメッセージ情報
以下のプロパティおよびメソッドは、メッセージに関する追加情報を提供します。
-
MessageSize プロパティは、付加された電子メール・メッセージを除く、メッセージの全長を示します。
-
GetLocalDateTime() メソッドは、メッセージが取得された日時を返します。$HOROLOG 形式で現地時刻に変換されます。
-
GetUTCDateTime() メソッドは、メッセージが取得された日時を返します。$HOROLOG 形式で UTC に変換されます。
-
GetUTCSeconds() メソッドは、メッセージが取得された日時を返します。1840 年 12 月 31 日からの経過秒数で表されます。
-
HToSeconds() クラス・メソッドは、$HOROLOG 形式の日時を 1840 年 12 月 31 日からの経過秒数に変換します。
-
SecondsToH() クラス・メソッドは、1840 年 12 月 31 日からの経過秒数を $HOROLOG 形式の日時に変換します。
ビジネス・サービスの追加と構成
ビジネス・サービスを Ensemble プロダクションに追加するには、管理ポータルを使用して以下の操作を行います。
-
カスタム・ビジネス・サービス・クラスのインスタンスを Ensemble プロダクションに追加します。
-
ビジネス・サービスを有効化します。
-
POP3 メール・サーバにアクセスしてメッセージをダウンロードするアダプタを構成します。具体的には、以下を行います。
-
Call Interv\al を使用してアダプタが電子メールを検索する頻度を指定します。
-
プロダクションを実行します。
POP3 サーバへのログイン方法の指定
以下の設定に対して値を指定し、ログオンする POP3 サーバ、およびメールボックスにアクセスするためのセキュリティ情報を指定します。
例えば、以下のような値を使用できます。
設定 | 値 |
---|---|
POP3サーバ | pop.hotpop.com |
POP3ポート | 110 |
Credentials | hotpop |
この例にある hotpop は、ユーザ名 isctest@hotpop.com とこれに対応するパスワードから成る Ensemble 資格情報 の ID です。
取得するメッセージの指定
以下の設定に対して値を指定し、取得するメッセージを制御します。指定された条件にすべて一致するメッセージのみが使用されます。条件の照合では大文字と小文字が区別されます。
これらの条件を変更すると、アダプタは、以前は条件に一致しなかったメッセージを調べ、必要に応じて処理します。