Microsoft Dynamics 365 の取り込みに関するトラブルシューティング

備考

プレビュー

この機能はパブリックプレビュー段階です。

このページではLakeFlow ConnectのMicrosoft Dynamics 365 コネクタに関する一般的な問題に関するトラブルシューティングガイダンスを提供します。

Azure Synapse Link の問題

Synapse Link がデータをエクスポートしない

症状：

Synapse Link を構成した後、ADLS Gen2 コンテナーにフォルダーが表示されません。
フォルダーのタイムスタンプの更新が停止します。
パイプラインの実行が「データが見つかりません」というエラーで失敗します。

考えられる原因:

Synapse Link 接続を停止する、または停止しました。
Azure ストレージアカウントのアクセス許可が正しくありません。
選択したテーブルはエクスポート用に構成されていません。
Synapse Link のエクスポート中にエラーが発生しました。

ソリューション:

Synapse Link のステータスを確認します。
- Power Appsにサインインします。
- 環境内の Azure Synapse Link に移動します。
- 接続が「アクティブ」ステータスになっていることを確認します。
- 停止する場合は、 「再開」 を選択してエクスポートを再開します。
ストレージ権限を確認します。
- Azure ポータルで、ストレージアカウントに移動します。
- アクセス制御 (IAM) を選択します。
- Synapse Link マネージド ID に ストレージ BLOB データ共同作成者 ロールがあることを確認します。
- 不足している場合は、ロールの割り当てを追加します。
テーブル構成を確認します:
- Power Apps で、Synapse Link 接続を選択します。
- 選択したテーブルのリストを確認します。
- 取り込むテーブルが含まれていることを確認します。
- 不足しているテーブルを追加し、最初のエクスポートを待ちます (5 ～ 15 分)。
Synapse Link ログを確認します。
- Power Apps で、Synapse Link 接続を選択します。
- [ログの表示] または [履歴] を選択します。
- エクスポートの失敗を示すエラーメッセージを探します。
- 特定のエラー (ストレージクォータ、アクセス許可など) に対処します。

FILE_PATH_DOES_NOT_EXIST エラー

症状：

パイプラインの実行はFILE_PATH_DOES_NOT_EXISTエラーで失敗しました。
コネクタは ADLS Gen2 で予期されたファイルを見つけることができません。
エラーは、フォルダーまたはファイルパスが見つからないことを示します。

考えられる原因:

Synapse Link 構成で 、増分更新フォルダー構造を有効にする オプションが有効になっていません。
コネクタは存在しない特定のフォルダー構造を想定しています。

ソリューション:

増分更新フォルダー構造を有効にする:
- Power Apps で、Synapse Link 接続を編集します。
- 詳細な構成設定を表示するには、 「詳細」 を選択します。
- 有効にするには、 「増分更新フォルダー構造を 有効にする」を切り替えます。
- 設定を保存します。
- Synapse Link がフォルダー構造を再生成するまで待ちます (大規模なデータセットの場合は数時間かかる場合があります)。
フォルダ構造を確認します:
- Azure ポータルで、ADLS Gen2 ストレージアカウントとコンテナーに移動します。
- テーブルフォルダーにタイムスタンプ付きのサブフォルダー (たとえば、 2025-12-19T10-30-00-000Z ) が含まれていることを確認します。
- これらのタイムスタンプ付きフォルダーには、コネクタに必要な増分更新が含まれています。
パイプラインを再試行します。
- 増分フォルダー構造を有効にした後、パイプラインを再度実行します。
- コネクタは予期された場所でファイルを見つけるはずです。

Synapse Link は設定されているが、ファイルが表示されない

症状：

Synapse Link は「アクティブ」ステータスを示していますが、ADLS Gen2 コンテナーに CSV ファイルが表示されません。
パイプラインの実行が「データが見つかりません」またはファイル形式エラーで失敗します。

考えられる原因:

Synapse Link は、CSV 形式ではなく Parquet 形式でデータをエクスポートするように構成されています。
Azure Synapse Analytics ワークスペースへの接続 オプションが選択され、Parquet エクスポートが強制されます。

ソリューション:

ADLS Gen2 でファイル形式を確認します。
- Azure ポータルで、ADLS Gen2 ストレージアカウントとコンテナーに移動します。
- テーブルフォルダーを開き、ファイル拡張子を確認します。
- ファイルの拡張子が.csvではなく.parquetの場合、形式が正しくありません。
CSV エクスポート用に Synapse Link を再構成します。
- Dynamics 365 コネクタは CSV 形式のみをサポートします。Synapse Link を再設定する必要があります。
- Power Apps で、Synapse Link 接続を編集または再作成します。
- [Azure Synapse Analytics ワークスペースに接続する ] チェックボックスを オフにします 。
- これにより、データは Parquet ではなく CSV 形式でエクスポートされるようになります。
- 構成を保存し、Synapse Link がデータを再度エクスポートするまで待ちます (大規模なデータセットの場合は数時間かかる場合があります)。
CSV ファイルが作成されたことを確認します。
- 再構成後、ADLS Gen2 コンテナーを確認します。
- 新しいフォルダーに.csvファイルが含まれていることを確認します。
- CSV ファイルが表示されたら、パイプラインの実行を再試行します。

Synapse Link の変更ログにバージョン番号がありません

症状：

パイプラインの実行が「VersionNumber フィールドが見つかりません」というエラーで失敗します。
増分取り込みは機能しません。
完全な更新のみが成功します。

考えられる原因:

Synapse Link は変更ログをエクスポートするように構成されていません。
テーブルの変更追跡は有効になっていません。
Synapse Link のバージョンが古くなっています。

ソリューション:

変更追跡を有効にする:
- Power Apps で、Synapse Link 接続を編集します。
- 「変更追跡を有効にする」 が選択されていることを確認します。
- 保存して、Synapse Link がエクスポートを再生成するまで待ちます (最大 30 分)。
変更ログファイルを確認します。
- Azure ポータルで、ADLS Gen2 コンテナーに移動します。
- テーブルフォルダーを開き、 SynapseLinkサブフォルダーを見つけます。
- 最近の変更ログファイル (CSV または JSON) を開きます。
- ファイルにVersionNumber列が含まれていることを確認してください。
- 不足している場合は、Microsoft サポートに連絡して変更の追跡を有効にしてください。
Synapse リンクを更新:
- Azure Synapse Link for Dataverse バージョン 1.0 以降を使用していることを確認します。
- 古いバージョンではVersionNumberがサポートされていない可能性があります。
- 必要に応じて Synapse Link を最新バージョンに更新します。
完全更新を実行します。
- 変更追跡を有効にできない場合は、完全更新モードのみを使用できます。
- 完全更新では実行ごとにすべてのデータが再ロードされるため、速度が遅くなり、コストも高くなることに注意してください。

認証の問題

Entra ID認証に失敗しました

症状：

「認証に失敗しました」というエラーが発生し、パイプラインの作成に失敗します。
カタログエクスプローラーで接続テストが失敗します。
パイプラインの実行が「401 Unauthorized」エラーで失敗します。

考えられる原因:

テナント ID、クライアント ID、またはクライアントシークレットが正しくありません。
クライアントシークレットの有効期限が切れました。
アプリケーションに必要な権限がありません。
指定された範囲が正しくありません。

ソリューション:

認証を確認してください:
- Azure ポータルで、 Microsoft Entra ID > アプリの登録 に移動します。
- アプリケーションを見つけて確認します。
  - アプリケーション (クライアント) ID は 接続構成と一致します。
  - ディレクトリ (テナント) ID は 接続構成と一致します。
- 正しい値をコピーし、必要に応じて接続を更新します。
クライアントシークレットの有効期限を確認します。
- アプリケーションで、 [証明書とシークレット] を選択します。
- クライアントシークレットの有効期限が切れていないことを確認してください。
- 期限が切れている場合は、新しいシークレットを作成します。
  - + 新しいクライアントシークレット を選択します。
  - 説明と有効期限を入力します。
  - 秘密の値をコピーします。
  - 新しいシークレットを使用して接続を更新します。
スコープを確認します:
- 接続で正しいスコープが使用されていることを確認します。 https://storage.azure.com/.default
- このスコープは、Dynamics 365 ではなく、Azure Storage へのアクセスを直接許可します。
テスト接続:
- カタログエクスプローラーで、接続に移動します。
- 認証を確認するには、 「テスト接続」 を選択します。
- テストが失敗した場合は、具体的なガイダンスについてはエラーメッセージを確認してください。

ADLS Gen2ストレージにアクセスできません

症状：

