Email Connector のトラブルシューティング - Mule 4

メール用 Anypoint Connector (Email Connector) のトラブルシューティングを行うには、アプリケーションログ、JavaMail のデバッグ、添付ファイルへのアクセスのトラブルシューティング、プロトコルの問題のトラブルシューティング、一般的なメッセージの解釈に関する情報を理解しておいてください。

アプリケーションログの表示

Mule Runtime Engine (Mule) アプリケーションの実行中に問題が発生した場合は、次のようにアプリケーションログを参照してください。

  • アプリケーションを Anypoint Platform から実行している場合、出力は Anypoint Studio のコンソールウィンドウに表示される。

  • コマンドラインから Mule を使用してアプリケーションを実行している場合、アプリケーションログは OS コンソールに表示される。

アプリケーションのログファイル ​log4j2.xml​ でログファイルパスがカスタマイズされていない場合、デフォルトの場所 ​MULE_HOME/logs/<app-name>.log​ でアプリケーションログを参照します。

JavaMail デバッグログを有効化する

JavaMail デバッグログは、基盤となるサードパーティクラスで使用されます。

JavaMail デバッグログを有効化する手順は、次のとおりです。

  1. Anypoint Studio にアクセスし、​[Package Explorer]​ ビューに移動します。

  2. アプリケーションのプロジェクト名を開きます。

  3. src/main/mule​ パスフォルダーを開きます。

  4. フォルダー内の Mule アプリケーション XML ファイルを開きます。

  5. <property key="mail.debug" value="true"/>​ を IMAP または SMTP 接続要素に追加します。

      <email:imaps-connection host="..." user="..." password="..." >
        <email:properties >
          <email:property key="mail.debug" value="true" />
        </email:properties>
      </email:imaps-connection>
  6. 変更を保存します。

  7. Package Explorer​ でプロジェクト名をクリックし、​[Run (実行)]​ > ​[Run As (別のユーザーとして実行)]​ > ​[Mule Application (Mule アプリケーション)]​ をクリックします。

  8. [Console (コンソール)]​ ビューに移動してロガー内のメールメッセージを読みます。

    DEBUG: JavaMail version 1.6.3
    DEBUG: successfully loaded resource: /META-INF/javamail.default.address.map
    DEBUG: getProvider() returning javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,Oracle]
    DEBUG IMAP: mail.imap.fetchsize: 16384
    DEBUG IMAP: mail.imap.ignorebodystructuresize: false
    DEBUG IMAP: trying to connect to host "******", port 993, isSSL true
    * OK The Microsoft Exchange IMAP4 service is ready. [******]
    A0 CAPABILITY
    * CAPABILITY IMAP4 IMAP4rev1 AUTH=PLAIN AUTH=XOAUTH2 SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+
    A0 OK CAPABILITY completed.
    ...

アプリケーションを Anypoint Platform で実行している場合、ログ出力ではコンソールビューにデバッグ行が表示されます。
スタンドアロン Mule でアプリケーションを実行している場合、ログ出力ではログファイルにデバッグ行が出力されます。

Email Connector デバッグログを有効化する

Email Connector のトラブルシューティングを開始するには、正確なエラーメッセージを確認するためにデバッグログを有効にします。

  1. Anypoint Studio にアクセスし、​[Package Explorer]​ ビューに移動します。

  2. アプリケーションのプロジェクト名を開きます。

  3. src/main/resources​ パスフォルダーを開きます。

  4. フォルダー内の ​log4j2.xml​ ファイルを開きます。

  5. 次の行がすでに ​log4j2.xml​ ファイル内にある場合は、そのコメントを解除して有効にします。それ以外の場合、次の行を追加します。

    <AsyncLogger name="org.mule.extension.email" level="DEBUG" />
  6. 変更を保存します。

  7. Package Explorer​ でプロジェクト名をクリックし、​[Run (実行)]​ > ​[Run As (別のユーザーとして実行)]​ > ​[Mule Application (Mule アプリケーション)]​ をクリックします。

  8. [Console (コンソール)]​ ビューに移動してロガー内の Email Connector のメッセージを読みます。

    DEBUG 2021-04-26 18:51:08,536 [_pollingSource_imapattachmentFlow/executor.01] [processor: ; event: ] org.mule.extension.email.internal.mailbox.BaseMailboxPollingSource: Poll will be skipped, since last poll emails are still being processed
    INFO  2021-04-26 18:51:09,166 [[MuleRuntime].uber.04: [imapattachment].imapattachmentFlow.CPU_LITE @111719e0] [processor: imapattachmentFlow/processors/1/processors/2; event: 820f7fe0-a6d9-11eb-a84b-147dda4dba09] org.mule.runtime.core.internal.processor.LoggerMessageProcessor: "" as Binary {base: "64"}
    DEBUG 2021-04-26 18:51:15,360 [_pollingSource_imapattachmentFlow/executor.01] [processor: ; event: ] org.mule.extension.email.internal.mailbox.BaseMailboxPollingSource: Email [172] was not processed.
    ....

