キュー可能 Apex によるスケーラブルな Salesforce アプリケーション開発：開発者向け詳細ガイド

日付:

背景と適用シナリオ

Salesforce プラットフォーム上で複雑なビジネスロジックを実装する際、開発者が常に直面する課題の一つが Governor Limits (ガバナ制限) です。これは、プラットフォームのリソースをすべてのユーザーで公平に共有するために Salesforce が設けている実行制限です。例えば、1回のトランザクション内で実行できる SOQL クエリの数や DML ステートメントの数、CPU 実行時間などには上限があります。これらの制限により、特に大量のデータを処理したり、外部システムへのコールアウトを実行したりする場合、同期的な処理では限界が生じることがあります。

この課題を解決するために、Salesforce は Asynchronous Apex (非同期 Apex) という仕組みを提供しています。非同期 Apex を使用すると、重い処理をバックグラウンドで実行させ、現在のトランザクションから切り離すことができます。これにより、ユーザーは処理の完了を待つことなく次の操作に進むことができ、ガバナ制限もより緩和されたものになります。

非同期 Apex には、@future メソッド、Batch Apex (バッチ Apex)、Scheduled Apex (スケジュール済み Apex)、そして本稿の主役である Queueable Apex (キュー可能 Apex) など、いくつかの種類があります。

特に @future メソッドは、非同期処理を実装するための最も手軽な方法の一つですが、いくつかの制約があります。例えば、引数として渡せるのはプリミティブなデータ型のみであり、処理の実行状況を追跡するための Job ID を直接取得することもできません。また、一つの @future メソッドから別の @future メソッドを呼び出すといった、処理の連鎖（チェーニング）もできません。

ここで登場するのが Queueable Apex です。Queueable Apex は @future メソッドの強力な後継と位置づけられており、その多くの制約を克服しています。主な適用シナリオは以下の通りです。

  • 複雑なデータ処理： トリガーなどから起動され、大量のレコード更新や複雑な計算をバックグラウンドで実行する必要がある場合。
  • 外部システムへのコールアウト： DML 操作の後に外部システムの API を呼び出すなど、混合 DML エラーを回避しつつ、時間のかかるコールアウトを実行する場合。
  • 依存関係のある非同期処理： 最初の非同期ジョブが完了した後に、その結果を利用して次の非同期ジョブを開始する（Job Chaining (ジョブのチェーン化)）必要がある場合。

本稿では、Salesforce 開発者の視点から Queueable Apex の原理を深く掘り下げ、その強力な機能を最大限に活用するための方法を解説します。

原理説明

Queueable Apex の中核は、Queueable というシステムインターフェースを実装することにあります。このインターフェースをクラスに実装すると、そのクラスのインスタンスを非同期ジョブのキューに追加できるようになります。

Queueable インターフェースには、実装が必要なメソッドが一つだけ定義されています。

void execute(QueueableContext context)

この execute メソッド内に、バックグラウンドで実行したいすべてのビジネスロジックを記述します。メソッドが受け取る QueueableContext オブジェクトは、現在のジョブの Job ID を取得するためのインターフェースを提供しますが、現時点ではそれ以外の機能はありません。

Queueable Apex の実行プロセスは非常にシンプルです。

  1. Queueable インターフェースを実装した Apex クラスを作成します。
  2. クラスのコンストラクタを使用して、処理に必要なデータを渡します。@future メソッドとは異なり、sObject やカスタム Apex クラスのインスタンスなど、非プリミティブなデータ型をメンバー変数として保持できます。
  3. execute メソッド内に、非同期で実行したい処理を実装します。
  4. 作成したクラスのインスタンスを生成し、System.enqueueJob() メソッドに渡してジョブをキューに追加します。
// 例：ジョブのキュー追加
MyQueueableJob job = new MyQueueableJob(someSObjectList);
ID jobId = System.enqueueJob(job);

この System.enqueueJob(job) メソッドは、ジョブが正常にキューに追加されると、そのジョブを追跡するための Job ID を返します。この ID を使用して AsyncApexJob オブジェクトをクエリすることで、ジョブのステータス（'Queued', 'Processing', 'Completed', 'Failed' など）を監視できます。これは、@future メソッドにはない大きな利点です。