パイプラインの実行は、「403 禁止」または「アクセスが拒否されました」というエラーで失敗します。
接続テストは成功しましたが、パイプラインは失敗しました。
一部のテーブルは動作しますが、他のテーブルは動作しません。

考えられる原因:

Entra ID アプリケーションには、ストレージ BLOB データ共同作成者ロールがありません。
ロールの割り当ての範囲が間違ったコンテナーまたはパスに設定されています。
ネットワーク制限によりアクセスがブロックされます。
ストレージアカウントのファイアウォールルールにより、Databricks へのアクセスがブロックされます。

ソリューション:

ロールの割り当てを確認します。
- Azure ポータルで、ストレージアカウントに移動します。
- アクセス制御 (IAM) を選択します。
- ロールの割り当て を選択します。
- Entra ID アプリケーションに ストレージ BLOB データコントリビューター ロールがあることを確認します。
- スコープが 特定のコンテナーではなく、ストレージアカウント全体に設定されていることを確認します。
不足しているロールを追加します:
- + 追加 > ロールの割り当ての 追加を選択します。
- Storage Blob Data Contributor を検索します。
- 「次へ」 を選択してアプリケーションを追加します。
- [レビュー + 割り当て] を選択します。
- 権限の変更が反映されるまで 5 ～ 10 分ほどお待ちください。
ネットワーク制限を確認してください:
- ストレージアカウントで、 [ネットワーク] を選択します。
- すべてのネットワークから パブリックネットワークアクセス が有効になっているか、Databricks IP 範囲が含まれていることを確認します。
- プライベートエンドポイントを使用する場合は、Databricks がそれらにルーティングできることを確認します。
ファイアウォールルールを確認します。
- [ネットワーク] で、 ファイアウォールの 設定を確認します。
- 必要に応じて、Databricks IP アドレスを許可リストに追加します。
- または、 信頼できるサービスリストで Azure サービスを許可するを 有効にします。

仮想エンティティの問題

スキーマ検出に表示されない仮想エンティティ

症状：

テーブルを一覧表示するときに仮想エンティティは表示されません。
仮想エンティティの「テーブルが見つかりません」エラーによりパイプラインの作成が失敗します。
検出可能なのは、Dataverse ネイティブテーブルのみです。

考えられる原因:

仮想エンティティは構成または同期されていません。
Synapse Link は仮想エンティティをエクスポートしません。
仮想エンティティ名がテーブル構成と一致しません。

ソリューション:

仮想エンティティの構成を確認します。
- Power Platform 管理センターで、環境に移動します。
- [設定] > [製品] > [機能] に移動します。
- 仮想エンティティのデータソース が有効になっていることを確認します。
- F&O 仮想エンティティが構成され、アクティブであることを確認します。
同期を待機します:
- 仮想エンティティは、構成後に同期するまでに最大 15 分かかる場合があります。
- 仮想エンティティが Dataverse に表示されるまで最大 30 分かかります。
- 同期期間後に再度確認してください。
Synapse Link に仮想エンティティが含まれていることを確認します。
- Power Apps で、Synapse Link 接続を編集します。
- 選択したテーブルを確認します。
- 仮想エンティティがエクスポートリストに含まれていることを確認します。
- 不足している仮想エンティティを追加して保存します。
仮想エンティティ名を確認します。
- 仮想エンティティの論理名は、F&O テーブル名と異なる場合があります。
- Power Apps で、 テーブル に移動し、仮想エンティティを見つけます。
- 正確な 論理名 をコピーし、パイプライン構成で使用します。

仮想エンティティスキーマの変更が反映されない

症状：

F&O の新しい列はターゲット Delta テーブルに表示されません。
パイプラインの実行は成功しましたが、データが不完全です。
パイプラインログ内のスキーマドリフトの警告。

考えられる原因:

仮想エンティティのメタデータが Dataverse で更新されません。
キャッシュされたスキーマを使用する Synapse Link。
仮想エンティティのスキーマ進化の制限。

ソリューション:

