Mule エラー

Mule の実行に失敗すると、エラーが発生します。Mule アプリケーションの実行中、Mule Runtime Engine と、アプリケーションで設定されたモジュールおよびコネクタの操作の両方でエラーがスローされる可能性があります。エラーは Mule エラーオブジェクトで表され、Mule イベントに関連付けられています。On-Error コンポーネントを使用してエラーオブジェクトを処理し、それらに関する情報をログで確認できます。

Mule エラーは、階層順に従い、エラーの発生源を識別して選択したレベルでエラーを処理するのに役立つ命名規則を使用するエラー種別にグループ化されます。これらのエラーをマッピングするカスタムエラー種別を作成することもできます。マッピングは、アプリケーションで処理する必要があるエラーをさらに識別してグループ化するのに役立つ場合があります。

エラー処理設定で Mule エラーの値を調べて使用するために、セレクター式を使用することもできます。

Mule エラーには式 (EXPRESSION) とストリームに関連したエラー (STREAM_MAXIMUM_SIZE_EXCEEDED) が含まれる一方で、操作によって多数の異なる種別のエラーがスローされる可能性があります。例として、HTTP:NOT_FOUND (404 エラー) および HTTP Connector の HTTP リスナーからの HTTP:CONNECTIVITY エラーなどがあります。 DB:BAD_SYNTAX と DB:QUERY_EXPRESSION は、Database Connector の Select 操作でスローされる可能性があるエラーです。

モジュールおよびコネクタ (たとえば、HTTP Connector や Database Connector のリファレンス) では、Mule エラーをリストしています。

Mule エラーのセレクター式

Mule エラーは説明や種別など、複数の項目が含まれる複合データ型です。Mule エラーを記録して処理する場合、任意の数のエラー項目から値を選択できます。

項目説明セレクター式

項目	説明	セレクター式
説明	問題の説明。	`#[error.description]`
Detailed Description (詳細な説明)	問題の説明。説明と同じ場合もあれば、説明よりも広範な内容の場合もあります。	`#[error.detailedDescription]`
型	問題の特徴を記述し、エラーハンドラー内のルーティングを可能にするために使用される種別。	`#[error.errorType]`
Cause	失敗の原因となった基になる Java `Throwable`。	`#[error.cause]`
Message (メッセージ)	問題に関する省略可能な Mule メッセージ。	`#[error.errorMessage]`
Child Errors	Scatter-Gather などの要素が集約されたルートエラーを提供するために使用する内部エラーの省略可能なコレクション。	`#[error.childErrors]`

説明

問題の説明。

#[error.description]

Detailed Description (詳細な説明)

問題の説明。説明と同じ場合もあれば、説明よりも広範な内容の場合もあります。

#[error.detailedDescription]

型

問題の特徴を記述し、エラーハンドラー内のルーティングを可能にするために使用される種別。

#[error.errorType]

Cause

失敗の原因となった基になる Java Throwable。

#[error.cause]

Message (メッセージ)

問題に関する省略可能な Mule メッセージ。

#[error.errorMessage]

Child Errors

Scatter-Gather などの要素が集約されたルートエラーを提供するために使用する内部エラーの省略可能なコレクション。

#[error.childErrors]

多くの場合、error.cause セレクターは、Mule API に含まれる Throwable インスタンスを返します。このエラーの内部構造にアクセスしてエラー処理ロジックを定義しないでください。エラーを処理するためのすべての必要な情報は他のエラーセレクターによって公開されます。また、error.cause をシリアル化すると、冗長な情報が生成される可能性があります。

HTTP 要求エラーの例

たとえば、HTTP 要求に失敗して HTTP:NOT_FOUND エラー (404 状況コードの場合) が表示された場合、エラーメッセージの各部の値は次のようになります。

#[error.description] が返す内容:

HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404).

#[error.detailedDescription] は HTTP GET on resource 'http://jsonplaceholder.typicode.com:80/mybadrequest' failed: not found (404). を返します。
#[error.errorType] は HTTP:NOT_FOUND を返します。
#[error.cause] は org.mule.extension.http.api.request.validator.ResponseValidatorTypedException を返します。ResponseValidatorTypedException の戻りインスタンスを出力する場合、Mule は toString の結果を出力します。エラーに関連付けられた既知の HTTP 状況コード (404 など) がある場合、ResponseValidatorTypedException インスタンスの文字列表現は人間が読み取り可能なエラーの説明になります。

#[error.errorMessage] が返す内容:

org.mule.runtime.core.internal.message.DefaultMessageBuilder$MessageImplementation
{
  payload=org.mule.runtime.core.internal.streaming.bytes.ManagedCursorStreamProvider@223d8f75
  mediaType=application/json; charset=UTF-8
  attributes=org.mule.extension.http.api.HttpResponseAttributes
{
   Status Code=404
   Reason Phrase=Not Found
   Headers=[
      date=Sat, 03 Aug 2019 04:28:29 GMT
      content-type=application/json; charset=utf-8
      content-length=2
      connection=keep-alive
      set-cookie=__cfduid=de19ed0b495b5b58e74fa0ee31a700d651564806509; expires=Sun, 02-Aug-20 04:28:29 GMT; path=/; domain=.typicode.com; HttpOnly
      x-powered-by=Express
      vary=Origin, Accept-Encoding
      access-control-allow-credentials=true
      cache-control=public, max-age=14400
      pragma=no-cache
      expires=Sat, 03 Aug 2019 08:28:29 GMT
      x-content-type-options=nosniff
      etag=W/"2-vyGp6PvFo4RvsFtPoIWeCReyIC8"
      via=1.1 vegur
      cf-cache-status=HIT
      age=96
      server=cloudflare
      cf-ray=50058b8add0a92fe-SJC
   ]
}
  attributesMediaType=*/*
}

errorMessage 要素は、コネクタまたはコンポーネントがエラーとして解釈したメッセージを公開した時点で使用可能になります。たとえば、HTTP 要求で Mule がエラーとして扱うことを示す状況コードが受信された場合、プロセスは失敗し、また、errorMessage にエラーに関する情報が入力されます。その後、ペイロードには #[error.errorMessage.payload] を、メタデータには #[error.errorMessage.attributes] を使用して、エラーメッセージ属性 (メタデータ) およびペイロード自体にアクセスできるようになります。HTTP 要求でエラーが返される場合は、#[error.errorMessage.attributes.statusCode] を使用して状況コードの値 (404 など) を選択できます。Studio でメッセージ属性を確認するには、「DataSense」を参照してください。

#[error.childErrors] が返す内容: []

Mule エラー種別

Mule エラーには名前空間 (HTTP: や FILE: など) と識別子 (NOT_FOUND など) があり、エラー種別の階層に属します。

命名規則により、ドメインに従ってエラーを区別できます。たとえば、NOT_FOUND をスローする代わりに、HTTP Connector は HTTP:NOT_FOUND をスローし、File Connector は FILE:NOT_FOUND エラーをスローする場合があります。

コネクタとは異なり、Mule Runtime エラーには暗黙の MULE 名前空間があるため、MULE:EXPRESSION と EXPRESSION は同じように解釈されます。

エラー種別には親種別がある場合があります。たとえば、HTTP:UNAUTHORIZED の親は MULE:CLIENT_SECURITY、MULE:CLIENT_SECURITY の親は MULE:SECURITY です。この階層は、よりグローバルなエラー種別が各エラー種別に特定化されていることを示しています。たとえば、HTTP:UNAUTHORIZED エラー種別はクライアントセキュリティエラー (MULE:CLIENT_SECURITY) の種別の 1 つですが、クライアントセキュリティエラーはより広範なセキュリティ上の問題 (MULE:SECURITY) の種別の 1 つです。

階層により、一般的な方法、またはより特定の方法でエラーをルーティングできます。たとえば、MULE:SECURITY のエラーハンドラーは HTTP:UNAUTHORIZED エラーおよび OAuth エラーをキャッチします。次の図は、コアランタイム階層を示しています。

すべてのエラーは ANY または CRITICAL の 2 つの主な種別に属します。ANY の各種別はその親によって照合され、処理できるのに対して、CRITICAL のエラー種別はきわめて厳密であるため、処理できず、ログ記録されるのみです。 CRITICAL エラーには FATAL_JVM_ERROR と OVERLOAD が含まれます。

失敗の明確な理由がない場合、コンポーネントは UNKNOWN 種別を使用できます。このエラーは ANY 種別を介して処理し、アプリケーションの既存の動作を変更せずに、不明確なエラーを定義します。

コネクタの場合、各コネクタがコアランタイム階層を考慮してそのエラー種別階層を定義しますが、CONNECTIVITY および RETRY_EXHAUSTED 種別はすべてのコネクタに共通であるため、常に存在します。

エラー種別:

ANY: フローで発生し、処理できるすべてのエラー種別に一致するエラー種別。この種別には、提供元で発生するエラーは含まれません。
- TRANSFORMATION: 値の変換中にエラーが発生したことを示す。これには、Mule Runtime 内部変換が含まれ、DataWeave 変換は含まれません。
- EXPRESSION: DataWeave 式の評価中にエラーが発生したことを示す。
- VALIDATION: 検証エラーが発生したことを示す。
  - DUPLICATE_MESSAGE: 2 回処理されたメッセージに関する検証エラーを示す。たとえば、冪等性のあるメッセージバリデーターの使用などです。
- REDELIVERY_EXHAUSTED: ソースからのメッセージの再処理の最大試行回数に達したことを示す。
- CONNECTIVITY: 接続の確立で問題が発生したことを示す。これは、たとえば HTTP リクエスターなど、コネクタの使用中に発生する可能性があります。
  - RETRY_EXHAUSTED: 特定の実行ブロックの再試行回数がなくなったことを示す。たとえば、特定の操作や、Until Successful スコープの使用などです。
- ROUTING: メッセージのルーティング中にエラーが発生したことを示す。たとえば、Round Robin ルーターの使用などです。
  - COMPOSITE_ROUTING: メッセージのルーティング中に 1 つ以上のエラーが発生したことを示す。たとえば、Scatter Gather ルーターの使用などです。
- SECURITY: 無効なログイン情報の受信や期限切れのトークンの使用など、セキュリティエラーが発生したことを示す。
  - CLIENT_SECURITY: 外部エンティティ (たとえば、外部エンドポイントのコール) によってセキュリティエラーが発生したことを示す。
  - SERVER_SECURITY: Mule Runtime によってセキュリティエラーが適用されたことを示す。
    
    NOT_PERMITTED: 検索条件によってセキュリティ制限が適用されたことを示す。たとえば、Mule Spring Module の承認検索条件の使用などです。
- STREAM_MAXIMUM_SIZE_EXCEEDED: ストリームに許可された最大サイズを超えたことを示す。詳細については、「Mule アプリケーションでのストリーミング」を参照してください。
- TIMEOUT: メッセージの処理中にタイムアウトが発生したことを示す。
- UNKNOWN: 不明なエラーまたは予期しないエラーが発生したことを示す。このエラーは、将来のランタイムバージョンでエラー種別が追加された場合に備えて後方互換性を確保するため、直接処理することはできず、ANY を処理することで処理するしかありません。
SOURCE: フローの取得元でエラーが発生したことを示す。このエラーは処理できません。
- SOURCE_ERROR_RESPONSE_GENERATE: エラー応答のパラメーターの生成中にフローの取得元でエラーが発生したことを示す。取得元がすでに失敗したパスを実行しているため、このエラーは処理できません。
- SOURCE_ERROR_RESPONSE_SEND: エラー応答の送信中にフローの取得元でエラーが発生したことを示す。取得元がすでに失敗したパスを実行しているため、このエラーは処理できません。
SOURCE_RESPONSE: 成功した応答の処理中にフローの取得元でエラーが発生したことを示す。取得元がすでに成功したパスを実行しているため、このエラーは伝播のみできます。このエラーは処理できません。
- SOURCE_RESPONSE_GENERATE: 成功した応答のパラメーターの生成中にフローの取得元でエラーが発生したことを示す。
- SOURCE_RESPONSE_SEND: 成功した応答の送信中にフローの取得元でエラーが発生したことを示す。
CRITICAL: 重大なエラーが発生したことを示す。このエラーは処理できません。
- OVERLOAD: オーバーロードの問題が発生し、実行が拒否されたことを示す。
  - FLOW_BACK_PRESSURE: ソースレベルでオーバーロードの問題が発生したことを示す。たとえば、ソースとしての HTTP リスナーの使用などです。
- FATAL_JVM_ERROR: スタックのオーバーフローなど、重大なエラーが発生したことを示す。

カスタムエラー種別

カスタムエラー種別を使用するには、マッピングするときまたはエラーが発生したときに定義する必要があります。このエラーは、アプリケーション内の既存の種別と区別するために特定のカスタム名前空間が必要です。つまり、HTTP および Database Connector 操作を使用するアプリケーションでは、カスタムエラー種別に HTTP および DB 名前空間を使用できません。

特定の Mule アプリケーション名またはコンテキストに関連した名前空間を定義し、既存のコネクタ名前空間の使用を避ける必要があります。たとえば、顧客集約 API は CUSTOMER 名前空間をそのカスタムエラー種別に使用でき、受注処理 API は ORDER 名前空間を使用できます。

エラーのマッピング

フローの各操作で、可能性のあるエラー種別を選択したカスタムエラー種別にマップできます。これらのカスタムエラー種別を使用して、フローのどこでエラーが発生したかを識別できます。たとえば、フローに異なる REST サービスにアクセスする 2 つの HTTP Request 操作がある場合、一方での接続失敗によって同じエラーが発生します。各エラーを異なるカスタムエラー種別にマッピングすることで、各操作失敗のエラー処理を識別でき、Mule アプリケーションログでエラーの発生元をすばやく識別できます。

次の例では、マッピングによって 2 つのカスタムエラー種別 APP:CUSTOMER_API および APP:ORDER_API を定義することで、きめ細かいエラー処理が可能になることがわかります。

マッピングの XML 設定の例

<flow name="retrieveMatchingOrders">
  <http:request config-ref="customersConfig" path="/customer">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:CUSTOMER_API"/>
  </http:request>
  <http:request config-ref="ordersConfig" path="/order">
    <error-mapping sourceType="CONNECTIVITY" targetType="APP:ORDER_API"/>
  </http:request>
  <error-handler>
    <on-error-continue type="APP:CUSTOMER_API">
      <logger message="#['Could not retrieve customer data.']"/>
    </on-error-continue>
    <on-error-continue type="APP:ORDER_API">
      <logger message="#['Could not retrieve customer order data.']"/>
    </on-error-continue>
  </error-handler>
</flow>

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan