API連携におけるSalesforce重複管理完全ガイド

こんにちは、Salesforce 統合エンジニア (Integration Engineer) です。私の主な役割は、SalesforceとERP、マーケティングオートメーション、自社開発システムといった多種多様な外部システムとの間で、シームレスかつ信頼性の高いデータ連携を実現することです。この業務の中で最も頻繁に直面し、かつビジネスに深刻な影響を与える課題の一つが、「重複データ」の問題です。

本記事では、特にAPIを介したデータ連携の観点から、Salesforceの標準機能である重複管理 (Duplicate Management) を最大限に活用し、クリーンなデータを維持するための技術的なアプローチとベストプラクティスを、統合エンジニアの視点で徹底的に解説します。

背景と応用シナリオ

システム連携において、なぜ重複データがこれほどまでに大きな問題となるのでしょうか。考えてみてください。マーケティング部門が新しいリード獲得システムを導入し、Webフォームから送信されたリード情報をREST API経由でリアルタイムにSalesforceへ登録するシナリオを想像してみましょう。

この時、適切な重複チェック機構がなければ、以下のような事態が発生します：

既存の取引先責任者 (Contact) が再度リード (Lead) として作成される: 既存顧客に対して、新規顧客向けのアプローチをしてしまい、顧客体験を損なう可能性があります。
同一人物が複数のリードとして登録される: 同じセミナーに複数回申し込んだり、異なるキャンペーンで情報を入力したりすることで、同じ人物のリードが複数作成されます。これにより、営業担当者はどのリードを追うべきか混乱し、アプローチが分散してしまいます。
レポートと分析の不正確化: 重複データは、マーケティングROIの算出や、営業パイプラインの予測といった重要なビジネス指標を歪めます。

これらの問題を解決するため、API経由でデータを挿入 (insert) または更新 (update) する際に、Salesforceの重複管理エンジンを起動させることが極めて重要になります。これにより、リアルタイムで重複の可能性を検知し、データの作成をブロックしたり、あるいは特別な処理を施したりすることが可能となります。今回のシナリオでは、「外部システムからAPIでLeadを作成する際に、Salesforce内の既存LeadやContactとの重複を自動的に防ぐ」ことを目標とします。

原理の説明

Salesforceの重複管理は、主に2つのコンポーネントで構成されています。「一致ルール (Matching Rule)」と「重複ルール (Duplicate Rule)」です。これらは、API連携においても中核的な役割を果たします。

一致ルール (Matching Rule)

一致ルールは、「どのような条件のレコードを重複とみなすか」を定義するものです。例えば、リードオブジェクトに対して以下のようなルールを定義できます。

ルール1: メールアドレスが完全一致 (Exact)
ルール2: 会社名がファジー (Fuzzy) 一致かつ氏名がファジー一致

これらのルールは、複数の項目を組み合わせたり、標準の一致アルゴリズム（完全一致、ファジー一致など）を利用したりして、ビジネス要件に応じて柔軟にカスタマイズできます。統合エンジニアとしては、どの項目が外部システムから確実に連携されてくるのかを把握し、それらの項目を利用した効果的な一致ルールを設計することが求められます。

重複ルール (Duplicate Rule)

重複ルールは、一致ルールによって重複の可能性が検知された場合に、「どのようなアクションを実行するか」を定義します。主なアクションは以下の通りです。

ブロック (Block): レコードの作成または更新をブロックし、エラーを返します。API連携においては、これが最も直接的な重複防止策となります。
許可してアラート (Allow and Alert): レコードの作成・更新は許可しつつ、ユーザーインターフェース上で警告を表示し、重複レコードとしてレポートに記録します。

さらに、重複ルールでは「作成時のアクション」と「編集時のアクション」を個別に設定できます。API連携では、主に「作成時のアクション」で「ブロック」を選択することが一般的です。また、特定の条件下（例：特定のプロファイルを持つユーザーからの操作）でこのルールをバイパスする設定も可能です。

API連携における重複ルールの起動

ここからが統合エンジニアの腕の見せ所です。REST APIやSOAP API、あるいはApexを用いたDML操作で、これらの重複ルールをどのようにして起動させるのでしょうか。その鍵を握るのが `DMLOptions.DuplicateRuleHeader` です。

