【Salesforce】外部IDで困った時の本番反映前の切り分け

Salesforceで外部IDを使用していると、本番環境への反映前に「データがインポートできない」「レコードが重複する」「エラーが発生して先に進めない」といった問題に直面することがあります。外部IDはレコードを一意に識別するための重要な項目ですが、設定やデータの不備があると本番環境で深刻なトラブルを引き起こします。本記事では、本番反映前に外部IDに関連する問題を効率的に切り分けるための具体的な手順と考え方を解説します。エラーが発生した際に「どこを確認すればよいか」を明確にすることで、スムーズな本番デプロイを支援します。

外部IDで発生しやすいエラーと原因

外部IDに関連するエラーは、主にデータの重複、形式不一致、権限不足、設定ミスの4つに分類できます。本番環境に反映する前に、どのようなエラーが起こり得るかを理解しておくと、原因特定が容易になります。以下に、代表的なケースを説明します。

重複エラーのケース

外部IDには一意性制約が設定されているため、同じ値を複数のレコードに割り当てようとするとエラーが発生します。例えば、顧客コードを外部IDとして使用している場合、既存のレコードと同じコードを新しいレコードに設定しようとすると、「DUPLICATE_VALUE」エラーが返されます。このエラーは、データインポート時やレコード更新時によく見られます。原因としては、CSVファイル内で値を重複して含んでいる、既存データに外部IDが未設定で後から重複値を挿入しようとしている、などが考えられます。

データインポート時のエラー

データローダやData Import Wizardを使用して外部IDを含むデータをインポートする際、外部IDのデータ型がテキストなのか数値なのか、長さ制限はあるのか、といった定義と実際のデータが一致しないとエラーになります。例えば、外部IDが「数値」型に設定されているのに、CSVで文字列を指定すると型変換エラーが発生します。また、空白や特殊文字が含まれている場合もエラーの原因となります。

レコードの作成・更新時のエラー

ApexやREST APIから外部IDを使ってレコードをupsertする場合、外部IDが正しく参照されずにエラーが発生することがあります。例えば、外部IDの値を指定しても該当レコードが見つからない「MALFORMED_ID」エラーや、外部IDのフィールドが参照不可の状態になっている場合のエラーなどです。これらのエラーは、多くの場合、外部IDが未設定のレコードが存在する、または外部IDのインデックスが正しく機能していないことが原因です。

原因を切り分ける基本手順

問題が発生したときに、まずどの範囲で調べるべきかを明確にする手順を説明します。以下の手順に沿って確認することで、原因を効率的に絞り込めます。

外部IDの定義を確認する

最初に、問題のオブジェクトで外部IDとして設定されている項目の定義を確認してください。具体的には、[設定] > [オブジェクトマネージャ] > 該当オブジェクト > [項目とリレーション] で対象項目を開き、「外部ID」チェックボックスがオンになっているか、また「一意」が設定されているかを確認します。もし「一意」がオフになっていると、重複エラーは発生しませんが、外部IDをupsertキーとして使うことはできません。また、データ型や文字数制限(外部IDは255文字まで)も確認します。

データの重複をチェックする

外部IDの重複エラーが疑われる場合、実際にデータベース上で重複が存在するかを確認します。SalesforceのSOQLやデータエクスポートを利用して、外部IDフィールドをGROUP BYしてカウントする方法が有効です。例えば、SELECT External_ID__c, COUNT(Id) FROM Account GROUP BY External_ID__c HAVING COUNT(Id) > 1 のようなクエリを実行すれば、重複している値を特定できます。もしインポート前のデータに重複がある場合は、データクリーニングを行ってから再試行します。

ユーザ権限とプロファイルを確認する

エラーが特定のユーザでのみ発生する場合、権限が原因である可能性があります。外部IDとして使う項目の参照権限や編集権限が正しく付与されているかを確認してください。特に、プロファイルまたは権限セットで「読み取り」「作成」「編集」が許可されているか、また項目レベルのセキュリティで参照不可になっていないかをチェックします。管理者に依頼して、テストユーザで権限を検証することも有効です。

本番反映前に実施すべきチェックリスト

本番環境への反映作業を安全に進めるため、以下のチェックリストを事前に完了しておくことを推奨します。各項目はSandbox環境で検証してから本番に適用してください。

