Salesforce Apexにおける動的SOQL開発者ガイド

Salesforce開発者の皆さん、こんにちは！日々の開発業務で、ユーザーの入力や特定の条件に応じてクエリを柔軟に構築したいと感じることはありませんか？静的なSOQLでは対応しきれない、そんな複雑な要件に応えるための強力なツールがDynamic SOQL (動的SOQL)です。本記事では、Salesforce開発者として、動的SOQLの基本から応用、そして最も重要なセキュリティ上の注意点までを、実践的なコードを交えて徹底的に解説します。

背景と応用シナリオ

Salesforce開発において、データの問い合わせにはSOQL (Salesforce Object Query Language)、すなわちSalesforceオブジェクトクエリ言語を使用します。通常、私たちがApexクラス内で書くSOQLは「静的SOQL」と呼ばれます。これは、クエリ文字列がコード内に直接記述され、コンパイル時に構文チェックや項目・オブジェクトの存在チェックが行われるため、非常に安全でパフォーマンスも高い方法です。

例：

List<Account> accs = [SELECT Id, Name FROM Account WHERE Name = 'ACME'];

しかし、実際のプロジェクトでは、要件が常に静的であるとは限りません。以下のようなシナリオに直面した場合、静的SOQLだけでは限界があります。

応用シナリオの例：

カスタム検索画面の実装：ユーザーが画面上で検索対象のオブジェクト、表示したい項目、そして絞り込み条件（例：取引先名が「A」で始まり、年間売上が1億円以上など）を自由に選択できるような検索コンポーネントを構築する場合。クエリの構造そのものが実行時まで確定しません。
汎用的なデータエクスポートツールの開発：設定（カスタムメタデータなど）に基づいて、異なるオブジェクトから異なる項目をCSVとしてエクスポートするツールを作成する場合。クエリ対象のオブジェクト名や項目名を変数として扱う必要があります。
動的なレポート機能：ユーザープロファイルや権限セットに応じて、表示する項目を切り替える必要があるレポート機能をLightning Web Componentで実装する場合。

このような「実行時にクエリを組み立てる」必要がある場面で活躍するのが、Dynamic SOQL (動的SOQL)です。動的SOQLは、クエリを文字列としてプログラムで生成し、実行時にその文字列をデータベースに渡して結果を取得する仕組みです。

原理説明

動的SOQLの核心は、Apexの`Database`クラスが提供するメソッドにあります。最も基本的なメソッドは`Database.query(queryString)`です。

このメソッドは、引数としてSOQLクエリが格納された文字列(`String`)を受け取ります。Apexは、この文字列を実行時にSOQLクエリとして解釈し、データベースエンジンに渡します。データベースエンジンはクエリを実行し、結果を`List<sObject>`として返します。

静的SOQLがコンパイル時に検証されるのに対し、動的SOQLは実行時に検証されます。これは、柔軟性が高い反面、文字列の組み立て方を間違えると構文エラーが発生し、`QueryException`という実行時例外を引き起こす可能性があることを意味します。したがって、開発者はクエリ文字列が常に有効なSOQLになるよう、細心の注意を払って構築する必要があります。

そして、動的SOQLを扱う上で最も警戒すべきなのがSOQL Injection (SOQLインジェクション)というセキュリティ脆弱性です。これは、ユーザーからの入力を適切に処理（エスケープ）せずにクエリ文字列に連結してしまうことで、攻撃者が意図しないクエリを実行させ、データを不正に閲覧したり、更新・削除したりする攻撃手法です。このリスクを理解し、対策を講じることが、動的SOQLを安全に利用するための絶対条件となります。

示例代码

ここでは、Salesforceの公式ドキュメントに掲載されているコードを基に、動的SOQLの基本的な使い方と、SOQLインジェクション対策について解説します。

基本的な動的SOQLの例

以下の例では、変数を使って検索対象のオブジェクトと項目を動的に指定しています。

// 検索対象のオブジェクト名を文字列変数で定義
String objectName = 'Account';
// 取得したい項目を文字列変数で定義
String fieldName = 'Name';

