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

全般的な動作

プロダクション内で、送信アダプタは、ユーザが作成および構成するビジネス・オペレーションに関連付けられます。このビジネス・オペレーションはプロダクション内からメッセージを受信し、メッセージ・タイプを調べ、適切なメソッドを実行します。このメソッドは、通常、関連するアダプタのメソッドを実行します。

電子メール送信アダプタ (EnsLib.EMail.OutboundAdapterOpens in a new tab) には、以下のような項目の指定に使用する設定が用意されています。

• 接続する SMTP サーバ、およびそのサーバに対して必要なログイン情報 (ある場合)

• 電子メール送信元のデフォルト・アドレス (From: ヘッダ)

• ハードコードされた受信者の他に、アダプタが送信するメッセージに追加する受信者

このアダプタは、以下の 3 つのアクションを行うメソッドを提供します。

• To: リストへの受信者の追加

• Cc: リストへの受信者の追加

• メッセージの送信

アダプタを使用するビジネス・オペレーションの作成

EnsLib.EMail.OutBoundAdapter を使用するビジネス・オペレーションを作成するために、新しいビジネス・オペレーション・クラスを作成します。後で、そのクラスをプロダクションに追加して構成します。

存在しなければ、該当するメッセージ・クラスを作成する必要もあります。"Ensemble プロダクションの開発" の “Ensemble メッセージの定義” を参照してください。

ビジネス・オペレーション・クラスの基本要件を以下に列挙します。

• ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。

• クラスの ADAPTER パラメータは EnsLib.EMail.OutboundAdapterOpens in a new tab である必要があります。

• クラスの INVOCATION パラメータは、使用する呼び出しスタイルを指定する必要があります。以下のいずれかを使用します。

  • Queue は、メッセージが 1 つのバックグラウンド・ジョブ内で作成され、元のジョブが解放された段階でキューに配置されます。その後、メッセージが処理された段階で、別のバックグラウンド・ジョブがそのタスクに割り当てられます。これは最も一般的な設定です。

  • InProc は、メッセージが、作成されたジョブと同じジョブで生成、送信、および配信されることを意味します。このジョブは、メッセージが対象に配信されるまで送信者のプールに解放されません。これは特殊なケースのみに該当します。

• クラスでは、少なくとも 1 つのエントリを含むメッセージ・マップを定義します。メッセージ・マップは、以下の構造を持つ XData ブロック・エントリです。

  XData MessageMap
  {
  <MapItems>
    <MapItem MessageType="messageclass">
      <Method>methodname</Method>
    </MapItem>
    ...
  </MapItems>
  }
  
  

  

• クラスでは、メッセージ・マップ内で名前が付けられたすべてのメソッドを定義します。これらのメソッドは、メッセージ・ハンドラと呼ばれます。各メッセージ・ハンドラは、以下のシグニチャを持っている必要があります。

  Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
  

  

  ここで、Sample はメソッド名、RequestClass は Ensemble 要求メッセージ・クラスの名前、ResponseClass は Ensemble 応答メッセージ・クラスの名前です。通常、これらのメソッドは、ビジネス・オペレーションの Adapter プロパティのプロパティおよびメソッドを参照します。

• その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・オペレーション・クラスの定義” を参照してください。

以下の例は、必要となる一般的な構造を示しています。

Class EEMA.NewOperation1 Extends Ens.BusinessOperation 
{
Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method SampleCall(pRequest As Ens.Request,
                  Output pResponse As Ens.Response) As %Status
{
  Quit $$$ERROR($$$NotImplemented)
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="Ens.Request">
    <Method>SampleCall</Method>
  </MapItem>
</MapItems>
}
}

メッセージ・ハンドラ・メソッドの作成

EnsLib.EMail.OutboundAdapterOpens in a new tab で使用するビジネス・オペレーション・クラスを作成する場合の最大のタスクは、通常、このアダプタで使用するメッセージ・ハンドラ、つまり、Ensemble メッセージを受信して SMTP サーバを介して電子メール・メッセージを送信するメソッドの記述です。

各メッセージ・ハンドラ・メソッドは、以下のシグニチャを持っている必要があります。

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status

ここで、Sample はメソッド名、RequestClass は Ensemble 要求メッセージ・クラスの名前、ResponseClass は Ensemble 応答メッセージ・クラスの名前です。

通常、このメソッドは以下の操作を実行します。

1. 受信要求メッセージを調べます。

2. 送信する電子メール・メッセージを作成します。詳細は、この章の “電子メール・メッセージの作成” を参照してください。