仮想エンティティのメタデータを更新します。
- Power Platform 管理センターで、環境に移動します。
- 仮想エンティティの 設定に移動します。
- 影響を受ける仮想エンティティの メタデータを更新を 選択します。
- メタデータが同期されるまで最大 30 分間待ちます。
Synapse Link エクスポートを再作成します。
- Power Apps で、Synapse Link 接続を編集します。
- 影響を受ける仮想エンティティをエクスポートリストから削除します。
- 保存して5分間待ちます。
- 仮想エンティティをエクスポートリストに再度追加します。
- 保存して、最初のエクスポートが完了するまで待ちます。
完全更新を実行します。
- 仮想エンティティスキーマの変更には、多くの場合、完全な更新が必要になります。
- パイプラインを停止します。
- 影響を受ける仮想エンティティのターゲット Delta テーブルを削除します。
- パイプラインを再起動して、更新されたスキーマでテーブルを再作成します。

スキーマ進化の問題

データ型の変更によりパイプライン障害が発生する

症状：

パイプラインの実行は、「型の不一致」または「キャストできません」というエラーで失敗します。
D365 の更新または構成の変更後、取り込みは停止します。
エラーメッセージは特定の列とデータ型を参照します。

考えられる原因:

D365 で列のデータ型が変更されました (たとえば、文字列から整数へ)。
ターゲットDeltaテーブルには、新しいデータと互換性のない古いスキーマがあります。
Synapse Link は新しい形式でデータをエクスポートしますが、ターゲットテーブルでは古い形式が想定されています。

ソリューション:

変更された列を識別します。
- パイプラインエラーログを確認して、影響を受ける列とテーブルを見つけます。
- Power Apps で、列の現在のデータ型のテーブル定義を確認します。
- ターゲット Delta テーブルスキーマと比較します。
  SQL
```
DESCRIBE main.d365_data.tablename;
```
完全更新を実行します。
- データ型を変更するには、テーブルを再作成するために完全な更新が必要です。
- 影響を受けるパイプラインを停止します。
- ターゲットテーブルを削除します。
  SQL
```
DROP TABLE IF EXISTS main.d365_data.tablename;
```
- パイプラインを再起動して、新しいスキーマでテーブルを再作成します。
将来の問題を防ぐ:
- スキーマを変更する前に、D365 管理者と調整してください。
- まず、非本番運用環境でスキーマの変更をテストします。
- メンテナンスウィンドウ中に完全更新をスケジュールします。

重要

Dynamics 365 コネクタは、データ型の変更を自動的に処理しません。テーブルスキーマを更新するには、完全更新を実行する必要があります。詳細については制限事項を参照してください。

列名の変更が正しく処理されない

症状：

名前を変更した列は、 NULL 値を持つ新しい列として表示されます。
古い列のデータは失われます。
ターゲットテーブルには、古い列名と新しい列名の両方があります。

考えられる原因:

コネクタは列の名前変更をドロップおよび追加の操作として扱います。
古い列名から新しい列名への自動データ移行は行われません。

ソリューション:

名前の変更が行われる前:
- 可能であれば、名前を変更する前に D365 管理者と連携して完全な更新を実行してください。
- これにより、新しい列名で履歴データが保持されます。
名前変更後:
- 完全更新を実行して、すべてのデータを新しい列名で再ロードします。
- 履歴データが新しい列に入力されます。

手動移行 (完全更新が不可能な場合):

完全な更新を実行できない場合は、データを手動で移行します。

SQL
-- Copy data from old column to new column
UPDATE main.d365_data.tablename
SET new_column_name = old_column_name
WHERE new_column_name IS NULL AND old_column_name IS NOT NULL;

-- Drop old column after verification
ALTER TABLE main.d365_data.tablename DROP COLUMN old_column_name;

ヒント

中断を最小限に抑えるには、スケジュールされたメンテナンス期間中に列の名前変更を計画し、直後に完全更新を実行します。

パフォーマンスの問題

初期同期に時間がかかりすぎます

症状：

パイプラインは完了せずに何時間も実行されます。
初期同期が予想よりも遅いです。
最初の実行中にパイプラインがタイムアウトするか失敗します。

考えられる原因:

ソーステーブルのデータ量が大きい。
Synapse Link のエクスポートが遅い。
ネットワーク帯域幅の制限。
1 つのパイプライン内のテーブルが多すぎます。

ソリューション:

