Queueable Apex を使用したプロセスの制御

• Queueable インターフェースを使用するケース。
• queueable メソッドと future メソッドの違い。
• Queueable Apex の構文。
• queueable メソッドのベストプラクティス。

メモ

このバッジのハンズオン Challenge は日本語、スペイン語 (LATAM)、ポルトガル語 (ブラジル) に対応しています。Playground の言語を変更するには、こちらの指示に従ってください。日本語等、翻訳された言語と英語に差異がある可能性があります。英語以外の言語での指示に従って Challenge に合格できなかった場合は、[言語] と [地域] をそれぞれ [English]、[アメリカ合衆国] に切り替えてからもう一度お試しください。

翻訳版 Trailhead を活用する方法の詳細は、自分の言語の Trailhead バッジを参照してください。

• 非プリミティブ型: Queueable クラスには、sObject 型やカスタム Apex 型など、プリミティブ以外のデータ型のメンバー変数を含めることができます。これらのオブジェクトには、ジョブの実行時にアクセスできます。
• 監視: System.enqueueJob() メソッドを呼び出してジョブを送信すると、メソッドが AsyncApexJob レコードの ID を返します。この ID を使用して、Salesforce ユーザーインターフェースの [Apex ジョブ] ページから、またはプログラムで AsyncApexJob のレコードを照会する方法で、ジョブを識別してその進行状況を監視できます。
• ジョブのチェーニング: 実行中のジョブから 2 つ目のジョブを開始することで、2 つのジョブを連鎖的に実行することができます。ジョブのチェーニングは、連続的な処理を行う必要がある場合に役立ちます。

@future
static void myFutureMethod(List<String> params) {
    // call synchronous method
    mySyncMethod(params);
}

public class SomeClass implements Queueable {
    public void execute(QueueableContext context) {
        // awesome code here
    }
}

サンプルコード

一般的なシナリオは、いくつかの sObject レコードを取り、外部の REST エンドポイントへのコールアウトの実行など一定の処理を実行するか、何らかの計算を実行してからデータベースで非同期で更新します。@future メソッドはプリミティブデータ型 (またはプリミティブの配列あるいはコレクション) に限定されているため、Queueable Apex が理想的な選択肢となります。次のコードは、取引先レコードのコレクションを取り、各レコードに parentId を設定してから、データベースのレコードを更新します。

public class UpdateParentAccount implements Queueable {
    private List<Account> accounts;
    private ID parent;
    public UpdateParentAccount(List<Account> records, ID id) {
        this.accounts = records;
        this.parent = id;
    }
    public void execute(QueueableContext context) {
        for (Account account : accounts) {
          account.parentId = parent;
          // perform other processing or callout
        }
        update accounts;
    }
}

このクラスをジョブとしてキューに追加するには、次のコードを実行します。

// find all accounts in ‘NY’
List<Account> accounts = [select id from account where billingstate = ‘NY’];
// find a specific parent account for all records
Id parentId = [select id from account where name = 'ACME Corp'][0].Id;
// instantiate a new instance of the Queueable class
UpdateParentAccount updateJob = new UpdateParentAccount(accounts, parentId);
// enqueue the job for processing
ID jobID = System.enqueueJob(updateJob);

キュー可能クラスを実行のために送信すると、ジョブはキューに追加され、システムリソースが使用可能になると処理されます。

新しいジョブ ID を使用して、[Apex Job (Apex ジョブ)] ページから、またはプログラムで AsyncApexJob を照会する方法で、進行状況を監視できます。

SELECT Id, Status, NumberOfErrors FROM AsyncApexJob WHERE Id = :jobID

@isTest
public class UpdateParentAccountTest {
    @testSetup
    static void setup() {
        List<Account> accounts = new List<Account>();
        // add a parent account
        accounts.add(new Account(name='Parent'));
        // add 100 child accounts
        for (Integer i = 0; i < 100; i++) {
            accounts.add(new Account(
                name='Test Account'+i
            ));
        }
        insert accounts;
    }
    static testmethod void testQueueable() {
        // query for test data to pass to queueable class
        Id parentId = [select id from account where name = 'Parent'][0].Id;
        List<Account> accounts = [select id, name from account where name like 'Test Account%'];
        // Create our Queueable instance
        UpdateParentAccount updater = new UpdateParentAccount(accounts, parentId);
        // startTest/stopTest block to force async processes to run
        Test.startTest();
        System.enqueueJob(updater);
        Test.stopTest();
        // Validate the job ran. Check if record have correct parentId now
        System.assertEquals(100, [select count() from account where parentId = :parentId]);
    }
}

public class FirstJob implements Queueable {
    public void execute(QueueableContext context) {
        // Awesome processing logic here
        // Chain this job to next job by submitting the next job
        System.enqueueJob(new SecondJob());
    }
}

• キュー内のジョブを実行すると、非同期 Apex メソッド実行の共有制限値に 1 回カウントされます。
• 1 つのトランザクションで System.enqueueJob を使用してキューに追加できる最大数は 50 ジョブです。
• ジョブをチェーニングするとき、実行中のジョブから System.enqueueJob で追加できるジョブは 1 つのみです。つまり、親キュー可能ジョブごとに 1 つの子ジョブしか存在できません。同じキュー可能ジョブからの複数の子ジョブを開始することはできません。
• チェーニングされたジョブの深度に制限はありません。つまり、1 つのジョブから別のジョブにチェーニングし、このプロセスを新しい子ジョブごとに繰り返して新しい子ジョブにリンクできます。ただし、Developer Edition 組織やトライアル組織の場合は、チェーニングされたジョブの最大スタック深度は 5 です。つまり、ジョブのチェーニングを 4 回行うことができ、チェーン内のジョブ数は最初の親キュー可能ジョブを含めて最大 5 個です。

• Apex 開発者ガイド: Queueable Apex