備註
Fabric Connection 與筆記型電腦的整合目前處於預覽階段。
與 Fabric Connect 的整合讓你能直接從筆記本使用外部資料來源。 你可以重複使用現有的連線和憑證,這讓你更容易處理不同資料來源,也能讓你在筆記本中享受順暢的編碼體驗。
要在筆記本中使用 Fabric Connection,你需要在 Fabric 資料來源管理頁面明確啟用該連線才能在筆記本中使用。 有一個特定的勾選框可以啟用該連線,稱為 允許像筆記本這樣的 Code-First Artifacts 存取此連線(預覽)。 這個勾選框只能在建立時設定,之後無法修改。
以下是筆記型電腦中支援的 Fabric Connect 認證方法:
- Basic Authentication:支援 Azure SQL Database 及其他支援基本認證的資料庫。
- 帳號金鑰驗證:支援需要帳號金鑰驗證的 REST API 資料來源。
- 憑證認證:支援需要憑證認證的資料來源。
- Workspace 身份驗證:支援 Fabric 工作空間身份驗證。
- 服務主體認證(SPN):支援用於需要SPN認證的資料來源。
這很重要
在筆記本中,Fabric Connection 不支援 OAuth2.0。 如果你選擇工作區身份驗證或 SPN,務必授予 Fabric 工作區身份存取資料來源所需的權限。 關於每個連接器的詳細設定資訊,請參閱 資料來源管理。
有一個租戶層級設定,讓租戶管理員可以控制是否啟用這個功能給整個租戶。 如果這個設定被停用,使用者就無法在筆記本中使用 Fabric Connection。 預設會啟用此功能。
如何為數位筆記本建立 Fabric 連結
建立筆記本電腦的 Fabric 連接有兩種方式。
筆記本使用 連線窗格,而非其他 Fabric 體驗中可用的「取得資料」模組。 利用其節點尋找連結:
- 目前的筆記本:檢視繫結至目前開啟的筆記本的連線。
- 全域權限:檢視可繫結至筆記本的工作區連線。
選擇 新增連線 ,從筆記本內建立並綁定連線。
在筆記本內建立 Fabric 連接
在筆記本內,你可以在連接面板中選擇新增連接來建立 Fabric Connection。
這會開啟「 新增連線 」窗格,你可以選擇資料來源類型。 提供連線細節並選擇驗證方式。
對於在筆記本內建立的連線,預設會勾選「允許類似筆記本的 Code-First 工件存取此連線(預覽)」的勾選框。 連線建立後,它會自動綁定到目前的筆記本,並會出現在連接面板的「目前筆記本」節點中。
從資料來源管理頁面建立 Fabric 連線
你可以從現有的資料來源管理頁面建立 Fabric 連線。 要執行此操作,請前往資料來源管理頁面,然後選擇新增。 你可以在 資料來源管理頁面找到更多關於如何建立 Fabric 連線的細節,詳見資料來源管理頁面。
建立連線時,請選擇允許 Code-First Artifacts 類筆記本access此連線(預覽)勾選框,讓連線能用於筆記本。 這個設定只能在建立時設定,之後無法更改。
連線建立後,它會出現在筆記本內的 Connections 面板中的全域權限節點中。
在 全域權限 節點下的連線,您需要在連線的內容選單中選擇「連接」,以明確將該連線綁定到目前的筆記本。
當你將連線綁定到目前的筆記本後,它會出現在連接面板的「目前筆記本」節點中。
連線狀態
隨著時間推移,Fabric 連線的狀態可能因各種原因而改變,例如憑證過期或權限變更。 你可以從右鍵選單中選擇 「檢查狀態 」按鈕來查看連線狀態。
如果連線有任何問題,連線名稱旁邊會顯示離線圖示。 以下是可能導致連線中斷的常見情境:
- 憑證過期:若用於連線的憑證已過期,連線即為離線。 你需要更新憑證才能讓連線重新上線。
- 權限變更:如果資料來源的權限改變且導致連線無法再存取,則連線將會離線。 你需要恢復必要的權限才能讓連線重新上線。 例如,如果你使用工作區身份驗證或 SPN,請確保 Fabric 工作區身份或 SPN 擁有訪問資料來源所需的權限。
- 網路問題:如果網路問題阻礙access資料來源,連線就會離線。 你需要解決網路問題才能讓連線重新上線。
- 連線被刪除:如果綁定到筆記本後被刪除,筆電會離線並顯示 無法使用 錯誤。 你無法從離線連線產生程式碼片段。
在「目前筆記本」節點下的離線連線,「檢查狀態」和「斷線」選項可在右鍵選單中使用。 你無法從離線連線產生程式碼片段。 如果 檢查狀態 也被停用,表示連線已被刪除。 你可以重新建立連線並重新綁定到筆記本,或者更新程式碼片段,改用現有的連線。
在 「全域權限」 節點下的離線連線中,右鍵選單中可以使用「檢查狀態」選項。 你無法將離線連線連接到目前的筆記本。 只有當目前使用者擁有該連線的擁有者權限時,「刪除」選項才會可用。
這很重要
如果使用 Workspace 身份驗證來建立連線, 檢查狀態 選項無法驗證連線是線上還是離線,因為測試連線不支援工作區身份驗證。
如何在筆記本程式碼中使用 Fabric Connection
建立 Fabric Connection 並將其綁定到目前筆記本後,你可以產生程式碼片段,直接從筆記本存取資料來源。
程式碼會取得連線的憑證細節,利用這些憑證為資料來源設定客戶端,然後執行查詢取得資料。 你可以根據查詢需求調整產生的摘要。 如果在執行環境中沒有所需的套件,會出現一個包含 pip 安裝指令的上一個程式碼格——在執行查詢前,先執行該程式碼格。
以下是為 Azure Cosmos DB 連線產生的程式碼片段範例:
from azure.cosmos import CosmosClient
import json
import pandas as pd
connection_id = '9d405da3-3d11-481a-9022-xxxxxxxxxxx' # connection name: "neweventdb qixwang"
connection_credential = notebookutils.connections.getCredential(connection_id)
credential_dict = json.loads(connection_credential['credential'])
key = next(item['value'] for item in credential_dict['credentialData'] if item['name'] == 'key')
endpoint = 'https://userevent.documents.azure.com:443/'
client = CosmosClient(endpoint, credential=key)
databases = list(client.list_databases())
database = databases[0]
database_client = client.get_database_client(database['id'])
containers = list(database_client.list_containers())
container = containers[0]
container_name = container['id']
container_client = database_client.get_container_client(container_name)
query = f"SELECT * FROM {container_name} p"
items = list(container_client.query_items(query=query, enable_cross_partition_query=True))
df = pd.DataFrame(items)
display(df)
先用指令執行程式碼 pip install 區塊安裝所需套件,然後再執行程式碼區塊從資料來源取得資料。
連線權限要求
當你執行筆記本時,會進行權限檢查,確保你擁有使用該連線所需的權限。 如果你沒有權限,筆記本會顯示錯誤訊息。
如果你和其他使用者共用筆記本,他們也需要正確的權限才能使用連線並執行程式碼儲存格。 了解更多關於管理 資料來源管理中的連線權限。
如果使用工作區身份驗證或服務主體名稱(SPN)用於連線,請確保 Fabric 的工作區身份或 SPN 擁有存取資料來源所需的權限。
對於 Azure Key Vault 連線,若使用 SPN 或工作空間身份驗證,需遵守以下權限要求:
- SPN 或 Fabric 工作區的身份必須具備 金鑰保存庫 的管理員或協作者角色,才能存取這些秘密。
- SPN 或 Fabric 工作空間身份必須在 金鑰保存庫 上擁有 Azure 資源擁有者/貢獻者角色。
- 更新 金鑰保存庫 中的存取政策,以授予 SPN 或 Fabric 工作空間身份存取機密的權限。
- 在 金鑰保存庫 的存取政策中啟用 “保管庫存取政策”,並授予用於 SPN 或 Fabric 工作區身份的秘密的 “取得” 和 “列出” 權限。
從筆記型電腦連接或斷開 Fabric 連線
要連接或斷開現有筆記本的 Fabric Connection:
- 在 「目前筆記本」 節點中選擇連線。
- 選擇省略號(...),然後從右鍵選單中選擇「斷線」或「連接」。
如果同一條連線斷開再重新連接,連線 ID 會改變。 對於任何已存在的代碼儲存格,只要提到該連線,你就需要把程式碼儲存格裡的連線ID更新成新的連線ID。 在連線的右鍵選單中選擇 「複製 ID」 就可以找到連線 ID。
已知問題與限制
- 筆記本的 Fabric Connect 不支援 OAuth2.0 認證。