より少ないテーブルから始めます:
- 小さなテーブルのサブセット (5 ～ 10 テーブル) を含むパイプラインを作成します。
- パイプラインが正しく動作することを確認します。
- 最初の検証後にテーブルを段階的に追加します。
Synapse Link のエクスポートを待ちます:
- パイプラインを実行する前に、Synapse Link が初期エクスポートを完了したことを確認します。
- Azure ポータルで、すべてのテーブルフォルダーにデータファイルが含まれていることを確認します。
- 大規模なデータセットの場合、最初の Synapse Link エクスポートには数時間かかることがあります。
複数のパイプラインに分割:
- 100 個のテーブルを持つ 1 つのパイプラインの代わりに、それぞれ 20 個のテーブルを持つ 5 つのパイプラインを作成します。
- リソースの可用性に基づいて、パイプラインを並列または順次実行します。
- このアプローチにより、個々のパイプラインの実行時間が短縮されます。
Azure 帯域幅を監視します。
- Azure Storage メトリクスでスロットリングや帯域幅の制限を確認してください。
- 調整されている場合は、ストレージアカウント層を増やすか、ネットワーク容量を追加します。

増分更新が遅い

症状：

増分パイプラインの実行には予想よりも時間がかかります。
パイプラインのパフォーマンスは時間の経過とともに低下します。
変更量が多いと遅延が発生します。

考えられる原因:

大きな変更ログファイル。
ADLS Gen2 に蓄積されるフォルダーが多すぎます。
頻繁に変更されるため、多数の小さなフォルダーが作成されます。

ソリューション:

パイプラインの実行頻度を増やす:
- 変更ログが大きい場合は、パイプラインをより頻繁に実行します。
- 小さくて頻繁に更新される変更ログファイルは、大きなファイルよりも処理速度が速くなります。
- 変更の多い環境では、1 時間ごとではなく 5 ～ 15 分ごとに実行します。
Synapse Link のエクスポート頻度を確認します。
- Power Apps で、Synapse Link のエクスポートスケジュールを確認します。
- Synapse Link は定期的に (通常は 5 ～ 15 分ごとに) フォルダーを作成します。
- パイプラインの実行を Synapse Link のエクスポート頻度に合わせて調整します。
古いエクスポートフォルダーをクリーンアップします。
- 古いエクスポートを削除するには、ストレージアカウントでライフサイクルポリシーを構成します。
- 回復のニーズに応じて、過去 7 ～ 30 日間のエクスポートのみを保持します。
- これにより、コネクタがスキャンする必要があるフォルダーの数が減ります。
小銭の量を減らす:
- 高頻度の更新を生成する D365 プロセスを確認します。
- 可能な場合はバッチ更新を実行して、個々の変更イベントを減らします。
- すべての更新をキャプチャする必要があるかどうかを検討します (一部は一時的なものである可能性があります)。

データ品質の問題

取り込み後のレコードの欠落

症状：

ターゲットテーブルの行数がソーステーブルと一致しません。
ターゲットテーブルから特定のレコードが欠落しています。
断続的なデータギャップ。

考えられる原因:

Synapse Link のエクスポートが不完全です。
エラーのため、パイプラインはフォルダーをスキップしました。
ソースシステムでのフィルタリングまたは権限。
Synapse Link によってエクスポートされなかったレコードを削除します。

ソリューション:

レコード数を比較します:
- D365 で行数を確認します。
  SQL
```
-- In D365/Dataverse
SELECT COUNT(*) FROM account;
```
- ターゲット Delta テーブルの行数を確認します。
  SQL
```
-- In Databricks
SELECT COUNT(*) FROM main.d365_data.account;
```
- 差異の大きさを特定します。
Synapse Link の完全性を確認します。
- ADLS Gen2 では、すべてのテーブルフォルダーに最新のタイムスタンプフォルダーがあることを確認します。
- エクスポートの失敗を示す可能性のあるフォルダーのタイムスタンプのギャップを探します。
- ギャップが存在する場合、Synapse Link が一時的に停止している可能性があります。
フィルタリングを確認します:
- 一部の D365 テーブルには、表示されるレコードを制限するセキュリティフィルターがあります。
- Synapse Link サービスアカウントにすべてのレコードを表示する権限があることを確認します。
- レコードの所有権またはビジネスユニットフィルターが適用されているかどうかを確認します。
完全更新を実行します。
- レコードが継続的に欠落している場合は、完全更新を実行します。
- これにより、すべてのデータが再ロードされ、完全性が確保されます。
- 完全な更新後に再度カウントを比較します。
削除処理を確認します:
- D365 で不足しているレコードが削除された場合は、Synapse Link エクスポートの削除を確認してください。
- Power Apps で、削除追跡の Synapse Link 設定を確認します。
- 削除がエクスポートされない場合、削除されたレコードはターゲットテーブルに反映されません。

