Fabric 連携説明
対象者：顧客 Azure 管理者、プラットフォーム管理者、導入コンサルタント 説明範囲：Microsoft Fabric を Analytics データソース として利用する際の連携ロジックと設定要点 位置づけ：本書は「データソース連携」シナリオのみを対象とし、ベクトルDB方案 には触れず、また MCP の事前設定機能についても詳述しません
適用範囲とバージョン境界
サポート対象：
- プラットフォームが顧客の Microsoft Fabric の SQL Endpoint / Warehouse に接続し、Analytics データソースとして利用します：テーブル/ビューの参照、メタデータの同期、データプレビュー、分析レポートでの利用。
- 認証方式は SSO（Entra ID OAuth、サービスプリンシパル Service Principal ベース） をデフォルトかつ推奨方式とし、従来の ユーザー名/パスワード認証 も互換オプションとして保持します。
- SSO は 2 種類のトークン管理モードをサポートします：
- Zero-Trust（デフォルト）：短期の access token のみを保存し、refresh token は永続化しません。トークン期限切れ後は再度認可フローを実行する必要があります。
- Token-Refresh：完全な MSAL トークンキャッシュ（refresh token を含む）を永続化し、サイレント更新をサポートして、手動での再認可頻度を減らします。
サポート対象外：
- 本書では、Fabric をナレッジベースのベクトルストレージとして利用 する方案は扱いません（この種の要件がある場合は、別途ベクトルDB関連ドキュメントを参照してください）。
- Fabric 関連の MCP（Model Context Protocol）事前設定機能については詳述しません。これは別の独立した機能領域に属します。
- Fabric データソースではポート番号設定を使用しません（Fabric SQL Endpoint は HTTPS レイヤープロトコルを使用するため、追加ポートは不要です）。
- プラットフォームは Fabric ワークスペース（Workspace）、Warehouse/Lakehouse の作成および権限付与を担当しません。これらは管理者が実施する必要があります。
前提条件チェックリスト
| カテゴリ | 前提条件 |
|---|---|
| 権限 | Entra ID でアプリ登録（サービスプリンシパル）の権限を持っていること；当該サービスプリンシパルは Fabric 管理センターで対象 Workspace/Warehouse へのアクセス権（例：Viewer/Contributor。Fabric の権限モデルに応じて Fabric 管理者が設定）を付与されている必要があります。 |
| アカウント | Client ID / Client Secret / Tenant ID（サービスプリンシパルの 3 要素）；SSO モードでは追加のユーザー名/パスワードは不要です。 |
| ネットワーク | プラットフォームサーバーが Fabric SQL Endpoint（例：<workspace>.fabric.microsoft.com または <warehouse>-<id>.datawarehouse.fabric.microsoft.com）および Entra ID ログインエンドポイントにアクセスできる必要があります。 |
| リソース準備 | 対象 Warehouse/Lakehouse 名称（database フィールドに対応）；プラットフォームのデプロイ環境で FABRIC_REDIRECT_URI などの OAuth コールバック環境変数が正しく設定されていることを確認してください。 |
| ⚠️ 要確認 | サービスプリンシパルの Fabric 側での具体的な権限範囲（対象 Warehouse の読み取り権限を含むか）；繰り返し認可を減らすために Token-Refresh モードを使用する必要があるか。 |
Azure 側の設定要点
- サービスプリンシパルを登録：Azure Portal → Entra ID → アプリの登録 でアプリを作成し、Client ID、Tenant ID を記録します。
- Client Secret を作成：アプリの「証明書とシークレット」でキーを作成し、シークレット値を安全に保管します。
- Fabric 側で認可：Fabric 管理センター（または対象 Workspace のアクセス権設定）で、このサービスプリンシパルを Workspace メンバーとして追加し、対象 Warehouse/Lakehouse へのアクセスに必要な権限を付与します。
- SQL Endpoint アドレスを確認：Fabric Workspace で Warehouse/Lakehouse の SQL Endpoint 接続文字列を確認します。形式は
<workspace>.fabric.microsoft.comまたは<warehouse>-<id>.datawarehouse.fabric.microsoft.comです。 - テナントでサービスプリンシパルの Fabric アクセスが許可されているか確認：一部のテナントでは、サービスプリンシパルによる Fabric API へのアクセスがデフォルトで無効になっている場合があります。管理者が Fabric テナント設定で「サービスプリンシパルは Fabric API を使用できる」関連オプションを有効にする必要があります。
プラットフォーム側の入力要点
| フィールド名 | 必須 | 説明 |
|---|---|---|
| ホストアドレス（Host） | ✅ | Fabric SQL Endpoint / Warehouse サーバーアドレス。例：<workspace>.fabric.microsoft.com |
| データベース名（Database Name） | ✅ | 対象 Warehouse または Lakehouse の名称 |
| 認証タイプ（Auth Type） | ✅ | OAuth サービスプリンシパル認証には sso（推奨）を選択し、ユーザー名/パスワードには password（旧モード互換）を選択します |
| クライアント ID（Client ID） | SSO 時必須 | Entra サービスプリンシパルの Client ID（アプリケーション ID） |
| テナント ID（Tenant ID） | SSO 時必須 | Azure AD テナント ID（Directory ID） |
| クライアントシークレット/パスワード | ✅ | SSO モードでは Client Secret を入力；パスワードモードではユーザーパスワードを入力し、いずれもプラットフォームで RSA 暗号化保存されます |
| トークンモード（Mode） | 任意 | zero_trust（デフォルト、トークン期限切れ時に再認可が必要）または token_refresh（自動更新対応、長期利用推奨） |
| ユーザー名 | パスワードモード時必須 | SSO モードでは入力不要 |
| スキーマ（Schema） | 任意 | データベーススキーマ名。空欄の場合はデフォルトスキーマを使用します |
| ポート | 使用しない | Fabric ではポート番号の設定は不要です |
入力と認可フロー：
- 左側で接続情報（ホストアドレス、データベース名、Client ID、Tenant ID）を入力します。
- 右側で認証情報（クライアントシークレット、認証タイプ、トークンモード）を入力します。
- 「認可を開始」（Authenticate ボタン）をクリックすると、システムが Microsoft ログインページへ遷移します。
- 顧客の Azure 管理者がログインと認可同意を完了すると、Microsoft のコールバックでトークン交換が完了し、データソース状態が「認可済み」に更新されます。
- 認可成功後、「接続テスト」をクリックして利用可能性を確認します。
具体的な操作ガイド
データソース作成ページに入る
- Data 画面で、データソースの入口を見つけます
- 「データソースを作成」または「新規データソース」ボタンをクリックします
- ポップアップ表示されるデータソースタイプ選択ダイアログで、Fabric を選択します
基本接続情報を入力する
左側のフォームに以下の必須項目を入力します：
Host（ホストアドレス）*
- Fabric サービスの SQL Endpoint アドレスを入力します
- 例：
<workspace>.fabric.microsoft.comまたは<warehouse>-<id>.datawarehouse.fabric.microsoft.com
Database Name（データベース名）*
- Warehouse 名を入力します
- その Warehouse が Fabric インスタンス内に既に存在していることを確認してください
Client ID（クライアント ID）*
- Azure AD アプリケーション（サービスプリンシパル）の Client ID を入力します
- この情報は Azure Portal のアプリ登録で確認できます
Schema（スキーマ）
- （任意）データベーススキーマ名を入力します
- 指定しない場合は、デフォルトスキーマが使用されます
認証情報を入力する
右側のフォームに以下の必須項目を入力します：
Client Secret（クライアントシークレット）*
- Azure AD アプリケー ションのクライアントシークレットを入力します
- 注意：このシークレットには有効期限があるため、期限切れでないことを確認してください
- 重要：このシークレットは適切に保管し、漏洩させないでください
Tenant ID（テナント ID）*
- Azure AD テナント ID（Directory ID）を入力します
- Azure Portal の Azure Active Directory 概要で確認できます
Auth Type（認証タイプ）*
- OAuth のサービスプリンシパルベース認証には
sso（推奨）を選択します - 旧モード互換として
passwordも選択可能です（非推奨）
Mode（トークンモード）
zero_trust（デフォルト）：refresh token を永続化せず、access token の期限切れ後に再認可が必要ですtoken_refresh：完全な MSAL キャッシュを永続化し、サイレント更新をサポートして再認可頻度を減らします
Auto Refresh Token（トークン自動更新）
- このオプションを有効にすると、アクセス トークンを自動更新できます
- 長時間実行されるクエリがトークン期限切れで失敗しないよう、有効化を推奨します
接続を検証する
- すべての必須フィールド（* が付いた項目）が正しく入力されていることを確認します
- ページ下部の "Authenticate"（認証）ボタンをクリックします
- システムは自動的に Microsoft アカウントのログインページへ遷移します
- Fabric 権限を持つアカウントでログインし、認可を完了します
- ログイン成功後、データソース状態が「認可済み」に更新され、Fabric データソースへの接続が成功します
テストと検証
認可完了後、以下の手順で接続の利用可能性を確認します：
- 「接続テスト」をクリックすると、システムが可視なテーブルとビューを検出して一覧表示します
- 少なくとも 1 つの重要テーブルに対して「 テーブル構造を同期」を実行し、フィールド情報を確認します
- そのテーブルに対して「データプレビュー」を実行し、正常にデータを取得できることを確認します
- Token-Refresh モードを使用している場合は、一定時間後に再度クエリを実行し、サイレント更新が有効に機能しているか確認することを推奨します
よくある問題と切り分け手順
| 問題分類 | 現象 | 想定原因 | 切り分けの提案 |
|---|---|---|---|
| 認証失敗/トークン期限切れ | 「Fabric アクセストークンを取得できません。OAuth でデータソースを再認可してください」と表示される | Zero-Trust モードで access token が期限切れ；Token-Refresh モードで refresh token が無効化、またはサイレント更新に失敗 | OAuth 認可フローを再実行してください；頻繁に発生する場合は Token-Refresh モードへの切り替えを推奨します |
| 認証未完了 | 「データソースはまだ正常に認証されていません。先に認証フローを完了してください」と表示される | OAuth 認可が未実施、または認可状態がリセットされた | 管理者が一度認可ログインを完了してください |
| SSO パラメータ不足 | 認可開始時に「SSO 認証が設定されていません」関連エラーが表示される | auth_type が sso に設定されていない、または client_id/tenant_id が未入力 | others.auth_type=sso および client_id/tenant_id を確認・補完し、client_secret は password フィールドに保存してください |
| エンドポイント/接続タイムアウト | 接続テストが長時間応答しない、またはタイムアウトする | SQL Endpoint アドレス誤り；ネットワークポリシー制限；Fabric Workspace/Warehouse が利用可能状態でない | SQL Endpoint アドレスを再確認；ネットワーク出口ポリシーを確認；Warehouse/Lakehouse の状態が正常であることを確認してください |
| 権限不足 | 接続テストは成功するがテーブル/ビュー一覧が空、またはクエリで権限エラーが発生する | サービスプリンシパルに当該 Workspace/Warehouse へのアクセス権が付与されていない | Fabric 管理者に依頼し、Workspace 権限設定で当該サービスプリンシパルを追加し、適切なロールを付与してください |
| Microsoft 側認証エラー（AADSTS 系列） | 認可コールバックで error=AADSTSxxxxxx が返る | Client ID/Secret の誤り、テナントポリシー制限、サービスプリンシパル無効化など | 具体的な AADSTS エラーコードに基づき、Azure Portal でアプリ状態やテナントポリシー（例：条件付きアクセス ポリシーがサービスプリンシパルのログインをブロックしていないか）を確認してください |
| 一般的な接続失敗 | 「データソース接続に失敗しました」と表示される | ネットワークタイムアウト、Fabric サービスの一時的な利用不可、ドライバー異常 | しばらくして から再試行してください；Fabric サービス状態ページを確認してください；必要に応じてネットワーク/セキュリティチームへ調査を依頼してください |