Fabric 的 NotebookUtils 凭据实用工具

可以使用凭据实用工具获取访问令牌和管理 Azure Key Vault 中的机密。该 notebookutils.credentials 模块与用于获取令牌的 Microsoft Entra ID 集成，以及用于机密管理的 Azure Key Vault，因此可以安全地连接到 Azure 资源，而无需在代码中公开凭据。

凭据实用工具在 Python、PySpark、Scala 和 R 笔记本中可用。本页上的示例使用 Python 作为主要语言，其中显示了公共 API 支持它们的 Scala 和 R 等效项。

重要

切勿直接在笔记本代码中硬编码机密或凭据。始终使用 Azure Key Vault 存储敏感值，并在运行时通过 notebookutils.credentials.getSecret 对其进行检索。

约束和安全

在使用凭据实用工具之前，请注意以下约束：

令牌过期 – 令牌在一段时间后过期。对于长时间运行的操作，请实现刷新逻辑，以在过期前请求新令牌。
服务主体范围限制 – 在服务主体下运行时，针对pbi受众的令牌与用户标识相比具有受限的范围。
MSAL 用于完整范围 – 如果需要服务主体下的完整 Fabric 服务范围，请使用 MSAL 身份验证，而不是 getToken。
机密修订 – 笔记本输出会自动对机密值进行修订，以防止意外泄露。
Key Vault 权限 - 必须在 Azure Key Vault 上具有适当的权限（用于读取、设置写入）才能访问或存储机密。
访问群体更改 - 令牌访问群体范围可能会随时间推移而演变。验证文档中的当前范围。

运行以下命令以概要了解可用的方法：

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

下表列出了可用的凭据方法：

方法	Signature	说明
`getToken`	`getToken(audience: String): String`	返回指定受众的 Microsoft Entra 标记。
`getSecret`	`getSecret(akvName: String, secret: String): String`	从指定的 Azure Key Vault 返回密钥的值。
`putSecret`	`putSecret(akvName: String, secretName: String, secretValue: String): String`	将机密存储在指定的 Azure Key Vault 中。此方法在公共 Scala API 中不可用。
`isValidToken`	`isValidToken(token: String): Boolean`	检查给定令牌是否有效且未过期。此方法在公共 Scala API 中不可用。

获取令牌

getToken 为给定受众返回Microsoft Entra 令牌。下表显示了当前可用的受众密钥：

受众密钥	资源	用例
`storage`	Azure 存储	访问 ADLS Gen2 和 Blob 存储
`pbi`	Power BI	调用 Power BI 和 Fabric REST API
`keyvault`	Azure Key Vault	检索 Key Vault 密钥
`kusto`	Synapse RTA KQL 数据库	连接到 Azure 数据资源管理器

运行以下命令以获取这些令牌：

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

代币使用示例

可以使用返回的令牌对各种 Azure 服务进行身份验证。

Azure 存储

storage_token = notebookutils.credentials.getToken('storage')

Power BI 和 Fabric REST API

import requests

pbi_token = notebookutils.credentials.getToken('pbi')

headers = {
    'Authorization': f'Bearer {pbi_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.powerbi.com/v1.0/myorg/datasets',
    headers=headers
)

if response.status_code == 200:
    datasets = response.json()
    print(f"Found {len(datasets['value'])} datasets")

Azure Data Explorer （Kusto）

kusto_token = notebookutils.credentials.getToken('kusto')

Azure Key Vault

keyvault_token = notebookutils.credentials.getToken('keyvault')

将令牌与 Azure SDK 配合使用

Fabric 笔记本不直接支持 DefaultAzureCredential。可以使用自定义凭据类作为一种解决方法，将 NotebookUtils 令牌传递给 Azure SDK 客户端。

from azure.core.credentials import AccessToken, TokenCredential
import jwt

class NotebookUtilsCredential(TokenCredential):
    """Custom credential that uses notebookutils tokens for Azure SDK."""

    def __init__(self, audience="storage"):
        self.audience = audience

    def get_token(self, *scopes, claims=None, tenant_id=None, **kwargs):
        token = notebookutils.credentials.getToken(self.audience)

        # Decode token to get expiration time
        token_json = jwt.decode(
            token, algorithms="RS256",
            options={"verify_signature": False}
        )

        return AccessToken(token, int(token_json.get("exp", 0)))

# Example: use with Azure Blob Storage
from azure.storage.blob import BlobServiceClient

account_url = "https://mystorageaccount.blob.core.windows.net"
credential = NotebookUtilsCredential(audience="storage")
blob_client = BlobServiceClient(account_url=account_url, credential=credential)

for container in blob_client.list_containers():
    print(f"Container: {container.name}")

小窍门

令牌在一段时间后过期。如果笔记本运行长时间的操作，请实现刷新逻辑，以便在当前令牌过期之前请求新令牌。

注意事项

