Narzędzia poświadczeń NotebookUtils dla Fabric

Możesz użyć narzędzi poświadczeń, aby uzyskać tokeny dostępu i zarządzać tajemnicami w usłudze Azure Key Vault. Moduł notebookutils.credentials integruje się z usługą Microsoft Entra ID w celu pozyskiwania tokenów oraz z usługą Azure Key Vault do zarządzania danymi poufnymi, dzięki czemu można bezpiecznie łączyć się z zasobami platformy Azure bez ujawniania poświadczeń w kodzie.

Możesz korzystać z narzędzi do uwierzytelniania w notatnikach Python i Fabric Spark. W notatnikach Fabric Spark można używać PySpark, Scala lub R. Dostępność metod różni się w zależności od czasu uruchomienia notebooka i API. Na przykład działa putSecret tylko w notatnikach Python, które korzystają z środowiska uruchomieniowego Python. Notebooki Spark tego nie obsługują, nawet gdy uruchamiają kod Python z PySparkiem. Notebooki Spark korzystające ze Scali lub R też tego nie obsługują.

Poniższe przykłady wykorzystują Python jako główny język. Pojawiają się odpowiedniki Scala i R, gdzie środowisko uruchomieniowe notebooka i publiczne API obsługują tę metodę.

Ważna

Nigdy nie należy kodować wpisów tajnych ani poświadczeń bezpośrednio w kodzie notesu. Zawsze używaj usługi Azure Key Vault do przechowywania poufnych wartości i pobierania ich w czasie wykonywania za pomocą polecenia notebookutils.credentials.getSecret.

Ograniczenia i bezpieczeństwo

Przed użyciem narzędzi poświadczeń należy pamiętać o następujących ograniczeniach:

Wygaśnięcie tokenu — tokeny wygasają po upływie okresu. W przypadku długotrwałych operacji zaimplementuj logikę odświeżania, aby zażądać nowego tokenu przed wygaśnięciem.
Ograniczenia zakresu jednostki usługi — w przypadku uruchamiania w ramach jednostki usługi tokeny dla pbi odbiorców mają ograniczone zakresy w porównaniu z tożsamością użytkownika.
MSAL dla pełnego zakresu — jeśli potrzebujesz pełnego zakresu usług Fabric w ramach jednostki usługi, użyj uwierzytelniania MSAL zamiast getToken.
Maskowanie wartości tajnej – Dane wyjściowe notesu próbują ukryć oryginalną wartość tajną, gdy kod bezpośrednio ją wypisuje lub wyświetla. To zabezpieczenie oparte na zasadzie najlepszych starań ogranicza ryzyko przypadkowego ujawnienia, również podczas udostępniania ekranu. To nie jest granica bezpieczeństwa. Po pobraniu autoryzowany kod notatnika otrzymuje tekst jawny i może przetwarzać, przekształcać lub ujawniać wpis tajny albo treść pochodzącą z tego wpisu tajnego.
Uprawnienia usługi Key Vault — aby uzyskać dostęp do wpisów tajnych lub przechowywać wpisy tajne, musisz mieć odpowiednie uprawnienia (Pobierz do odczytu, Ustaw do zapisu) w usłudze Azure Key Vault.
Zmiany odbiorców — zakresy odbiorców tokenu mogą ewoluować wraz z upływem czasu. Sprawdź bieżące zakresy w dokumentacji.

Uruchom następujące polecenie, aby uzyskać przegląd dostępnych metod:

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

W poniższej tabeli wymieniono dostępne metody poświadczeń:

Metoda	Signature	Opis
`getToken`	`getToken(audience: String): String`	Zwraca token Entra firmy Microsoft dla określonej grupy odbiorców.
`getSecret`	`getSecret(akvName: String, secret: String): String`	Zwraca wartość wpisu tajnego z określonej usługi Azure Key Vault.
`putSecret`	`putSecret(akvName: String, secretName: String, secretValue: String): String`	Przechowuje sekret w określonej usłudze Azure Key Vault. Ta metoda działa tylko w notatnikach korzystających z runtime Python. Notebooki Spark tego nie obsługują, nawet gdy uruchamiają kod Python z PySparkiem. Notebooki Spark korzystające ze Scali lub R też tego nie obsługują.
`isValidToken`	`isValidToken(token: String): Boolean`	Sprawdza, czy dany token jest prawidłowy i nie wygasł. Ta metoda nie jest dostępna w publicznym interfejsie API języka Scala.