添付テキストファイルを本文メッセージとして解析する場合のトラブルシューティング

Email Connector が本文なしの添付ファイルのみのメッセージを受け取り、Content-Type が ​text​ に設定されている場合、コネクタはテキストコンテンツをペイロード本文としてパブリッシュします。ペイロード添付ファイルリストてテキストファイルを受け取るには、​parsing.text.attachment.as.body​ システムプロパティを ​false​ に設定します。詳細は、​添付テキストファイルを本文メッセージとして解析するための設定​のドキュメントを参照してください。

Jakarta Mail システムプロパティのトラブルシューティング

Email Connector は、Jakarta Mail ライブラリを使用します。そのため、MIME 種別や MIME マルチパートなどの Jakarta Mail システムプロパティを変更することで、コネクタ動作を変更できます。これらのプロパティは、MIME 種別仕様への準拠を制御します。

これらのプロパティはセッションプロパティではなく、システムプロパティとしてグローバルに設定する必要があります。Anypoint Studio で、またはオンプレミスデプロイでシステムプロパティを設定する方法については、​システムプロパティ​のドキュメントを参照してください。

MIME 種別システムプロパティ

最も多く使用される Jakarta Mail MIME 種別システムプロパティは次のとおりです。

  • mail.mime.decodetext.strict
    MIME でエンコードされたワードのデコードを制御します。MIME 仕様では、エンコードされたワードは、空白スペースで区切られたワードの先頭から開始する必要があると定めています。一部のメーラーは、エンコードされたワードをワードの途中から不適切に開始しています。​mail.mime.decodetext.strict​ システムプロパティが ​false​ に設定されている場合は、これらの不当にエンコードされているワードのデコードが試みられます。デフォルトは ​true​ です。

  • mail.mime.encodeeol.strict
    種別が ​text​ ではない MIME パートのコンテンツ転送エンコードの選択を制御します。多くの場合、これらの MIME パートには、通常の行末規定が許可されるエンコードが不適切であるテキストデータが含まれます。まれなケースですが、種別が ​text​ ではない MIME パート全体にテキストデータが含まれていても、CR 文字と LF 文字を変更せずに保持するエンコードが求められる場合があります。​mail.mime.encodeeol.strict​ システムプロパティが ​true​ に設定されている場合、必要に応じてこの種別のエンコードが使用されます。デフォルトは ​false​ です。

  • mail.mime.charset
    プロパティで文字セットが指定されていないエンコードされたワードとテキストパートで使用するデフォルトの MIME 文字セットを指定します。通常、デフォルトの MIME 文字セットは、​file.encoding​ システムプロパティで指定されているデフォルトの Java 文字セットから取得されます。ほとんどのアプリケーションでは、デフォルトの MIME 文字セットを明示的に指定する必要はありません。このプロパティは、メールメッセージで使用するデフォルトの MIME 文字セットが、システムで保存されているファイルで使用されている文字セットと異なる場合に設定してください。

  • mail.mime.ignoreunknownencoding
    Content-Transfer-Encoding ヘッダーの未知の値がデコードメソッドに渡されたときに例外をスローするかどうかを制御します。​true​ の場合、未知の値は無視され、8 ビットエンコードが使用されます。そうでない場合は、​MessagingException​ 例外がスローされます。

MIME マルチパートシステムプロパティ

最も多く使用される Jakarta Mail MIME マルチパートシステムプロパティは次のとおりです。

  • mail.mime.multipart.ignoremissingendboundary
    このプロパティを ​false​ に設定すると、マルチパートデータが必要な終了境界行で終わっていない場合には ​MessagingException​ 例外がスローされます。このプロパティが ​true​ に設定されているか、またはこのプロパティが設定されていない場合は、終了境界が存在しなくてもエラーとは見なされず、本文の最終部分がデータの最後で終了します。

  • mail.mime.multipart.ignoremissingboundaryparameter+ このプロパティを ​false​ に設定すると、MIME マルチパートのコンテンツタイプに境界パラメーターが含まれていない場合に ​MessagingException​ 例外がスローされます。このプロパティが ​true​ に設定されているか、またはこのプロパティが設定されていない場合は、マルチパート解析コードは境界行と似た行を検索し、その行をパートを分割する境界として使用します。

  • mail.mime.multipart.ignoreexistingboundaryparameter
    このプロパティを ​true​ に設定すると、すべての境界が無視され、​mail.mime.multipart.ignoremissingboundaryparameter​ システムプロパティの場合と同じようにメッセージ内で境界行が検索されます。

  • mail.mime.multipart.allowempty
    通常、本文を持たない MIME マルチパートを作成したり、本文を持たないマルチパートメッセージを解析したりすると、​MessagingException​ 例外がスローされます。MIME 種別仕様では、本文を持たないマルチパートコンテンツは許可されません。​mail.mime.multipart.allowempty​ システムプロパティを ​true​ に設定すると、この動作を変更できます。このような MIME マルチパートを書き出すと、空のパートが 1 つ含まれます。このようなマルチパートを読み取ると、本文を持たない MIME マルチパートが作成されます。