受众为 pbi 的令牌范围可能会随着时间而改变。
调用 notebookutils.credentials.getToken("pbi")时，如果笔记本在服务主体下运行，则返回的令牌的范围有限。令牌未完全涵盖 Fabric 服务范围。如果笔记本在用户标识下运行，令牌仍具有完整的 Fabric 服务范围，但这可能会随着安全改进而更改。若要确保令牌具有完整的 Fabric 服务范围，请使用 MSAL 身份验证而不是 notebookutils.credentials.getToken API。有关详细信息，请参阅使用 Microsoft Entra ID 进行身份验证。
在服务主体标识下使用受众密钥notebookutils.credentials.getToken进行调用pbi时，可以使用以下范围：
- Lakehouse.ReadWrite.All – 对 Lakehouse 项目的读写访问权限
- MLExperiment.ReadWrite.All – 对机器学习试验项的读取和写入访问权限
- MLModel.ReadWrite.All – 对机器学习模型项的读取和写入访问权限
- Notebook.ReadWrite.All – 对笔记本项的读取和写入访问权限
- SparkJobDefinition.ReadWrite.All – 对 Spark 作业定义项的读取和写入访问权限
- Workspace.ReadWrite.All – 对工作区项的读取和写入访问权限
- Dataset.ReadWrite.All – 对数据集项的读取和写入访问权限

小窍门

如果需要访问其他 Fabric 服务或服务主体下更广泛的权限，请使用 MSAL for Python 直接使用完整的 Fabric 服务范围进行身份验证，而不是依赖 getToken("pbi")。

获取机密

getSecret 返回 Azure Key Vault 中给定终结点和机密名称的机密。该调用使用当前用户凭据对 Key Vault 进行身份验证。

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

notebookutils.credentials.getSecret("https://<name>.vault.azure.net/", "secret name")

notebookutils.credentials.getSecret("https://<name>.vault.azure.net/", "secret name")

可以检索多个机密来生成连接字符串或配置服务：

vault_url = "https://myvault.vault.azure.net/"

db_host = notebookutils.credentials.getSecret(vault_url, "db-host")
db_user = notebookutils.credentials.getSecret(vault_url, "db-user")
db_password = notebookutils.credentials.getSecret(vault_url, "db-password")

connection_string = f"Server={db_host};User={db_user};Password={db_password}"

注释

笔记本输出会自动对机密值进行修订，以便安全。如果打印或显示检索到的机密，输出将显示经过修订的占位符，而不是实际值。

使用格式 https://<vault-name>.vault.azure.net/的完全限定的 Key Vault URL。必须具有访问 Key Vault 和单个机密的适当权限。

安全最佳做法

在处理 Fabric 笔记本中的凭据时，请遵循以下建议：

将所有敏感值存储在 Azure Key Vault 中。 切勿直接在笔记本代码中嵌入凭据、连接字符串或 API 密钥。
不要记录机密值。 依赖笔记本输出中的自动机密编辑。避免将机密写入文件或将其作为笔记本参数传递。
使用正确的受众密钥。 将受众密钥与目标 Azure 资源匹配，以便令牌仅具有所需的权限。
了解身份上下文。 了解笔记本是在用户标识或服务主体下运行的，因为可用的令牌范围可能有所不同。在交互式上下文和管道上下文中测试身份验证。
处理令牌过期。 令牌过期。对于长时间运行的操作，请实现刷新逻辑，以便在当前令牌过期之前请求新令牌。
限制 Key Vault 访问。 仅向 Key Vault 授予所需的最低权限。通过 Azure Key Vault 诊断日志审核机密访问。
尽可能使用托管标识。 托管标识减少了手动管理凭据的需求，并提供更安全的身份验证流。

存放机密

putSecret 将机密存储在指定的 Azure Key Vault 中。如果机密已存在，则会更新该值。

notebookutils.credentials.putSecret('https://<name>.vault.azure.net/', 'secret name', 'secret value')

notebookutils.credentials.putSecret("https://<name>.vault.azure.net/", "secret name", "secret value")

必须对 Azure Key Vault 具有适当的权限（设置权限），才能写入机密。

vault_url = "https://myvault.vault.azure.net/"

notebookutils.credentials.putSecret(vault_url, "api-key", "my-secret-api-key-value")

验证令牌

使用 isValidToken 在调用 API 之前检查令牌是否有效且未过期。

token = notebookutils.credentials.getToken('storage')
is_valid = notebookutils.credentials.isValidToken(token)

if is_valid:
    print("Token is valid")
else:
    print("Token is expired or invalid, requesting a new one")
    token = notebookutils.credentials.getToken('storage')

token <- notebookutils.credentials.getToken("storage")
is_valid <- notebookutils.credentials.isValidToken(token)

if (is_valid) print("Token is valid") else print("Token is expired or invalid")

NotebookUtils （前 MSSparkUtils） for Fabric

反馈

此页面是否有帮助？

Last updated on 2026-04-02