これは、DML操作（`insert`, `update`）を実行する際に付与できるヘッダー情報で、Salesforceに対して重複ルールをどのように処理してほしいかを明示的に指示します。このヘッダーを設定することで、標準のUI操作だけでなく、バックグラウンドで実行されるAPI経由のデータ操作にも、定義済みの重複管理ロジックを適用させることができます。

例えば、ApexでカスタムREST APIを実装する場合、`Database.insert()` メソッドの第二引数に `DMLOptions` を渡すことで、このヘッダーを制御します。これにより、外部システムは特別なロジックを実装することなく、Salesforce側の重複定義に従ったデータ登録が可能になります。

サンプルコード

それでは、前述の「マーケティングシステムからリード情報を受け取り、重複ルールを適用しながらリードを作成する」カスタムREST APIをApexで実装する例を見てみましょう。このコードは、`DuplicateRuleHeader` を利用して重複チェックを強制する方法を示しています。

まず、Salesforce側で「リードオブジェクト」に対して、メールアドレスが完全一致する場合にブロックする有効な重複ルールが設定されていることを前提とします。

@RestResource(urlMapping='/LeadCreator/v1/*')
global with sharing class LeadCreatorService {

    // 内部リクエストボディを表現するラッパークラス
    global class LeadRequest {
        global String firstName;
        global String lastName;
        global String company;
        global String email;
    }

    @HttpPost
    global static Map<String, Object> createLead(LeadRequest req) {
        Map<String, Object> response = new Map<String, Object>();

        // APIから受け取った情報でLeadオブジェクトを準備
        Lead newLead = new Lead(
            FirstName = req.firstName,
            LastName = req.lastName,
            Company = req.company,
            Email = req.email
        );

        // DMLOptionsオブジェクトを作成し、DuplicateRuleHeaderを設定
        // これがAPI経由で重複ルールを起動させるための核心部分
        Database.DMLOptions dmlOptions = new Database.DMLOptions();
        
        // allowSaveをfalseに設定することで、有効な重複ルールを起動し、
        // 重複が検知された場合はDML操作をブロックして例外を発生させる
        dmlOptions.DuplicateRuleHeader.allowSave = false;

        // 重複ルールを実行するユーザーにレポート権限がある場合、
        // 重複レコードセットに結果を記録するかどうかを指定
        dmlOptions.DuplicateRuleHeader.includeRecordDetails = true;
        
        // このDML操作が重複ルールによってどのように処理されたかをログに残す
        dmlOptions.DuplicateRuleHeader.runAsCurrentUser = true;

        try {
            // DMLOptionsを指定してDatabase.insertを実行
            // これにより、通常のinsertとは異なり、重複ルールの評価が強制される
            Database.SaveResult sr = Database.insert(newLead, dmlOptions);

            if (sr.isSuccess()) {
                response.put('success', true);
                response.put('leadId', sr.getId());
                response.put('message', 'リードが正常に作成されました。');
                RestContext.response.statusCode = 201; // Created
            } else {
                // その他のDMLエラー（入力規則違反など）の処理
                response.put('success', false);
                response.put('errors', sr.getErrors());
                RestContext.response.statusCode = 400; // Bad Request
            }

        } catch (DmlException e) {
            // DmlExceptionを捕捉し、重複が原因であるかを確認
            String errorMessage = e.getMessage();
            if (e.getDmlType(0) == StatusCode.DUPLICATES_DETECTED) {
                // 重複が検知された場合の専用処理
                response.put('success', false);
                response.put('errorCode', 'DUPLICATES_DETECTED');
                response.put('message', '重複の可能性があるレコードが検出されたため、作成をブロックしました。');
                // エラーメッセージから重複しているレコードのIDを取得することも可能
                response.put('details', errorMessage);
                RestContext.response.statusCode = 409; // Conflict
            } else {
                // 重複以外のDML例外（トリガーエラーなど）の処理
                response.put('success', false);
                response.put('errorCode', 'UNKNOWN_DML_ERROR');
                response.put('message', '予期せぬエラーが発生しました。');
                response.put('details', errorMessage);
                RestContext.response.statusCode = 500; // Internal Server Error
            }
        }

        return response;
    }
}