さらに、Queueable Apex の最も強力な機能の一つがジョブのチェーン化です。ある Queueable ジョブの execute メソッド内から、別の Queueable ジョブ（あるいは同じジョブの新しいインスタンス）を System.enqueueJob() でキューに追加することができます。これにより、一連の依存関係のある処理を順番に実行させることが可能になります。例えば、ステップ1で取引先を処理し、その完了後にステップ2で関連する取引先責任者を処理する、といった連続したタスクを簡単に実装できます。

示例代码

ここでは、Salesforce の公式ドキュメントで紹介されているジョブのチェーン化の例を見てみましょう。この例では、まず親ジョブ（ParentJob）が取引先レコードの項目を更新します。その後、子ジョブ（ChildJob）をチェーンして、それらの取引先に関連するすべての取引先責任者の項目を更新します。

親ジョブ：取引先を更新し、子ジョブを呼び出す

このクラスは、取引先レコードのリストを受け取り、それらの説明項目を更新します。処理が完了すると、次のステップとして `ChildJob` をキューに追加します。 

// Salesforce Developer Guide の公式サンプルコード
public class ParentJob implements Queueable {
    
    private List<Account> accounts;
    
    // コンストラクタで処理対象のレコードを受け取る
    public ParentJob(List<Account> records) {
        this.accounts = records;
    }
    
    public void execute(QueueableContext context) {
        // 取引先の説明項目を更新する
        for (Account a : accounts) {
            a.Description = 'Parent job processed this account.';
        }
        update accounts;
        
        // ★★★ このジョブが完了したら、子ジョブをキューに追加する（ジョブのチェーン化） ★★★
        // チェーンされたジョブは、現在のジョブのガバナ制限を消費しない
        System.enqueueJob(new ChildJob(accounts));
    }
}

子ジョブ：関連する取引先責任者を更新する

このクラスは、親ジョブによって処理された取引先のリストを受け取り、それらに関連するすべての取引先責任者レコードを検索して更新します。 

// Salesforce Developer Guide の公式サンプルコード
public class ChildJob implements Queueable {
    
    private List<Account> accounts;
    
    // コンストラクタ
    public ChildJob(List<Account> records) {
        this.accounts = records;
    }
    
    public void execute(QueueableContext context) {
        List<Contact> contactsToUpdate = new List<Contact>();
        
        // 親ジョブで処理された取引先に関連するすべての取引先責任者を取得
        List<Contact> contacts = [SELECT Id, Description FROM Contact WHERE AccountId IN :accounts];
        
        for (Contact c : contacts) {
            c.Description = 'Child job processed this contact.';
            contactsToUpdate.add(c);
        }
        
        // 取引先責任者を更新
        if (!contactsToUpdate.isEmpty()) {
            update contactsToUpdate;
        }
    }
}

実行方法

この一連の処理を開始するには、匿名実行ウィンドウなどから親ジョブをキューに追加します。 

// 処理対象の取引先を準備
List<Account> accounts = [SELECT Id, Name FROM Account LIMIT 2];

// 親ジョブのインスタンスを作成し、キューに追加する
ParentJob parent = new ParentJob(accounts);
ID parentJobId = System.enqueueJob(parent);

// 返された Job ID を使用して、ジョブのステータスを監視できる
System.debug('Parent job ID: ' + parentJobId);

このコードを実行すると、まず `ParentJob` が実行され、2件の取引先が更新されます。その `execute` メソッドが完了すると、自動的に `ChildJob` がキューに追加され、関連する取引先責任者の更新処理が開始されます。これにより、2つの独立した非同期トランザクションで一連の処理が安全に実行されます。

注意事項

Queueable Apex は非常に強力ですが、使用する際にはいくつかの重要な点に注意する必要があります。

ガバナ制限

  • キュー追加の制限： 1回のトランザクション内で System.enqueueJob() を呼び出せる回数は、同期トランザクションでは50回までです。しかし、非同期コンテキスト（@future, Queueable, Batch など）内からは、1回しか呼び出すことができません。これが、ジョブチェーンが1対1の線形になる理由です。
  • ジョブチェーンの深さ： Developer Edition やトライアル組織では、チェーンできるジョブの深さに制限があります（通常は2）。本番組織ではより深いチェーンが可能ですが、無限にチェーンできるわけではありません。設計時には、チェーンが深くなりすぎないように注意が必要です。
  • 通常の Apex 制限： execute メソッド内の処理も、非同期処理用のガバナ制限（より緩和された CPU 時間やヒープサイズなど）に従う必要があります。1つのジョブで処理するデータ量が多すぎると、依然として制限に達する可能性があります。