添付ファイルのメタデータが不完全です

症状：

添付ファイルテーブル (例: annotation 、 attachment ) に欠落したデータまたは不完全なデータがあります。
ファイル名またはメタデータが正しくありません。

考えられる原因:

Synapse Link は添付ファイルテーブルをエクスポートしません。
添付ファイルの権限により表示が制限されます。
添付ファイルデータは異なるテーブルに保存されます。

ソリューション:

添付ファイルテーブルがエクスポートされていることを確認します。
- Power Apps で、Synapse Link 接続を確認します。
- 添付ファイル関連のテーブルが含まれていることを確認します。
  - annotation （メモやファイル添付用）
  - attachment (電子メール添付用)
  - activitymimeattachment （アクティビティ添付ファイル用）
- 不足しているテーブルを追加し、エクスポートを待ちます。
添付ファイルの権限を確認してください:
- Synapse Link サービスアカウントが添付ファイルレコードを読み取ることができることを確認します。
- 一部の添付ファイルはセキュリティロールによって制限される場合があります。
- 必要に応じて権限を調整します。
メタデータのみの制限を理解する:
- Dynamics 365 コネクタは、ファイルの内容ではなく、添付ファイルのメタデータを取り込みます。
- ファイルをダウンロードするには、Dynamics 365 Web API を別途使用してください。
- 詳細については、制限事項を参照してください。

添付ファイルのメタデータをクエリします。

正しい添付ファイルフィールドをクエリしていることを確認します。

SQL
SELECT
  annotationid,
  objectid,
  subject,
  filename,
  filesize,
  mimetype,
  documentbody  -- Usually NULL; binary content not ingested
FROM main.d365_data.annotation;

追加サポート

このガイドを使用しても問題を解決できない場合:

診断情報を収集します:
- パイプライン ID と実行タイムスタンプ。
- パイプラインログからの完全なエラーメッセージ。
- Azure Synapse Link のログとステータス。
- エラーメッセージまたは構成のスクリーンショット。
既知の問題を確認してください:
- 既知の問題に対する制限事項を確認します。
- 最近の更新については、 Databricksリリースノートを確認してください。
サポートチケットを作成します:
- ワークスペースで、 [ヘルプ] > [サポートに問い合わせ] に移動します。
- テクニカルサポート を選択し、以下を入力します。
  - 問題の明確な説明。
  - ステップを実行して問題を再現します。
  - 上記で収集されたすべての診断情報。
  - 問題の影響と緊急性。
フィードバックを提供:
- ベータ版については、Databricks アカウントチームとフィードバックを共有してください。
- バグ、機能リクエスト、またはドキュメントの問題を報告します。

Synapse Link は設定されていますが、ファイルが表示されません

まず、ファイルが Synapse Link (Parquet ではない) によって CSV 形式で書き込まれていることを確認します。これを行うには、Azure Synapse Link にリンクするときに [Azure Synapse Analytics ワークスペースに接続する] チェックボックスをオフにします。

資格情報/ログインエラー

次のデバッグスクリプトを試してください。

クライアント ID とクライアントシークレットが正しく機能していることを確認します。

Python
%pip install azure-storage-blob azure-identity azure-storage-file-datalake
%restart_python

# Required libraries
from azure.identity import ClientSecretCredential
from azure.storage.blob import BlobServiceClient


# --- Your Azure Credentials and Storage Details ---
# Replace the placeholder values with your actual information


# Entra ID (Azure Active Directory) details
tenant_id = "<tenant-id>"
client_id = "<client-id>"
client_secret = "<client-secret>"


# Azure Storage details
storage_account_name = "<storage-account>"
container_name = "<container-name>"


# --- Script to List Folders ---


# Construct the Blob Storage URL
storage_account_url = f"https://{storage_account_name}.blob.core.windows.net"


# 1. Authenticate using the service principal
# The ClientSecretCredential object will handle the OAuth 2.0 flow
try:
   credential = ClientSecretCredential(tenant_id, client_id, client_secret)
except Exception as e:
   print(f"Error creating credential: {e}")
   # You may want to stop execution if credentials are not valid
   dbutils.notebook.exit("Failed to create credentials")


