この文章は Salesforce 機械翻訳システムを使用して翻訳されました。詳細はこちらをご参照ください。

Transaction Finalizers

Transaction Finalizers 機能により、System.Finalizer インターフェースを使用して、キュー可能フレームワークを使う非同期 Apex ジョブにアクションを関連付けることができます。具体的な使用事例として、キュー可能ジョブが失敗した場合の回復アクションの設計が挙げられます。

Transaction Finalizers の機能により、非同期ジョブが成功または失敗したときに実行されるアクションを直接指定できます。Transaction Finalizers よりも前は、非同期ジョブの失敗に対して、次の 2 つのアクションしか取ることができませんでした。

SOQL クエリを使用して AsyncApexJob の状況をポーリングし、ジョブが失敗している場合にジョブを再度キューに追加する
Apex の一括処理メソッドで未対応の例外が発生した場合に、BatchApexErrorEvents を起動する

Transaction Finalizers を使用すると、後処理アクションシーケンスをキュー可能ジョブに関連付け、ジョブの実行結果に基づいて関連するアクションを実行できます。

未対応の例外が原因で失敗したキュー可能ジョブは、Transaction Finalizer によって連続して 5 回再度キューに追加できます。この制限は、キュー可能ジョブの一連の連続した失敗に適用されます。未対応の例外が発生せずにキュー可能ジョブが完了すると、カウンタはリセットされます。

Finalizers は内部クラスとして実装できます。また、同じクラスで Queueable インターフェースと Finalizer インターフェースの両方を実装できます。

キュー可能ジョブと Finalizer は、別個の Apex およびデータベーストランザクションで実行されます。たとえば、キュー可能ジョブには DML を含めることができ、Finalizer には REST コールアウトを含めることができます。Finalizer を使用しても、追加の実行として日次非同期 Apex 制限に反映されません。同期ガバナ制限は Finalizer トランザクションに適用されます。ただし、非同期制限が適用される場合は除きます。

ヒープの合計サイズ
System.enqueueJob によってキューに追加される Apex ジョブの最大数
Apex 呼び出し 1 回につき許可される future アノテーションを持つメソッドの最大数

ガバナ制限についての詳細は、「実行ガバナと制限」を参照してください。

System.Finalizer インターフェース

System.Finalizer インターフェースには execute メソッドがあります。

このメソッドは、指定した FinalizerContext インスタンスが関連付けられているキューに入れられたジョブごとにコールされます。execute メソッド内で、キュー可能ジョブの終了時に実行されるアクションを定義できます。System.FinalizerContext のインスタンスは、Apex ランタイムエンジンによって引数として execute メソッドに挿入されます。

System.FinalizerContext インターフェース

System.FinalizerContext インターフェースには 4 つのメソッドがあります。

getAsyncApexJobId メソッド
この Finalizer が定義されているキュー可能ジョブの ID を返します。
getRequestId メソッド
要求を一意に識別する文字列である要求 ID を返し、イベント監視ログと関連付けることができます。AsyncApexJob テーブルと関連付けるには、代わりに getAsyncApexJobId メソッドを使用します。キュー可能ジョブと Finalizer の実行の両方が (同じ) 要求 ID を使用します。
getResult メソッド
Finalizer が関連付けられている親非同期 Apex キュー可能ジョブの結果を表す System.ParentJobResult 列挙を返します。この列挙は、SUCCESS、UNHANDLED_EXCEPTION の値を取ります。
getException メソッド
getResult が UNHANDLED_EXCEPTION の場合はキュー可能ジョブが失敗し、それ以外の場合は null になる例外を返します。

System.attachFinalizer メソッドを使用して Finalizer をキュー可能ジョブに関連付けます。

System.Finalizer インターフェースを実装するクラスを定義します。
キュー可能ジョブの execute メソッド内で Finalizer を関連付けます。Finalizer を関連付けるには、System.Finalizer インターフェースを実装するインスタンス化されたクラスの引数として System.attachFinalizer メソッド使用して、このメソッドを呼び出します。

実装の詳細

1 つの Finalizer インスタンスのみを任意のキュー可能ジョブに関連付けることができます。
execute メソッドの Finalizer の実装では、1 つの非同期 Apex ジョブ (キュー可能ジョブ、実行予定ジョブ、一括処理ジョブ) をキューに追加できます。
Finalizer の実装ではコールアウトを使用できます。
Finalizer フレームワークは、キュー可能実行の終了時に Finalizer オブジェクト (関連付けられている場合) の状態を使用します。このため、Finalizer が関連付けられた後の状態の変更がサポートされます。
transient として宣言された変数は、シリアライゼーションとデシリアライゼーションで無視されるため、Transaction Finalizer で保持されません。

Finalizer のログ記録の例

次の例では、Transaction Finalizers を使用して、ジョブが成��したかどうかに関係なくキュー可能ジョブからメッセージをログ記録する方法を示します。この LoggingFinalizer クラスでは、Queueable インターフェースと Finalizer インターフェースの両方を実装します。キュー可能実装では、Finalizer がインスタンス化され、Finalizer が関連付けられた後、ログメッセージをバッファリングするための addLog() メソッドが呼び出されます。LoggingFinalizer の Finalizer 実装には、キュー可能ジョブからのメッセージを Fnalizer の状態にバッファリングできる addLog(message, source) メソッドが含まれます。キュー可能ジョブが完了すると、Finalizer インスタンスは、バッファリングされたログをコミットします。Finalizer の状態は、キュー可能ジョブが失敗しても保持され、Finalizer の実装または実行内の DML で使用できます。

キュー可能ジョブの再試行の例

次の例では、Finalizer で失敗したキュー可能ジョブを再度キューに追加する方法を示します。また、キュー可能チェーニング制限の 5 回までジョブを再度キューに追加できることを示します。

ベストプラクティス

ISV では、Finalizer をグローバルで使用している際に、パッケージで状態を変更するメソッドを使う場合には注意が必要です。登録者組織の実装から、グローバル Finalizer のこのようなメソッドを呼び出すと、予期しない動作が発生する可能性があります。状態を変更するメソッドすべて調べて、Finalizer の状態や全体の動作にどのような影響を与えるかを確認してください。

Apex 開発者ガイド