3. 任意で、ビジネス・オペレーションの Adapter プロパティの AddRecipients()、AddCcRecipients()、および AddBccRecipients() メソッドを呼び出します。これらのメソッドは、電子メール・メッセージの送信時に、To: ヘッダ、Cc: ヘッダ、および Bcc: ヘッダに電子メール・アドレスを追加します。これらのメソッドについては、後で説明します。

4. ビジネス・オペレーションの Adapter プロパティの SendMessage() メソッドを呼び出します。

       Set tSc=..Adapter.SendMail(email,.pf)
   
   

   

   このメソッドについては、後で説明します。

5. 応答を調べます。

6. 応答内の情報を使用して、Ensemble 応答メッセージ (Ens.ResponseOpens in a new tab またはサブクラスのインスタンス) を作成します。メソッドは出力としてこのメッセージを返します。

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

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

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

使用可能なメソッド

このアダプタは、以下のメソッドを提供します。

SendMail

Method SendMail(pMailMessage As %Net.MailMessage,
                Output pFailedRecipients As %ListOfDataTypes) As %Status

電子メール・メッセージを指定すると、このメソッドは、構成された SMTP サーバを使用して電子メール・メッセージを送信します。SMTP サーバによって失敗した受信者のリストが返されると、このメソッドは、出力として失敗した受信者のリストを返します。

AddRecipients

Method AddRecipients(pMailMessage As %Net.MailMessage,
                     pRecipients As %String)

電子メール・メッセージを指定すると、このメソッドは、メッセージの To: ヘッダに、リストされた電子メール・アドレスを追加します。

AddCcRecipients

Method AddCcRecipients(pMailMessage As %Net.MailMessage,
                       pRecipients As %String)

電子メール・メッセージを指定すると、このメソッドは、メッセージの Cc: ヘッダに、リストされた電子メール・アドレスを追加します。

AddBccRecipients

Method AddBccRecipients(pMailMessage As %Net.MailMessage,
                       pRecipients As %String)

電子メール・メッセージを指定すると、このメソッドは、メッセージの Bcc: ヘッダに、リストされた電子メール・アドレスを追加します。電子メールを送信する際は、To: ヘッダまたは Cc: ヘッダに少なくとも 1 つのアドレスを指定する必要があります。

ContinueAfterBadSendSet

Method ContinueAfterBadSendSet(%val As %Integer) as %Status

%val が真の場合は、1 人以上の受信者のアドレスが無効なときに、アダプタはメッセージの送信を続行します。デフォルトは真です。

例

メソッドは以下のようになります。

Method SendMultipartEmailMessage(pRequest As EEMA.MultipartEmailMsg,
Output pResponse As Ens.Response) As %Status
{
    Set part1=##class(%Net.MailMessage).%New()
    Do part1.TextData.Write(pRequest.Message1)
    Set part2=##class(%Net.MailMessage).%New()
    Do part2.TextData.Write(pRequest.Message2)
    Set part3=##class(%Net.MailMessage).%New()
    Do part3.TextData.Write(pRequest.Message3)

    Set email=##class(%Net.MailMessage).%New()
    Set email.Subject=pRequest.Subject
    Set email.IsMultiPart=1
    Do email.Parts.SetAt(part1,1)
    Do email.Parts.SetAt(part2,2)
    Do email.Parts.SetAt(part3,3)

    Set tSc=..Adapter.SendMail(email,.pf)
    Set pResponse=##class(EEMA.EmailFailedRecipients).%New()
    Set pResponse.FailedRecipients=pf

    if pf.Count()'=""
    {
        set count=pf.Count()
        for i=1:1:count
        {
            $$$TRACE("Failed recipient:"_pf.GetAt(i))
            }
        }

    Quit tSc
}

電子メール・メッセージの作成については、次の節を参照してください。

電子メール・メッセージの作成

メッセージには 1 つまたは複数のパートを含めることができます。各パートにはコンテンツが含まれ、ヘッダを含めることができます。メッセージ自体にもヘッダがあります。以下の節で、次のトピックについて説明します。

• 一般的な電子メール・メッセージの作成方法

• 指定されたメッセージ・パートのコンテンツおよびヘッダを指定する方法

• メッセージおよびそのパートのヘッダを指定する方法

• アタッチメントの追加方法

• 簡単な例

メッセージ・ヘッダの指定

前述したとおり、メッセージ自体およびメッセージの各パートの両方には、一連のヘッダがあります。

%Net.MailMessageOpens in a new tab クラスおよび %Net.MailMessagePartOpens in a new tab クラスは、最も一般的に使用されるヘッダに簡単にアクセスできるようにするプロパティを提供しますが、必要なヘッダを追加することができます。この節では、すべてのヘッダに関する情報を提供すると共に、カスタム・ヘッダの作成方法についても説明します。

Note:

指定されたメッセージ・パートのヘッダは、そのパートの Charset プロパティで指定された文字セットで記述されます。

基本的なヘッダ

以下のプロパティ (%Net.MailMessageOpens in a new tab のみ) を設定し、メッセージ自体の最も一般的に使用されるヘッダを指定します。

• To — (必須) このメッセージの送信先となる電子メール・アドレスのリスト。このプロパティは標準の Caché リストです。これを操作するには、標準リスト・メソッドの Insert()、GetAt()、RemoveAt()、Count()、および Clear() を使用します。

• From — (必須) このメッセージの送信元の電子メール・アドレス。

• Date — このメッセージの日付。

• Subject — このメッセージの件名を含む文字列。

• Sender — メッセージの実際の送信者。

• Cc — このメッセージの送信先となるカーボン・コピー・アドレスのリスト。

• Bcc — このメッセージの送信先となるブラインド・カーボン・コピー・アドレスのリスト。

Note:

使用している SMTP サーバの要件を理解しておく必要があります。例えば、一部の SMTP サーバでは Subject: ヘッダを含める必要があります。同様に、一部の SMTP サーバでは任意の From: ヘッダを許可しない場合があります。

Content-Type ヘッダ

メッセージを送信する場合、メッセージおよび各メッセージ・パートの Content-Type ヘッダは、自動的に以下のように設定されます。

• メッセージがプレーン・テキストの場合 (IsHTML が 0 で IsBinary が 0 の場合)、Content-Type ヘッダは "text/plain" に設定されます。

• メッセージが HTML の場合 (IsHTML が 1 で IsBinary が 0 の場合)、Content-Type ヘッダは "text/html" に設定されます。

• メッセージがバイナリの場合 (IsBinary が 1 の場合)、Content-Type ヘッダは "application/octet-stream" に設定されます。

• メッセージがマルチパートの場合 、Content-Type ヘッダは MultiPartType プロパティの値に対して適切に設定されます。

%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab は共に、ContentType プロパティを提供します。このプロパティは、Content-Type ヘッダへのアクセスを提供します。

Content-Transfer-Encoding ヘッダ

%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab は共に、ContentTransferEncoding プロパティを提供します。このプロパティは、メッセージまたはメッセージ・パートの Content-Transfer-Encoding ヘッダを簡単に指定する方法を提供します。

このプロパティは、"base64"、"quoted-printable"、"7bit"、"8bit" のいずれかです。

デフォルトは以下のとおりです。

• バイナリのメッセージまたはメッセージ・パートには、"base64" を使用します。

• テキストのメッセージまたはメッセージ・パートには、"quoted-printable" を使用します。

カスタム・ヘッダ

%Net.MailMessageOpens in a new tab および %Net.MailMessagePartOpens in a new tab の両方を使用して、Headers プロパティにアクセスすることにより、カスタム・ヘッダを設定または取得できます。このプロパティは、以下の構造を持つ配列です。

配列キー	配列の値
"Priority" など、ヘッダの名前	ヘッダの値

このプロパティを使用して、優先順位などの追加のヘッダを含めます。以下に例を示します。

 Do msg.Headers.SetAt("Urgent","Priority")

アタッチメントの追加

電子メールのメッセージまたはメッセージ・パートにアタッチメントを追加できます。そのためには、%Net.MailMessagePartOpens in a new tab または %Net.MailMessageOpens in a new tab の以下のメソッドを使用します。

これらの各メソッドは、元のメッセージ (またはメッセージ・パート) の Parts 配列にアタッチメントを追加し、自動的に IsMultiPart プロパティを 1 に設定します。

AttachFile

method AttachFile(Dir As %String,
                  File As %String,
                  isBinary As %Boolean = 1,
                  charset As %String = "",
                  ByRef count As %Integer) as %Status

指定されたファイルを電子メール・メッセージに添付します。デフォルトでは、ファイルはバイナリ・アタッチメントとして送信されますが、代わりにテキストとして指定することができます。また、このファイルがテキストの場合、ファイルが使用する文字セットを指定することもできます。(Caché 内の文字変換に関する背景情報は、"Caché プログラミング入門ガイド" の “ローカリゼーション・サポート” を参照してください)。

具体的には、このメソッドは %Net.MailMessagePartOpens in a new tab のインスタンスを作成し、BinaryData または TextData プロパティ内のファイルのコンテンツを適切に配置し、Charset プロパティおよび TextData.TranslateTable プロパティを必要に応じて設定します。このメソッドは、Parts 配列内のこの新しいメッセージ・パートの位置を示す整数を、参照渡しで返します。

このメソッドは、メッセージまたはメッセージ・パートの Dir プロパティおよび FileName プロパティも設定します。

AttachNewMessage

method AttachNewMessage() as %Net.MailMessagePart

