電子メール受信アダプタの使用法

全般的な動作

まず、アダプタに対して指定する詳細について理解しておくと役立ちます。EnsLib.EMail.InboundAdapterOpens in a new tab クラスには、以下のような項目の指定に使用する実行時設定が用意されています。

• 使用する POP3 サーバ、およびメッセージが格納されるメールボックスに対するログイン情報

• 対象のメッセージを指定する一致条件

• アダプタが新規入力をチェックする頻度を制御する、ポーリング間隔

通常、受信電子メール・アダプタ (EnsLib.EMail.InboundAdapterOpens in a new tab) は定期的にメールボックスをチェックし、条件に一致するものを検索し、(%Net.MailMessageOpens in a new tab のインスタンスとして) 関連するビジネス・サービスにメッセージを送信し、電子メール・サーバからそのメッセージを削除します。ユーザが作成および構成するビジネス・サービスでは、このメッセージを使用してプロダクションの他の部分と通信します。以下の図は、全体的なフローを示しています。

さらに具体的に説明します。

1. アダプタは定期的に OnTask() メソッドを実行します。このメソッドは、特定のユーザ名とパスワードを使用して、POP3 サーバに接続してログオンします。ポーリング間隔は CallInterval 設定によって決定されます。

2. アダプタはこのメールボックス内のすべてのメッセージを調べ、一致条件と比較します。

3. アダプタは、条件に一致するメッセージを見つけると、以下を実行します。

   1. アダプタは %Net.MailMessageOpens in a new tab クラスのインスタンスを作成し、電子メール・データをインスタンスに入れます。

   2. アダプタは、関連するビジネス・サービス・クラスの内部 ProcessInput() メソッドを呼び出し、%Net.MailMessageOpens in a new tab インスタンスを入力として渡します。

   3. アダプタは、サーバからメール・メッセージを削除します。

4. ビジネス・サービス・クラスの内部 ProcessInput() メソッドが実行されます。このメソッドは、すべてのビジネス・サービスが必要とする内部情報の保持など、基本的な Ensemble タスクを実行します。ビジネス・サービス・クラスが継承するこのメソッドは、カスタマイズや上書きを行いません。

5. 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
}
}

OnProcessInput() メソッドの実装

カスタム・ビジネス・サービス・クラスにおいて、OnProcessInput() メソッドは以下のシグニチャを持つ必要があります。

Method OnProcessInput(pInput As %Net.MailMessage,
                      pOutput As %RegisteredObject) As %Status

ここで、pInput は、アダプタがこのビジネス・サービスに送信する電子メール・メッセージ・オブジェクトです。これは %Net.MailMessageOpens in a new tab のインスタンスです。また、pOutput は、メソッド・シグニチャに必要な汎用出力引数です。

OnProcessInput() メソッドは、以下の一部またはすべてを実行する必要があります。

1. 電子メール・メッセージを調べて、それをどのように使用するかを決定します。

   電子メール・メッセージの構造はさまざまであり、それぞれ異なる処理が必要です。まず、メッセージの構造が期待どおりであることを確認したい場合があります。つまり、マルチパート・メッセージであるかどうか、また、各パートがバイナリかどうかを確認します。詳細は、“電子メール・メッセージの使用法” を参照してください。

2. メッセージの構造が確認できたら、%Net.MailMessageOpens in a new tab の別のプロパティを使用してメッセージ本文またはヘッダにアクセスします。“電子メール・メッセージの使用法” を参照してください。

3. ビジネス・サービスから送信される要求メッセージのインスタンスを作成します。

   メッセージ・クラスの作成方法は、"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。

4. 要求メッセージに対し、電子メール・メッセージの値を使用して適切にプロパティを設定します。

5. ビジネス・サービスの適切なメソッドを呼び出して、要求をプロダクション内の宛先に送信します。具体的には、SendRequestSync()、SendRequestAsync()、または (あまり一般的ではない) SendDeferredResponse() を呼び出します。詳細は、"Ensemble プロダクションの開発" の “要求メッセージの送信” を参照してください。

   これらの各メソッドは、ステータス (具体的には、%StatusOpens in a new tab のインスタンス) を返します。

6. 必ず出力引数 (pOutput) を設定します。通常、受信した応答メッセージと同じように設定します。この手順は必須です。

7. 適切なステータスを返します。この手順は必須です。

簡単な例を以下に示します。

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 のさまざまなプロパティを介してヘッダにアクセスできます。

ビジネス・サービスの追加と構成

ビジネス・サービスを Ensemble プロダクションに追加するには、管理ポータルを使用して以下の操作を行います。

1. カスタム・ビジネス・サービス・クラスのインスタンスを Ensemble プロダクションに追加します。

2. ビジネス・サービスを有効化します。

3. POP3 メール・サーバにアクセスしてメッセージをダウンロードするアダプタを構成します。具体的には、以下を行います。

   • メールボックスにアクセスするために必要な、POP3 メール・サーバ情報およびログイン情報を指定します。

   • ダウンロードするメッセージを決定するための条件を指定します。

   • Call Interv\al を使用してアダプタが電子メールを検索する頻度を指定します。

4. プロダクションを実行します。