# 2. Create a BlobServiceClient
# This client is the main entry point for interacting with the Blob service
try:
   blob_service_client = BlobServiceClient(account_url=storage_account_url, credential=credential)
except Exception as e:
   print(f"Error creating BlobServiceClient: {e}")
   dbutils.notebook.exit("Failed to create BlobServiceClient")


# 3. Get a client for the specific container
try:
   container_client = blob_service_client.get_container_client(container_name)
except Exception as e:
   print(f"Error getting container client for '{container_name}': {e}")
   dbutils.notebook.exit("Failed to get container client")


# 4. List the "folders" in the container
# Folders in Blob Storage are virtual and are represented by prefixes in blob names.
# This code iterates through the blobs and extracts the top-level directory names.
try:
   blob_list = container_client.list_blobs()
   folder_list = set()


   for blob in blob_list:
       if "/" in blob.name:
           folder_name = blob.name.split('/')[0]
           folder_list.add(folder_name)


   # Print the list of unique folder names
   if folder_list:
       print(f"Folders found in container '{container_name}':")
       for folder in sorted(list(folder_list)):
           print(folder)
   else:
       print(f"No folders found in container '{container_name}'.")


except Exception as e:
   print(f"An error occurred while listing blobs: {e}")

Unity Catalog接続がアクセス許可を送信できることを確認します。

Python
import requests
import json
import os


# --- Databricks Notebook Context and API Token Retrieval ---
# This section securely retrieves the necessary API token from your Databricks environment
# to interact with Unity Catalog.
notebook_context = dbutils.notebook.entry_point.getDbutils().notebook().getContext()
WORKSPACE_URL = notebook_context.apiUrl().get()
API_TOKEN = notebook_context.apiToken().get()
# --- Unity Catalog Connection Configuration ---
# IMPORTANT: Replace with the name of your Unity Catalog external connection to ADLS Gen2.
# This connection must be configured in Unity Catalog and granted necessary permissions
# to access your Azure Data Lake Storage Gen2 account.
# Example: CONNECTION_NAME = "my_adls_gen2_connection"
CONNECTION_NAME = "<uc-connection-name>"
def get_uc_connection_access_token(connection_name: str, api_token: str) -> str:
   """
   Retrieves the access token for a Unity Catalog external connection to ADLS Gen2.
   """
   url = f"{WORKSPACE_URL}/api/2.1/unity-catalog/foreign-credentials"
   body = '{{"securables": [{{"type": "CONNECTION", "full_name": "{}"}}]}}'.format(
       connection_name
   )
   headers = {
       "Authorization": "Bearer {}".format(api_token),
       "Content-Type": "application/json",
   }
   response = requests.post(url=url, headers=headers, data=body)
   response.raise_for_status() # Raise an exception for HTTP errors (e.g., 401, 403, 404)

   print(response.json())


   credentials = response.json()["securable_to_credentials"][0]["credentials"]["foreign_credential"]["options"]["options"]
   access_token = credentials["access_token"]
   return access_token
 print(get_uc_connection_access_token(CONNECTION_NAME, API_TOKEN))


Verify we are able to list container contents using UC connection

import requests
import json
import os
from datetime import datetime, timedelta
from azure.core.credentials import AccessToken, TokenCredential
from azure.storage.filedatalake import DataLakeServiceClient


notebook_context = dbutils.notebook.entry_point.getDbutils().notebook().getContext()
WORKSPACE_URL = notebook_context.apiUrl().get()
API_TOKEN = notebook_context.apiToken().get()


CONNECTION_NAME = "<uc-connection-name>"
storage_account_name = "<storage-account-name>"
container_name = "<container-name>"
# --- Custom Credential Object for Azure SDK ---
class StaticTokenCredential(TokenCredential):
   """
   A simple credential class to wrap an existing access token for Azure SDKs.
   The expiration is set arbitrarily for the SDK's internal logic;
   your token's real expiry is governed by its issuer.
   """
   def __init__(self, token: str):
       self._token = AccessToken(token, expires_on=(datetime.now() + timedelta(hours=1)).timestamp())
   def get_token(self, *scopes, **kwargs) -> AccessToken:
       return self._token
