Salesforce の取り込みのトラブルシューティング

このページでは、 Databricks Lakeflowコネクト の Salesforce インジェスト コネクタに関する一般的な問題とその解決方法について説明します。

一般的なパイプラインのトラブルシューティング

実行中にパイプラインが失敗した場合は、失敗したステップをクリックし、エラー メッセージにエラーの性質に関する十分な情報が含まれているかどうかを確認します。

また、右側のパネルで [Update details] をクリックし、[Logs] をクリックして、パイプラインの詳細ページからクラスター ログを確認してダウンロードすることもできます。 ログをスキャンしてエラーまたは例外を探します。

宣言型自動化バンドルを使用した列選択

発行：

宣言型自動化バンドルを使用して管理対象のデータ取り込みパイプラインを作成する場合、列選択機能は使用できません。

解決：

Databricks CLI のバージョンを確認します。バージョンがv0.251.0未満の場合、CLI を再インストールします。

ネットワーク接続とDNS解決の失敗

エラー ：

java.net.UnknownHostException: salesforce.com

または

Failed to connect to Salesforce: Connection refused

原因 ：

これらのエラーは通常、ネットワーク ポリシーによってコネクタが Salesforce ドメインを解決またはアクセスできないことを示しています。これは通常、適切な許可リスト構成なしで出力制御を使用する場合に発生します。

解決 ：

salesforce.comネットワーク ポリシーの許可リストに追加します。詳細については、 「 サーバレス出力制御に関するネットワーク ポリシーの管理 」を参照してください。

ファイアウォールと仮想ネットワークの設定により、ストレージ サービスへのアクセスがブロックされます

Firewalls and virtual networks' settings may be blocking access to storage services. Please verify your Azure storage credentials or firewall exception settings

この問題は、ネットワーク設定に起因します。トラブルシューティングを行うには、次の操作を試してください。

ケース	ソリューション
データソースは、 Databricks ワークスペースとは異なるリージョンにあります。	ネットワーク接続構成 (NCC) を作成します。次のことを確認してください。 ワークスペースにアタッチされています。 データソース専用のプライベートエンドポイントルールがあります。 プライベート エンドポイント ルールには、接続状態が establishedと表示されます。 NCC 設定に変更を加えた場合は、インジェスト パイプラインを再起動します。

LIMIT_EXCEEDED

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Salesforce API call. Source API type: CREATE_BULK_QUERY_JOB. Error code: LIMIT_EXCEEDED.
Try refreshing the destination table. If the issue persists, please file a ticket.

これは、Salesforce アカウントで API の制限に達した場合に発生します。最初のステップとして、API の制限がリセットされるのを待ってから、宛先テーブルを更新します。問題が解決しない場合は、チケットを提出してください。このエラーの蔓延を制限するには、スケジュールまたはインジェスト量を減らします。

INVALID_USER

[SAAS_CONNECTOR_SOURCE_API_ERROR] An error occurred in the Salesforce API call. Source API type: CREATE_BULK_QUERY_JOB. Error code: INVALID_USER.
Try refreshing the destination table. If the issue persists, please file a ticket.

Salesforce の開発者向けドキュメントには、このエラーには次の 2 つの理由があることが示されています。

• インジェスト パイプラインを実行しているユーザーに適切なアクセス許可がありません
• ジョブが、現在実行しているユーザーとは異なるユーザーによって作成されました

したがって、次のようにトラブルシューティングできます。

• 接続の資格情報が正しいことを確認します。これは、資格情報を修正することで解決できます。
• 接続の使用を開始した当初からユーザーが変更されているかどうかを確認します。これは、パイプラインを完全に更新することで解決できます。

問題が解決しない場合は、サポート チケットを提出してください。

STREAM_FAILED

STREAM_FAILED: Terminated with exception: Ingestion for object XYZ is incomplete because the Salesforce API query job took too long, failed, or was manually cancelled. To try again, you can either re-run the entire pipeline or refresh this specific destination table. If the error persists, file a ticket. SQLSTATE: XXKST