%Net.MailMessageOpens in a new tab の新しいインスタンスを作成し、メッセージに追加して、新しく修正された親のメッセージまたはメッセージ・パートを返します。

AttachEmail

method AttachEmail(mailmsg As %Net.MailMessage)

電子メール・メッセージ (%Net.MailMessageOpens in a new tab のインスタンス) を指定すると、このメソッドは、それをメッセージに追加します。

Note:

このメソッドは、ContentType を "message/rfc822" に設定します。この場合、他のアタッチメントを追加することはできません。

例については、%Net.MailMessagePartOpens in a new tab のクラス参照を参照してください。

例

以下に例を示します。

ClassMethod CreateTextMessage() As %Net.MailMessage
{
    Set msg = ##class(%Net.MailMessage).%New()
    set msg.From = "test@test.com"
    Do msg.To.Insert("xxx@xxx.com")
    Do msg.Cc.Insert("yyy@yyy.com")
    Do msg.Bcc.Insert("zzz@zzz.com")
    Set msg.Subject="subject line here"
    Set msg.IsBinary=0
    Set msg.IsHTML=0
    Do msg.TextData.Write("This is the message.")

    Quit msg
}

SAMPLES ネームスペースに、2 つの例があります。それらを見つけるには、このネームスペースで %Net.MailMessage を検索してください。

例

この節では、文字列コンテンツを含むシングルパートまたはマルチパートの電子メール・メッセージを送信する例を示します。プロダクション・システムでは、文字列の代わりにストリームを使用する場合もあります。ただし、この例では文字列を使用するので、Ensemble テスト・ページを使用して簡単にテストできます。

まず、シングルパート・メッセージの要求メッセージ・クラスは、以下のようになります。

Class EEMA.SimpleMsg Extends Ens.Request
{

Property Subject As %Text(MAXLEN = 100);

Property Message As %Text(MAXLEN = 5000);

}

次は、マルチパート・メッセージの要求メッセージ・クラスです。このクラスには、3 パートのメッセージを含めることができます。

Class EEMA.MultipartMsg Extends Ens.Request
{

Property Subject As %Text(MAXLEN = 100);

Property Part1 As %Text(MAXLEN = 5000);

Property Part2 As %Text(MAXLEN = 5000);

Property Part3 As %Text(MAXLEN = 5000);

}

以下のビジネス・オペレーションは、これらのメッセージのいずれかを受け取り、適切な電子メール・メッセージを作成して、構成された SMTP サーバを介して送信します。

Class EEMA.EmailOperation Extends Ens.BusinessOperation
{

Parameter ADAPTER = "EnsLib.EMail.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method SendSimpleMessage(pRequest As EEMA.SimpleMsg,
Output pResponse As Ens.Response) As %Status
{
    Set email=##class(%Net.MailMessage).%New()

    //Get info from pReq
    Do email.TextData.Write(pRequest.Message)
    Set email.Subject=pRequest.Subject

    //simple case--do not check for failed recipients
    Set tSc=..Adapter.SendMail(email)

    //send an empty response message after message is sent
    Set pResponse=##class(Ens.Response).%New()

    ;Quit tSc
}

Method SendMultipartEmailMessage(pRequest As EEMA.MultipartMsg,
Output pResponse As Ens.Response) As %Status
{
    Set part1=##class(%Net.MailMessage).%New()
    Do part1.TextData.Write(pRequest.Part1)
    Set part2=##class(%Net.MailMessage).%New()
    Do part2.TextData.Write(pRequest.Part2)
    Set part3=##class(%Net.MailMessage).%New()
    Do part3.TextData.Write(pRequest.Part3)

    Set email=##class(%Net.MailMessage).%New()
    Set email.Subject=pRequest.Subject
    Set email.IsMultiPart=1
    Do email.Parts.SetAt(part1,1)
    Do email.Parts.SetAt(part2,2)
    Do email.Parts.SetAt(part3,3)

    //simple case--do not check for failed recipients
    Set tSc=..Adapter.SendMail(email)

    //send an empty response message after message is sent
    Set pResponse=##class(Ens.Response).%New()

    Quit tSc
}

XData MessageMap
{
<MapItems>
    <MapItem MessageType="EEMA.SimpleMsg">
        <Method>SendSimpleMessage</Method>
    </MapItem>
    <MapItem MessageType="EEMA.MultipartMsg">
        <Method>SendMultipartEmailMessage</Method>
    </MapItem>
</MapItems>
}

}

ビジネス・オペレーションの追加と構成

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

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

2. ビジネス・オペレーションを有効化します。

3. SMTP メール・サーバとそれにアクセスするために必要な認証情報を指定します。

4. 任意で、電子メール・メッセージの追加のアドレスを指定します。

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