# ==================== Main Logic to List Top-Level Folders ====================
try:
   # --- Input Validation ---
   if CONNECTION_NAME == "<YOUR_UNITY_CATALOG_CONNECTION_NAME>":
       raise ValueError("Please update 'CONNECTION_NAME' with the name of your Unity Catalog connection.")
   if storage_account_name == "<YOUR_STORAGE_ACCOUNT_NAME>":
       raise ValueError("Please update 'storage_account_name' with your Azure Storage Account Name.")
   if container_name == "<YOUR_CONTAINER_NAME>":
       raise ValueError("Please update 'container_name' with your ADLS Gen2 Container Name.")
   print(f"Retrieving access token from Unity Catalog connection: '{CONNECTION_NAME}'...")
   access_token_string = get_uc_connection_access_token(CONNECTION_NAME, API_TOKEN)
   print("Access token retrieved successfully.")
   # 1. Initialize the DataLakeServiceClient using the retrieved token
   account_url = f"https://{storage_account_name}.dfs.core.windows.net"
   credential = StaticTokenCredential(access_token_string)
   datalake_service_client = DataLakeServiceClient(account_url=account_url, credential=credential)
   file_system_client = datalake_service_client.get_file_system_client(file_system=container_name)

   print(f"\nSuccessfully connected to ADLS Gen2 container: '{container_name}' in storage account: '{storage_account_name}'.")

   # 2. Get and print only the top-level directories
   print("\n--- Listing Top-Level Folders ---")

   all_paths = file_system_client.get_paths(path="/")


   for path in all_paths:
     print(path.name)
except Exception as e:
   print(f"An unexpected error occurred during execution.")
   print(f"Error details: {e}")

エラー： `The selected storage account has restricted network access...`

The selected storage account has restricted network access. To proceed, please setup an enterprise policy and connect it to your Dataverse environment. Once done, please enable the 'Select Enterprise Policy with Managed Service Identity' option below.

これは、ADLS ステージング場所がファイアウォールによって保護されており、Dataverse がそこに到達できない場合に発生する可能性があります。Microsoftドキュメントの「 AzureデータレイクストレージでAzureのマネージド ID を使用する」に従って、データにアクセスするためのマネージド ID (旧マネージドサービス ID) を設定します。

エラー： `FILE_PATH_DOES_NOT_EXIST`

これは通常、Synapse Link の構成時に 「増分更新フォルダー構造を有効にする」 が切り替えられていない場合に発生します。その結果、コネクタは予期した場所でファイルを見つけることができません。

Azure Synapse Link の問題​

Synapse Link がデータをエクスポートしない​

FILE_PATH_DOES_NOT_EXIST エラー​

Synapse Link は設定されているが、ファイルが表示されない​

Synapse Link の変更ログにバージョン番号がありません​

認証の問題​

Entra ID認証に失敗しました​

ADLS Gen2ストレージにアクセスできません​

仮想エンティティの問題​

スキーマ検出に表示されない仮想エンティティ​

仮想エンティティスキーマの変更が反映されない​

スキーマ進化の問題​

データ型の変更によりパイプライン障害が発生する​

列名の変更が正しく処理されない​

パフォーマンスの問題​

初期同期に時間がかかりすぎます​

増分更新が遅い​

データ品質の問題​

取り込み後のレコードの欠落​

添付ファイルのメタデータが不完全です​

追加サポート​

Synapse Link は設定されていますが、ファイルが表示されません​

資格情報/ログインエラー​

エラー： The selected storage account has restricted network access...​

エラー： FILE_PATH_DOES_NOT_EXIST​

Azure Synapse Link の問題

Synapse Link がデータをエクスポートしない

FILE_PATH_DOES_NOT_EXIST エラー

Synapse Link は設定されているが、ファイルが表示されない

Synapse Link の変更ログにバージョン番号がありません

認証の問題

Entra ID認証に失敗しました

ADLS Gen2ストレージにアクセスできません

仮想エンティティの問題

スキーマ検出に表示されない仮想エンティティ

仮想エンティティスキーマの変更が反映されない

スキーマ進化の問題

データ型の変更によりパイプライン障害が発生する

列名の変更が正しく処理されない

パフォーマンスの問題

初期同期に時間がかかりすぎます

増分更新が遅い

データ品質の問題

取り込み後のレコードの欠落

添付ファイルのメタデータが不完全です

追加サポート

Synapse Link は設定されていますが、ファイルが表示されません

資格情報/ログインエラー

エラー： `The selected storage account has restricted network access...`

エラー： `FILE_PATH_DOES_NOT_EXIST`