このコードのポイントは、`Database.insert(newLead, dmlOptions)` の部分です。`dmlOptions` を渡すことで、SalesforceのDMLエンジンに対し、デフォルトの動作をオーバーライドして重複ルールを厳格に適用するように指示しています。重複が検知されると、`DmlException` がスローされ、その`StatusCode` が `DUPLICATES_DETECTED` となります。これをcatchブロックで判定することで、呼び出し元の外部システムに対して「なぜレコード作成に失敗したのか（＝重複が原因である）」という明確なフィードバックを返すことができます。

注意事項

API連携で重複管理を実装する際には、いくつかの重要な点に注意する必要があります。

権限 (Permissions): APIリクエストを実行する統合ユーザーには、対象オブジェクトへのCRUD権限に加えて、「重複ルールを実行 (Run Duplicate Rules)」というシステム権限が必要です。この権限がないと、`DMLOptions` を設定しても重複ルールは起動しません。
API制限 (API Limits): 重複ルールの実行は、SOQLクエリやCPU時間を消費します。特に、複雑な一致ルールや大量のデータを一括で処理するバッチ連携の場合、ガバナ制限に抵触する可能性があります。処理時間やパフォーマンスへの影響を考慮し、特に大量データ連携の前にはパフォーマンステストを実施することが推奨されます。
エラー処理 (Error Handling): サンプルコードで示したように、`DmlException` の中でも `DUPLICATES_DETECTED` を特別に扱うことが不可欠です。これにより、呼び出し元システムは、単純な入力エラーと重複エラーを区別し、適切な後続処理（例えば、ユーザーに既存レコードの更新を促すなど）を行うことができます。エラーメッセージをパースして、重複しているレコードのIDリストを取得し、レスポンスに含めることも有効です。
クロスオブジェクトルール (Cross-Object Rules): Salesforceでは、例えば「リードが既存の取引先責任者と重複していないか」をチェックするような、オブジェクトをまたいだ重複ルールも設定できます。これはAPI連携においても同様に機能するため、データモデル全体を俯瞰したルール設計が重要です。
有効化 (Activation): 作成した一致ルールと重複ルールは、「有効化 (Activate)」されていなければ機能しません。開発環境でのテスト後、本番環境へデプロイする際には、ルールの有効化を忘れないようにしてください。

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

Salesforceの標準の重複管理機能は、UI操作だけでなく、APIを介したシステム連携においても非常に強力な武器となります。統合エンジニアとして、この機能を最大限に活用することが、高品質なデータ基盤を構築・維持するための鍵です。

以下に、本番の連携プロジェクトで従うべきベストプラクティスをまとめます。

車輪の再発明を避ける: 重複チェックロジックをApexでゼロから開発する前に、まずは標準の一致ルールと重複ルールで要件を満たせないか徹底的に検討してください。標準機能はSalesforceによってメンテナンスされ、パフォーマンスも最適化されています。
堅牢な統合ユーザープロファイルを設計する: 統合ユーザーには必要最小限の権限を付与する原則（Principle of Least Privilege）を遵守しつつ、「重複ルールを実行」権限を忘れずに割り当ててください。
包括的なエラーハンドリングを実装する: 呼び出し元システムが、なぜ処理が失敗したのかを正確に理解できるように、重複エラーを他のエラーと明確に区別してレスポンスを返却するロジックをAPI側に実装してください。
広範囲なテストを実施する: 新規レコードの作成、明確な重複レコードのブロック、部分的に一致するレコード（ファジー一致のテスト）、そして重複としてフラグ付けされるべきでないレコードなど、様々なシナリオで連携ロジックをテストしてください。
Salesforce管理者との連携: 統合エンジニアは重複ルールを「実行する」方法を実装しますが、どのようなビジネスロジックで重複を「定義する」かは、ビジネス部門と密に連携しているSalesforce管理者の役割です。ルール定義の段階から密に協力し、技術的な実現可能性とビジネス要件のバランスを取ることが、プロジェクト成功の秘訣です。

API経由でのデータ流入は、Salesforce組織におけるデータ品質の生命線です。`DMLOptions.DuplicateRuleHeader` を正しく理解し活用することで、堅牢でクリーンなデータ連携を実現し、Salesforceを真のSingle Source of Truth（信頼できる唯一の情報源）として機能させることができるでしょう。

にゃんこのSalesforce日記

このブログを検索