コネクタが Salesforce から取り込む場合、Salesforce クエリはエラーを返す可能性があります。これにはさまざまな理由があります (時間がかかりすぎる、失敗する、手動でキャンセルされるなど)。

このエラーは一時的なものである可能性があるため、まずはパイプラインを再試行するか、特定の宛先テーブルを更新することをお勧めします。それでも問題が解決しない場合は、サポート チケットを提出してください。

コピー先テーブルの行数がソース テーブルより少ない

The destination table has fewer rows than the source table.

コネクタは、ソース テーブルからすべての一意の行を取り込むことを目的としています。

まず、接続がテーブル内のすべてのローにアクセスできることを確認します。そこから、ソース テーブルに重複する行があるかどうかを確認します。これらは摂取されません。これらの問題のいずれも根本原因でない場合は、サポート チケットを提出してください。

テーブルは 1 つのパイプラインによってのみ所有できます

ExtendedAnalysisException: Table XYZ is already managed by pipeline ABC. A table can only be owned by one pipeline. Concurrent pipeline operations such as maintenance full refresh with conflict with each other. Please rename the table XYZ to proceed.

各宛先テーブルは、単一の取り込みパイプラインに対応します。「XYZ」という名前のテーブルを、既に「XYZ」という名前のテーブルが存在する宛先スキーマに書き込むパイプラインを作成しようとすると、パイプラインは失敗します。別の宛先スキーマに書き込むことができます。

新しく追加された列の Null 値

テーブルに新しい列が表示されるのは、次のいずれかの理由です。

• 新しい列がテーブルに追加されました。
• 列は常にテーブルに存在していましたが、ユーザーがアクセスできるようになったのはごく最近のことです。
• 列は常にソースに存在していましたが、以前はインジェストから除外されていましたが、ユーザーが最近含めました。

この問題は、2 番目のシナリオで発生します。既に取り込まれている行の場合、新しい列のデータは NULL になります。このデータをバックフィルするには、テーブルの完全更新を実行します。

(最初のシナリオでは、列は完全にバックフィルされます。3 番目のシナリオでは、この変更を行った後にパイプラインが失敗します。完全更新を実行してデータをリセットし、パイプラインの実行を続行できます)。

テーブルまたは列がありません

次の理由により、Salesforce オブジェクトまたは列が見つからない場合があります。

• オブジェクトまたは列にアクセスするための十分な Salesforce 権限がありません。

• 欠落している列は、次のものを表しています。

  • 複合 Salesforce オブジェクト項目 (住所、場所など)
  • base64 バイナリ フィールド

• Salesforce のテーブル名が、指定したテーブル名とは異なります。オブジェクト名では大文字と小文字が区別され、顧客オブジェクトには __c サフィックスが付きます。

OAuth を使用して Salesforce 接続を作成できませんでした

OAuth を使用して Salesforce への接続を作成しようとするとエラー (「無効なトークンの付与」など) が表示される場合:

1. OAuth 資格情報が正しいことを確認します。
2. Salesforce でサンドボックスインスタンスに接続しようとしている場合は、[ Is サンドボックス ] が選択されていることを確認します。

Salesforce 一括クエリ ジョブの失敗

Salesforce から大量のデータを取り込むと、コネクタは一括クエリ ジョブを Salesforce サーバーに送信してデータを取得します。次のようなエラーが表示される場合があります。

Ingestion for object `<object-name>` is incomplete because the Salesforce API query job took too long, failed, or was manually canceled. To try again, you can either re-run the entire pipeline or refresh this specific destination table. If the error persists, file a ticket. Job ID: 750TU00000DEdbWYAT. Job status: <Failed|Aborted|NOT_FOUND>.

この例では、一括クエリジョブが失敗したか、キャンセルされたか、Salesforce 側で削除されました。クエリが失敗した理由を調査するには、Salesforce UI の [一括データ読み込みジョブ ] ページにアクセスします。

https://<your-url>/lightning/setup/AsyncApiJobStatus/home