Uzyskiwanie tokenu

getToken Zwraca token Microsoft Entra dla określonej grupy odbiorców. W poniższej tabeli przedstawiono obecnie dostępne klucze odbiorców:

Klucz odbiorców	Resource	Przypadek użycia
`storage`	Azure Storage	Uzyskiwanie dostępu do usługi ADLS Gen2 i usługi Blob Storage
`pbi`	Power BI	Wywoływanie interfejsów API REST usługi Power BI i Fabric
`keyvault`	Azure Key Vault	Pobieranie tajemnic z Key Vault
`kusto`	Synapse RTA KQL DB	Połączenie z usługą Azure Data Explorer

Uruchom następujące polecenie, aby uzyskać token:

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

Przykłady użycia tokenów

Zwrócony token służy do uwierzytelniania w różnych usługach platformy Azure.

Azure Storage

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

Interfejsy API REST usługi Power BI i Fabric

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')

Używanie tokenów z zestawem Azure SDK

Notatniki Fabric nie obsługują DefaultAzureCredential bezpośrednio. Możesz użyć niestandardowej klasy poświadczeń jako obejścia w celu przekazania tokenów NotebookUtils do klientów 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}")

Tip

Tokeny wygasają po upływie czasu. Jeśli notes uruchamia długie operacje, zaimplementuj logikę odświeżania, aby zażądać nowego tokenu przed wygaśnięciem bieżącego.

Zagadnienia do rozważenia

Zakresy tokenów z pbi jako grupą odbiorców mogą się zmieniać z czasem.
Podczas wywoływania notebookutils.credentials.getToken("pbi") zwrócony token ma ograniczony zakres, jeśli notes działa w ramach jednostki usługi. Token nie obejmuje pełnego zakresu usługi Fabric. Jeśli notebook działa z uprawnieniami tożsamości użytkownika, token nadal ma pełny zakres funkcji usługi Fabric, ale może to ulec zmianie dzięki ulepszeniom zabezpieczeń. Aby upewnić się, że token ma pełny zakres usług Fabric, użyj uwierzytelniania MSAL zamiast interfejsu API notebookutils.credentials.getToken. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie za pomocą identyfikatora Entra firmy Microsoft.
Następujące zakresy są dostępne podczas wywoływania notebookutils.credentials.getToken za pomocą klucza pbi odbiorców w ramach tożsamości jednostki usługi:
- Lakehouse.ReadWrite.All – Dostęp do odczytu i zapisu do elementów lakehouse
- MLExperiment.ReadWrite.All – Dostęp do odczytu i zapisu do elementów eksperymentalnych
- MLModel.ReadWrite.All – Dostęp do odczytu i zapisu elementów modelu ML
- Notebook.ReadWrite.All – Dostęp do odczytu i zapisu elementów notesu
- SparkJobDefinition.ReadWrite.All – Dostęp do odczytu i zapisu do elementów definicji stanowisk w Spark
- Workspace.ReadWrite.All – Dostęp do odczytu i zapisu do obszarów roboczych
- Dataset.ReadWrite.All – Dostęp do odczytu i zapisu do elementów modelu semantycznego

Tip

Jeśli potrzebujesz dostępu do dodatkowych usług Fabric lub szerszych uprawnień w ramach zasady usługi, użyj biblioteki MSAL dla języka Python, aby uwierzytelnić się bezpośrednio w pełnym zakresie usługi Fabric, zamiast polegać na getToken("pbi").

Pobierz sekret

getSecret Zwraca tajemnicę usługi Azure Key Vault dla danego Azure Key Vault endpoint i nazwy tajemnicy. Wywołanie używa bieżących poświadczeń użytkownika do uwierzytelniania w usłudze 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")

Możesz pobrać wiele tajnych danych, aby utworzyć ciągi połączeń lub skonfigurować usługi.

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}"

Ważna

Po pomyślnym odzyskaniu autoryzowany kod notatnika otrzymuje wartość tajemnicy jako tekst jawny. Dane wyjściowe notatnika próbują ukryć oryginalną wartość sekretu, gdy kod bezpośrednio ją wypisuje lub wyświetla.