SMTPS と Gmail の接続の問題のトラブルシューティング

SMTPS 接続の問題のトラブルシューティングに使用する方法は、Gmail アカウントで 2 要素認証を使用しているかどうかによって異なります。

2 要素認証

アカウントで 2 要素認証値を使用している場合は、アプリケーション固有のパスワードを生成し、通常のパスワードの代わりにそのパスワードを使用します。 詳細は、 「アプリパスワードでログインする」​を参照してください。Gmail アカウントで​安全性の低いアプリ​を有効にする必要はありません。

パスワードベースの認証

Gmail アカウントで 2 要素認証を使用していない場合は、Gmail アカウントで​安全性の低いアプリ​をセットアップして有効化します。パスワードが機能しない場合は、 「Google アカウントへのアクセスを許可」​に移動して、次の手順を実行します。

  1. ユーザー名とパスワードを入力します。

  2. Captcha 画面の文字を入力します。

  3. Mule アプリケーションに戻り、フローを再実行します。

さまざまなプロトコルの動作の理解

問題がプロトコルの動作である場合は、RFC のドキュメントを確認してください。Request for Comments (RFC) とは、Internet Society (ISOC) およびその関連団体 (特に有名なのはインターネットの主要な技術開発および基準設定団体である Internet Engineering Task Force (IETF)) による公開文書です。IETF ではインターネット基準として RFC として公開された提案のいくつかを採用しています。 確認できるドキュメントの一部を紹介します。

一般的なスローを理解する

ここでは、一般的なスローメッセージとその解決方法を示します。

  • EMAIL:EMAIL_NOT_FOUND

    The email identified by ​`emailId`​ cannot be found in a mailbox folder. (「emailId」で識別されるメールがメールボックスフォルダーに見つかりません。)
  • EMAIL:ACCESSING_FOLDER

    There was a problem accessing an email folder or the folder does not exist. (メールフォルダーへのアクセスで問題が発生したか、フォルダーが存在しません。)
  • EMAIL:CONNECTIVITY

    A connection could not be established. (接続を確立できませんでした。)
  • EMAIL:RETRY_EXHAUSTED

    A problem occurred during message routing. (メッセージルーティング中に問題が発生しました。)
  • EMAIL:EMAIL_LIST

    An error occurred during an attempt to list emails. (メールのリスト作成試行中にエラーが発生しました。)
  • EMAIL:SEND

    An exception occurred during an attempt to send an email. (メールの送信試行中に例外が発生しました。)
  • EMAIL:FETCHING_ATTRIBUTES

    An error occurred during email attribute parsing from an email. (メールからのメール属性の解析中にエラーが発生しました。)
  • EMAIL:MARK

    An error occurred during email flag marking. (メールフラグのマーク中にエラーが発生しました。)
  • EMAIL:EXPUNGE_ERROR

    A error occurred during an attempt to delete emails from a folder. (フォルダーからのメールの削除試行中にエラーが発生しました。)
  • EMAIL:ATTACHMENT

    An error occurred during an attempt to send an attachment. (添付ファイルの送信試行中にエラーが発生しました。)
  • EMAIL:READ_EMAIL

    An error occurred during an attempt to read the email content. (メールコンテンツの読み取り試行中にエラーが発生しました。)
  • EMAIL:AUTHENTICATION

    Authentication failed. (認証に失敗しました。)
  • EMAIL:INVALID_CREDENTIALS

    An error occurred during the username and password parameter consistency check. (ユーザー名とパスワードパラメーターの一貫性チェック中にエラーが発生しました。)
  • EMAIL:UNKNOWN_HOST

    The IP address of a host cannot be determined or a port is out of range. (ホストの IP アドレスを判断できないか、ポートが範囲外です。)
  • EMAIL:CONNECTION_TIMEOUT

    The server took too long to reply to a data request. (サーバーでデータ要求への返信に時間がかかりすぎました。)
  • EMAIL:DISCONNECTED

    An error occurred during store connecting, or the connection was interrupted. (ストア接続中にエラーが発生したか、接続が中断されました。)
  • EMAIL:SSL_ERROR

    An error occurred during SSL context creation, or the TLS context wasn't properly configured. (SSL コンテキスト作成中にエラーが発生したか、TLS コンテキストが適切に設定されませんでした。)
  • EMAIL:EMAIL_MOVE

    An error occurred during an attempt to move the mail to the target folder. (対象フォルダーへのメールの移動試行中にエラーが発生しました。)
  • EMAIL:ILLEGAL_ARGUMENT

    メールのリストの取得中に無効なパラメーターのために例外が発生しました。