1. Sandboxで外部IDの設定を確認する: 本番と同じ設定でSandboxのオブジェクトに外部ID項目を設定し、データローダやAPIを使ってupsertが正常に動作することを確認します。
2. テストデータで重複がないか検証する: Sandboxにテストレコードを作成し、外部IDの重複値を意図的に入力してエラーが正しく発生するか、業務ルールに沿った動作かを確認します。
3. データローダで大量データのインポートテストを実施する: 数百件以上のレコードを外部IDを使ってインポートし、パフォーマンス問題やタイムアウトが発生しないか確認します。外部IDのインデックスが有効な場合は、インポート速度が向上するはずです。
4. 権限設定を本番と一致させる: 該当オブジェクトに対するプロファイルや権限セットの設定をレビューし、一般ユーザやAPIユーザが外部IDを参照・編集できるかを確認します。
5. バックアップを取得する: 外部IDの設定変更やデータインポート前に、既存のレコードをエクスポートしてバックアップを保管します。これにより、問題が発生しても元に戻せる状態を確保します。

よくある失敗パターンと回避方法

外部IDの運用で頻繁に遭遇する失敗パターンを以下にまとめました。これらのパターンを事前に把握しておくことで、本番環境でのトラブルを未然に防げます。

失敗パターン	原因	回避方法
外部IDにnullを許可しない設定で空値をインポート	項目定義で「NULL値を許可しない」にチェックがある場合、外部IDが空のレコードを作成しようとするとエラー	インポート前にデータのnullチェックを行い、空欄があればデフォルト値を設定するか、許可設定をオフにする
異なるオブジェクトで同じ外部ID値を使う	外部IDの一意制約はオブジェクト単位であり、オブジェクト間での重複はエラーにならないが、設計上の混乱を招く	命名規則を統一し、オブジェクトごとにプレフィックスを付けるなどの対策をとる
APIでのupsert時に外部IDの値が大文字小文字不一致	外部IDの値は大文字小文字を区別するため、データ側とDB側で表記が異なると別レコード扱いになる	インポート前に値の正規化(大文字統一など)を行うか、データを洗い出す
外部IDを後から変更しようとする	外部IDは一度設定すると、レコードが参照されている場合に変更が制限されることがある	変更前に外部IDを使用しているレコードやシステム連携を全て停止し、一括更新処理をテスト環境で検証する

管理者に確認すべき情報と依頼内容

問題の切り分けが進んでも、設定変更やデータ修正には管理者権限が必要な場合があります。以下の情報を整理して管理者に伝えると、迅速な対応が期待できます。

• エラーメッセージと発生状況: どの操作(データローダ、Apex、APIなど)で、どのようなエラーメッセージが表示されたかを詳細に伝えます。エラーログがある場合は添付します。
• 該当オブジェクトと外部ID項目名: 問題が発生しているオブジェクトのAPI参照名と、外部IDとして設定している項目名を明確にします。
• 権限設定の確認依頼: 一般ユーザやAPIユーザが外部IDを参照・編集できる権限を持っているか、プロファイルや権限セットを確認してもらいます。
• 重複ルールの状態: 重複ルールが有効になっている場合、外部IDの重複チェックの条件を確認し、必要に応じて一時的に無効化できるか相談します。
• Sandbox環境の提供: 本番に影響を与えずに検証するため、Sandbox環境の作成やリフレッシュを依頼します。

よくある質問(FAQ)

外部IDと主キー(Id)の違いは何ですか?

主キーはSalesforceが自動生成する15桁または18桁のIDで、変更できません。外部IDはユーザが任意の値を設定できる項目で、外部システムとの連携などに使われます。外部IDは一意制約を設定することで主キーの代わりにupsertキーとして使用できます。

外部IDは後から変更できますか?

外部IDの値は通常の項目として更新可能ですが、その項目が外部IDとして設定されているかどうかは、一度設定を外さないと変更できません。外部IDとしての使用をやめる場合は、事前にその外部IDを使用しているプロセスやルールを全て確認し、影響がないことを確かめてから変更する必要があります。

外部IDの最大長はどのくらいですか?

外部IDとして使用できる項目の最大文字数は255文字です。数値型の外部IDは最大桁数が指定されている場合がありますので、詳細はSalesforceのドキュメントを参照してください。

まとめ

本番環境に外部IDの設定を反映する前に、Sandboxで十分な検証と切り分けを行うことが重要です。まずは外部IDの定義、データの重複、権限の3つを必ず確認し、エラーの原因を特定します。本記事で紹介したチェックリストを活用すれば、本番デプロイ時のリスクを大幅に低減できます。外部IDは正しく設定すれば強力な連携ツールとなりますが、一度問題が発生すると影響範囲が広くなりがちです。トラブルが起きた際は、慌てずに原因を一つひとつ切り分け、管理者と連携して対処してください。