// 動的SOQLクエリを文字列として構築
// 'SELECT ' + fieldName + ' FROM ' + objectName のように文字列を連結していく
String soqlQuery = 'SELECT Id, ' + fieldName + ' FROM ' + objectName + ' LIMIT 10';

// Database.query()メソッドに文字列を渡してクエリを実行
// 戻り値は List<sObject> 型となる
List<sObject> records = Database.query(soqlQuery);

// 結果を処理
for (sObject record : records) {
    // sObject型から具体的な項目値を取得するには .get() メソッドを使用
    System.debug('Account ID: ' + record.get('Id'));
    System.debug('Account Name: ' + record.get(fieldName));
}

このコードは、オブジェクト名や項目名が事前にわからない場合に非常に有効です。しかし、`WHERE`句でユーザー入力を扱う際には、セキュリティ上のリスクが伴います。

SOQLインジェクションのリスクと対策

例えば、ユーザーが入力した文字列で取引先を検索する機能を考えてみましょう。以下は危険なコードの例です。

// --- 警告：これはSOQLインジェクションに対して脆弱なコードです ---
// ユーザーからの入力を想定した変数
String userInput = 'Test\') OR (Name LIKE \'%'; 

// ユーザー入力を直接クエリ文字列に連結
// これが最も危険な実装方法
String query = 'SELECT Id, Name FROM Account WHERE Name = \'' + userInput + '\'';

// この時点で、`query`変数の内容は以下のようになる：
// 'SELECT Id, Name FROM Account WHERE Name = 'Test') OR (Name LIKE '%''
// WHERE句の条件が意図せず変更され、すべての取引先が返されてしまう

try {
    List<Account> accs = Database.query(query);
    System.debug('取得したレコード数: ' + accs.size()); // 本来意図しないレコードが取得される
} catch (QueryException e) {
    System.debug('クエリエラー: ' + e.getMessage());
}

上記の例では、悪意のある入力によって`WHERE`句が操作され、本来取得されるべきでないデータが取得されてしまいます。この脆弱性を防ぐための最も基本的な方法が、`String.escapeSingleQuotes()`メソッドの使用です。