To zabezpieczenie typu best effort ogranicza ryzyko przypadkowego ujawnienia danych wyjściowych notatnika, także podczas udostępniania ekranu. Nie stanowi to granicy bezpieczeństwa i nie uniemożliwia przetwarzania, transformacji ani ujawniania treści pochodzących z sekretów.

Użyj w pełni kwalifikowanego adresu URL usługi Key Vault w formacie https://<vault-name>.vault.azure.net/. Aby uzyskać dostęp do usługi Key Vault i poszczególnych wpisów tajnych, musisz mieć odpowiednie uprawnienia.

Najlepsze rozwiązania dotyczące zabezpieczeń

Postępuj zgodnie z tymi zaleceniami podczas pracy z poświadczeniami w notesach Fabric.

Przechowuj wszystkie poufne wartości w usłudze Azure Key Vault. Nigdy nie osadzaj poświadczeń, parametrów połączenia ani kluczy interfejsu API bezpośrednio w kodzie notesu.
Nie ujawniaj tajnych wartości. Nie drukuj ani nie loguj sekretów, nie zapisuj ich w plikach ani nie przekazuj jako parametrów notatnika. Maskowanie danych wyjściowych ma na celu ochronę oryginalnej wartości w bezpośrednich danych wyjściowych notesu. Nie zapobiega ujawnieniu treści pochodzących z tajnych danych.
Użyj poprawnego klucza odbiorców. Dopasuj klucz odbiorców do docelowego zasobu platformy Azure, aby token miał tylko wymagane uprawnienia.
Omówienie kontekstu tożsamości. Dowiedz się, czy notes działa w ramach tożsamości użytkownika, czy jednostki usługi, ponieważ dostępne zakresy tokenów mogą się różnić. Przetestuj uwierzytelnianie zarówno w kontekstach interakcyjnych, jak i potokowych.
Obsługa wygaśnięcia tokenu. Tokeny wygasają. W przypadku długotrwałych operacji zaimplementuj logikę odświeżania, aby zażądać nowego tokenu przed wygaśnięciem bieżącego.
Ogranicz dostęp do usługi Key Vault. Przyznaj tylko minimalne wymagane uprawnienia do usługi Key Vault. Przeprowadź przegląd dostępu do danych poufnych za pomocą dzienników diagnostycznych usługi Azure Key Vault.
Jeśli to możliwe, użyj tożsamości zarządzanych. Tożsamości zarządzane zmniejszają konieczność ręcznego zarządzania poświadczeniami i zapewniają bardziej bezpieczny przepływ uwierzytelniania.

Umieść wpis tajny

putSecret przechowuje lub aktualizuje sekret w określonej usłudze Azure Key Vault. Działa tylko w notatnikach korzystających z runtime Python.

Ważna

Notebooki Spark nie obsługują putSecret, nawet gdy uruchamiają kod Python z PySparkiem. Notebooki Spark korzystające ze Scali lub R też tego nie obsługują. Użyj notatnika Python, który korzysta z runtime Python.

# Run only in a notebook that uses the Python runtime.
notebookutils.credentials.putSecret(
    'https://<name>.vault.azure.net/',
    'secret name',
    'secret value'
)

Aby zapisać sekrety, potrzebujesz odpowiednich uprawnień (Set permission) na Azure Key Vault. Uruchom poniższy przykład tylko w notatniku korzystającym z runtime Python. Nie uruchamiaj tego w notebooku Fabric Spark.

# Python runtime only. Fabric Spark notebooks don't support putSecret.
vault_url = "https://myvault.vault.azure.net/"

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

Weryfikowanie tokenu

Użyj polecenia isValidToken , aby sprawdzić, czy token jest prawidłowy i nie wygasł przed wywołaniem interfejsu 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 (dawniej MSSparkUtils) dla Fabric

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-23

Narzędzia poświadczeń NotebookUtils dla Fabric

Ograniczenia i bezpieczeństwo

Uzyskiwanie tokenu

Przykłady użycia tokenów

Azure Storage

Interfejsy API REST usługi Power BI i Fabric

Azure Data Explorer (Kusto)

Azure Key Vault

Używanie tokenów z zestawem Azure SDK

Zagadnienia do rozważenia

Pobierz sekret

Najlepsze rozwiązania dotyczące zabezpieczeń

Umieść wpis tajny

Weryfikowanie tokenu

Treści powiązane

Opinia

Dodatkowe zasoby