共用方式為

語意連結的服務主體支援

Azure 服務主體 （SPN） 是應用程式或自動化工具用來存取特定 Azure 資源的安全性身分識別。 與使用者身分不同，服務主體是非互動式、應用程式型身分，可指派精確的權限，非常適合自動化程序或背景服務。 若要深入瞭解一般服務主體，請參閱 Microsoft Entra ID 中的應用程式和服務主體物件。

Microsoft Fabric 支援兩種常見案例，可搭配服務主體驗證使用語意連結：

  • 服務主體觸發的筆記本執行：使用服務主體來驗證呼叫語意連結的自動化或排程筆記本作業，無需使用者登入即可啟用非互動式執行。
  • 使用服務主體手動驗證語意連結：在互動式或臨機操作工作流程期間叫用語意連結時，提供服務主體認證。

選擇符合您工作流程的案例，然後繼續執行組態步驟。

備註

服務主體支援需要語意連結 0.12.0 版或更新版本。 預設執行時期映像檔可能包含舊版。 使用下列方式更新筆記本環境中的套件：

%pip install -U semantic-link

安裝後，重新啟動核心（或重新執行作業）以獲取更新的套件。 驗證已安裝的版本：

import sempy
print(sempy.__version__)

如果您在管線中或透過作業排程器 API 執行筆記本，請確定執行環境會在作業設定中安裝更新的套件。

服務主體觸發的筆記本執行是指使用服務主體驗證的非互動式筆記本執行。 有兩種情況：

  • Fabric 管線：使用服務主體驗證作為管線的一部分叫用的筆記本。
  • 作業排程器 API：使用服務主體驗證，透過 Fabric 公用 API 觸發的筆記本。

根據預設，服務主體觸發的筆記本執行不需要額外的設定或程式碼變更。 預設權杖服務會自動處理語意連結的基礎驗證。 不過，此預設流程具有 功能限制 ，且僅支援語意連結功能的子集，請參閱 支援的語意連結功能。 若要使用其他功能，建議您使用 服務主體手動驗證語意連結。

使用預設權杖服務的服務主體觸發筆記本執行支援下列語意連結函式：

備註

服務主體驗證會封鎖個人「我的工作區」的存取。 任何以「我的工作區」為目標的呼叫都會失敗，包括此支援清單上的函式。

  • sempy.fabric.FabricRestClient
  • sempy.fabric.create_folder
  • sempy.fabric.create_lakehouse
  • sempy.fabric.create_notebook
  • sempy.fabric.delete_folder
  • sempy.fabric.delete_item
  • sempy.fabric.list_items
  • sempy.fabric.list_folders
  • sempy.fabric.list_datsets(..., mode='rest', endpoint='fabric')
  • sempy.fabric.list_dataflows(..., endpoint='fabric')
  • sempy.fabric.list_reports(..., endpoint='fabric')
  • sempy.fabric.list_workspaces(..., endpoint='fabric')
  • sempy.fabric.move_folder
  • sempy.fabric.rename_folder
  • sempy.fabric.resolve_workspace_id
  • sempy.fabric.resolve_workspace_name
  • sempy.fabric.resolve_workspace_name_and_id
  • sempy.fabric.resolve_dataset_id
  • sempy.fabric.resolve_dataset_name
  • sempy.fabric.resolve_dataset_name_and_id
  • sempy.fabric.resolve_folder_id
  • sempy.fabric.resolve_folder_path
  • sempy.fabric.resolve_item_id
  • sempy.fabric.resolve_item_name
  • sempy.fabric.run_notebook_job
  • sempy.fabric.get_lakehouse_id
  • sempy.fabric.get_workspace_id
  • sempy.fabric.get_artifact_id
  • sempy.fabric.get_notebook_workspace_id

您可以透過兩種方式驗證互動式筆記本執行的服務主體：

  • 使用 sempy set_service_principal 作為前後關聯管理程式。 這是較簡單的選項，程式碼較少，並內建支援純值或金鑰保存庫參考，請參閱 使用語意連結集服務主體 一節。
  • 使用 Azure SDKTokenCredential 來取得更多控制，並與其他 Azure 程式庫互通，請參閱 使用 Azure SDK 權杖認證 一節。

先決條件

  1. 使用 Azure 建立服務主體、指派角色，以及建立秘密。

  2. 請確定具有系統管理員工作區角色的使用者可以透過工作區中的 [管理存取權] 授與 SPN 的存取權。

    管理存取快顯視窗 Fabric 入口網站的螢幕擷取畫面。

您可以使用純值設定服務主體驗證：


import sempy.fabric as fabric
from sempy.fabric import set_service_principal

dataset = "<replace-with-your-dataset-name>"
workspace = "<replace-with-your-workspace-id>"

tenant_id = "<replace-with-your-tenant-id>"
client_id = "<replace-with-your-client-id>"
client_secret = "<replace-with-your-client-secret>"

with set_service_principal(tenant_id, client_id, client_secret=client_secret):
    fabric.run_model_bpa(dataset, workspace=workspace)

如果您不想在筆記本中內嵌秘密，請提供 金鑰保存庫參考 set_service_principal。 set_service_principal 接受秘密或憑證的 （vault_url， secret_name） 形式的元組，並在執行階段解析它們，將認證排除在程式碼和儲存的成品之外。 請確定執行筆記本的服務主體具有秘密和憑證的金鑰保存庫「取得」許可權。

範例：


tenant_kv = ("<replace-with-your-tenant-vault-url>", "<replace-with-your-tenant-secret-name>")
client_kv = ("<replace-with-your-client-vault-url>", "<replace-with-your-client-secret-name>")
client_cert_kv = ("<replace-with-your-client-certification-vault-url>", "<replace-with-your-client-certification-secret-name>")

with set_service_principal(tenant_kv, client_kv, client_certificate=client_cert_kv):
    fabric.run_model_bpa(dataset, workspace=workspace)

使用 Azure SDK 權杖認證

您可以使用 Azure SDK TokenCredential 來與其他 Azure 程式庫進行更多控制和互通性。 建立認證物件，並將它傳遞至 sempy 函式，或在 Fabric Analytics SDK 中將它設定為預設值。

範例：

建立 TokenCredential 並將其傳遞給 sempy 函數：

from azure.identity import ClientSecretCredential

tenant_id = "your-tenant-id"
client_id = "your-client-id"
client_secret = "your-client-secret" 

credential = ClientSecretCredential(tenant_id, client_id, client_secret)

fabric.run_model_bpa(dataset, workspace=workspace, credential=credential)

或將您的 TokenCredential 設定為 Fabric Analytics SDK 的預設驗證：

from fabric.analytics.environment.credentials import SetFabricAnalyticsDefaultTokenCredentials

with SetFabricAnalyticsDefaultTokenCredentials(credential):
    fabric.run_model_bpa(dataset, workspace=workspace)

備註

  • 請勿將秘密認可至原始檔控制。 使用環境變數或金鑰保存庫參考。
  • 請確定服務主體具有必要的角色和工作區存取權。
  • 服務主體驗證仍然無法存取「我的工作區」。

局限性

當您使用服務主體手動驗證語意連結時，請注意下列限制：

  • 個人「我的工作區」的存取權被拒絕。 任何以它為目標的呼叫都會失敗。
  • 服務主體驗證不支援下列函式：
    • sempy.fabric.list_apps
    • sempy.fabric.list_dataflow_storage_accounts
    • sempy.fabric.evaluate_measure
    • sempy.fabric.read_table(..., mode='rest')
    • sempy.fabric.execute_tmsl
  • Last updated on