パイプラインを再試行すると、問題が解決する場合があります。

コネクタが予想よりも少ない行を取り込む

オブジェクト内のすべての行にアクセスできることを確認します。

新しい列に null 値があるのはなぜですか?

次の場合に、新しい列に null 値が表示されることがあります。

• パイプラインは、元のバージョンのテーブルで実行します。
• 列がデータソースに追加されます。
• パイプラインは、新しい列を含む新しいバージョンのテーブルで実行します。

Databricks 列の選択またはソースの更新により、初期読み込み後に新しい列が自動的に追加される場合、コネクタは以前のカーソル値から行をバックフィルします。ただし、新しい列へのアクセスを受け取った場合、コネクタはバックフィルされません。

これを解決するには、テーブルの完全更新を実行します。

invalid_grant、期限切れのアクセス/更新トークン

このエラーは、次のシナリオで発生します。

• 認証する Salesforce ユーザの接続が 4 つ以上ある。認証ユーザーが接続制限を超えていないことを確認します。
• Salesforce インスタンスで接続アプリケーションへのアクセスが制限されます。Databricks 接続アプリを許可リストに追加します。
• Salesforce UI で接続アプリケーションのアクセス権を取り消しました。
• Salesforce が異常なアクティビティを検出し、更新トークンを無効にしました。
• 接続アプリケーションの更新トークンの有効期限が切れました。

この問題を解決するには、接続を編集して再承認します。問題が解決しない場合は、サポートチケットを提出してください。

数式フィールドの値はNULLと表示されます (増分取り込み)

増分数式フィールド取り込みを使用すると、一部の数式フィールドにNULL値が表示される場合があります。これは、数式でサポートされていない関数または演算が使用されている場合に発生します。診断するには、エラー追跡テーブルをクエリします。

1. 特定のオブジェクト（たとえば、 Accountオブジェクト）でサポートされていない数式フィールドを確認するには、次の手順を実行します。

   SQL

   SELECT * FROM <pipeline-id>_formula_fields_error_reasons
   WHERE object_name = 'Account'

   すべてのオブジェクトでサポートされていないすべての数式フィールドを表示するには:

   SQL

   SELECT object_name, formula_field_name, error_message
   FROM <pipeline-id>_formula_fields_error_reasons
   ORDER BY object_name, formula_field_name

2. 「制限事項」でサポートされていない数式関数のリストを確認してください。

数式がサポートされていない場合、宛先テーブルのフィールドには常にNULL値が表示されます。サポートされていないフィールドを取り込むには、デフォルトのスナップショット アプローチを使用します。パイプラインの増分数式フィールドの取り込みを有効にしないでください。

パイプラインが小数点精度エラーで失敗する（数式フィールド）

エラー：

Pipeline failed: Formula field exceeds maximum decimal precision (38, 18)

これは、数式フィールドがDatabricksの小数精度制限を超える値を計算した場合に発生します。 値がdecimal(38,18)を超える数式フィールドは増分的に取り込むことはできません。

解決：

このパイプラインの増分数式フィールドの取り込みを無効にするか、 exclude_columns構成を使用して問題のある数式フィールドを除外します。「取り込む列の選択」を参照してください。

Salesforce認証エラー

エラー：

We can't authorize you because of an OAuth error. For more information, contact your Salesforce administrator. OAUTH_APPROVAL_ERROR_GENERIC: An unexpected error has occurred during authentication. Please try again.

原因：

これは、Salesforce が接続アプリケーションの要件に変更を加えたことが原因であると考えられます。歴史的には、認証プロセスの一部として同意するだけで十分でした。しかし、2025 年 9 月、Salesforce はアンインストールされた接続アプリの使用を制限し始めました。

ソリューション:

初回認証を成功させるために必要な権限がない場合は、接続を作成または再認証するときに、管理者が Salesforce インスタンスに Databricks 接続アプリをインストールする必要があります。Salesforceを参照してください。

追加のリソース

• Salesforce 取り込みコネクタの制限
• Salesforce 取り込み コネクタのリファレンス