エラーハンドリング (Error Handling)

execute メソッド内でハンドルされない例外が発生した場合、ジョブは 'Failed' ステータスで終了します。Queueable Apex には、自動再試行の仕組みは組み込まれていません。そのため、堅牢なアプリケーションを構築するには、try-catch ブロックを使用して例外を適切に捕捉し、カスタムログオブジェクトへの記録や管理への通知など、独自のエラーハンドリング戦略を実装することが不可欠です。

さらに高度な要件として、Spring '21 で導入された Finalizer インターフェースがあります。System.attachFinalizer() メソッドを使用すると、Queueable ジョブが成功したか失敗したかに関わらず、ジョブの終了後に必ず実行される後処理ロジック（リソースのクリーンアップや状態の更新など）を実装できます。

テスト

Queueable Apex のテストは比較的簡単です。テストメソッド内でジョブをキューに追加すると、そのジョブは非同期ではなく、同期的に実行されます。ただし、ジョブの実行が完了し、後続のアサーション（結果検証）が正しく行われるように、Test.startTest() と Test.stopTest() のブロックでジョブの呼び出しを囲むことがベストプラクティスです。 

@isTest
private class MyQueueableTest {
    static testMethod void testQueueable() {
        // 1. テストデータを準備
        List<Account> accounts = new List<Account>();
        for(Integer i=0; i<5; i++) {
            accounts.add(new Account(Name='Test Account ' + i));
        }
        insert accounts;
        
        Test.startTest();
        // 2. Queueable ジョブをエンキュー
        System.enqueueJob(new ParentJob(accounts));
        Test.stopTest(); // ← この時点でジョブの実行が完了する
        
        // 3. 結果を検証
        List<Account> updatedAccounts = [SELECT Description FROM Account WHERE Id IN :accounts];
        for(Account acc : updatedAccounts) {
            System.assertEquals('Parent job processed this account.', acc.Description);
        }
    }
}

冪等性 (Idempotency)

特に再試行ロジックを独自に実装する場合、ジョブが複数回実行されても同じ結果になること、つまり冪等性を担保することが重要です。例えば、レコードの作成処理であれば、重複して作成しないように事前の存在チェックを行うなどの工夫が必要です。

まとめとベストプラクティス

Queueable Apex は、Salesforce プラットフォームにおける非同期処理のための現代的で強力なツールです。@future メソッドの制約を克服し、Job ID による追跡、複雑なデータ型のサポート、そしてジョブのチェーン化という重要な機能を提供します。

Queueable Apex vs Batch Apex:

  • Queueable Apex は、比較的複雑だが単一のトランザクションとして実行可能な、中規模の非同期タスクに適しています。ジョブのチェーン化が必要な場合に最適です。
  • Batch Apex は、数万から数百万件といった非常に大規模なデータセットを扱うために設計されています。データを自動的に小さなチャンクに分割し、それぞれを独立したトランザクションで処理するため、ガバナ制限に対して非常に高い回復力を持ちます。

以下に、Queueable Apex を使用する際のベストプラクティスをまとめます。

  1. 責務の単一化： 1つの Queueable クラスには、1つの明確な責務を持たせましょう。クラスが肥大化しすぎないように、ロジックは適切に分割してください。
  2. 堅牢なエラーハンドリング： try-catch ブロックを必ず使用し、失敗した場合のシナリオを考慮した設計を行ってください。必要に応じて Finalizer の使用も検討します。
  3. チェーンの管理： 無限ループや深すぎるチェーンに陥らないように、チェーンの終了条件を明確に定義してください。
  4. ガバナ制限の意識： execute メソッド内でも、処理がSOQLクエリやDMLステートメントの制限に達しないように、バルク化したコードを記述してください。
  5. 状態の管理： メンバー変数を使用してジョブ間で状態を渡すことができますが、ガバナ制限（ヒープサイズなど）に注意し、必要なデータのみを渡すようにしてください。

Queueable Apex をマスターすることは、スケーラブルで効率的な Salesforce アプリケーションを構築する上で、すべての Salesforce 開発者にとって不可欠なスキルです。その柔軟性とパワーを理解し、適切なシナリオで活用することで、ガバナ制限の壁を乗り越え、より高度なビジネス要件に対応することが可能になります。

コメント

コメントを投稿