このメソッドは、文字列内のすべてのシングルクォーテーション(`'`)の前にエスケープ文字(`\`)を挿入します。これにより、入力された文字列がSOQLリテラルとして安全に扱われるようになります。

SOQLインジェクション対策を施した安全なコード

以下は、`String.escapeSingleQuotes()`を使ってユーザー入力を安全に処理する、修正後のコードです。

// --- 安全な実装例 ---
// ユーザーからの入力を想定した変数
String userInput = 'Test Account'; 

// String.escapeSingleQuotes() メソッドを使用してユーザー入力をサニタイズ（無害化）する
// これにより、入力文字列内のシングルクォートがエスケープされる
String sanitizedInput = String.escapeSingleQuotes(userInput);
System.debug('サニタイズ後の入力: ' + sanitizedInput); // 'Test Account' のまま

// 安全にサニタイズされた変数をクエリ文字列に連結
String query = 'SELECT Id, Name FROM Account WHERE Name = \'' + sanitizedInput + '\'';

// Database.query() を try-catch ブロックで囲み、実行時エラーに備えるのがベストプラクティス
try {
    List<Account> accs = Database.query(query);
    System.debug('取得したレコード数: ' + accs.size());
    for (Account acc : accs) {
        System.debug('取引先名: ' + acc.Name);
    }
} catch (QueryException e) {
    // クエリ文字列に構文エラーがあった場合などにここが実行される
    System.debug('クエリエラーが発生しました: ' + e.getMessage());
}

このように、ユーザーが入力する可能性のある値を`WHERE`句に含める場合は、必ず`String.escapeSingleQuotes()`でエスケープ処理を行うことが、開発者としての責務です。

注意事項

動的SOQLを実務で利用する際には、いくつかの重要な注意点があります。

権限と共有 (Permissions and Sharing)

Apexクラスに`with sharing`または`without sharing`キーワードが指定されているかによって、動的SOQLの実行結果が変わります。`with sharing`を指定したクラス内で実行された動的SOQLは、実行ユーザーの共有設定を尊重します。つまり、ユーザーがアクセス権を持つレコードのみが返されます。一方、`without sharing`は共有設定を無視します。原則として、ユーザーの権限を尊重するために`with sharing`または`inherited sharing`を使用することが推奨されます。

SOQLインジェクション (SOQL Injection)

前述の通り、これは最大の注意点です。ユーザーからの入力をクエリに含める場合は、常に`String.escapeSingleQuotes()`メソッドでサニタイズしてください。バインド変数（`Database.queryWithBinds()`）を使用することも、より高度で安全な代替策となります。

ガバナ制限 (Governor Limits)

動的SOQLも、静的SOQLと同様にSalesforceのガバナ制限に従います。1つのトランザクション内で実行できるSOQLクエリの合計数（同期Apexでは100回）や、取得できるレコードの合計数（50,000件）などの制限に抵触しないよう、設計段階で考慮が必要です。動的だからといって、制限が緩和されるわけではありません。

エラー処理 (Error Handling)

クエリ文字列は実行時に評価されるため、文字列の連結ミスなどによって無効なSOQLが生成される可能性があります。その場合、`Database.query()`は`QueryException`をスローします。信頼性の高いコードにするために、動的SOQLの呼び出しは常に`try-catch`ブロックで囲み、例外が発生した場合の処理を適切に記述してください。

フィールドレベルセキュリティ (Field-Level Security)

動的SOQLは、実行ユーザーがアクセス権を持たない項目を`SELECT`句に含めてもエラーにはなりませんが、その項目は結果に含まれません。しかし、取得したデータをDML操作（`insert`, `update`など）に使用する前に、ユーザーがその項目に対する編集権限を持っているかを確認することがセキュリティ上重要です。`Security.stripInaccessible()`メソッドを使用することで、アクセスできない項目をsObjectリストから安全に除去できます。

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

Dynamic SOQLは、Salesforceプラットフォーム上で非常に柔軟かつ強力なデータアクセス機能を提供します。しかし、その力には大きな責任が伴います。最後に、動的SOQLを安全かつ効果的に活用するためのベストプラクティスをまとめます。

可能な限り静的SOQLを優先する：クエリの構造がコンパイル時に確定している場合は、常に静的SOQLを使用してください。安全性、パフォーマンス、可読性のすべてにおいて優れています。動的SOQLは、それが本当に必要な場合にのみ使用する「最後の手段」と考えるべきです。
SOQLインジェクションを徹底的に防御する：ユーザー入力をWHERE句に含める場合は、`String.escapeSingleQuotes()`によるサニタイズを絶対に忘れないでください。これが動的SOQLを扱う上での最低限のルールです。
堅牢なエラー処理を実装する：`Database.query()`の呼び出しは、必ず`try-catch`ブロックでラップし、`QueryException`を捕捉して、ユーザーに分かりやすいフィードバックを返すなどの代替処理を実装してください。
共有ルールを常に意識する：特別な理由がない限り、クラスには`with sharing`または`inherited sharing`を明記し、データアクセスがユーザーの権限に準拠するようにしてください。
コードの可読性を維持する：複雑なクエリ文字列を組み立てる際は、コードが非常に読みにくくなることがあります。クエリの各部分を組み立てるヘルパーメソッドを作成したり、コメントを詳細に残したりして、後から自分や他の開発者が見ても理解できるように工夫しましょう。
セキュリティチェックを怠らない：クエリ実行後のデータ操作（DML）の前には、`Security.stripInaccessible()`メソッドを利用してフィールドレベルセキュリティを適用することを検討してください。

これらの原則を守ることで、皆さんも動的SOQLという強力なツールを安全に使いこなし、より高度で柔軟なSalesforceアプリケーションを構築できるはずです。Happy coding!

にゃんこのSalesforce日記

このブログを検索