NotebookUtils credentials utilities for Fabric

Voit käyttää tunnistetietotyökaluja saadaksesi käyttöoikeustokeneita ja hallitaksesi salaisuuksia Azure Key Vaultissa. Moduuli notebookutils.credentials integroituu Microsoft Entra ID:hen tokenien hankintaan ja Azure Key Vaultiin salaisuuksien hallintaan, joten voit yhdistää Azure-resursseihin turvallisesti ilman, että tunnistetietoja tarvitsee paljastaa koodissa.

Voit käyttää Python-muistikirjojen ja Fabric Spark -muistikirjojen tunnistustyökaluja. Fabric Spark -muistikirjoissa voit käyttää PySpintia, Scalaa tai R:ää. Metodien saatavuus vaihtelee muistikirjan ajonajan ja API:n mukaan. Esimerkiksi toimii putSecret vain Python-muistikirjoissa, jotka käyttävät Python-ajonaikaa. Spark-muistikirjat eivät tue sitä, vaikka ne ajaisivat Python-koodia PySparkilla. Spark-kannettavat, jotka käyttävät Scalaa tai R:ää, eivät myöskään tue sitä.

Seuraavissa esimerkeissä Python on pääkieli. Scala- ja R-vastineet ilmestyvät siellä, missä notebookin ajonaikainen ja julkinen API tukevat metodia.

Tärkeää

Älä koskaan koodaa salaisuuksia tai tunnuksia suoraan muistikirjan koodiin. Käytä aina Azure Key Vaultia tallentaaksesi arkaluontoiset arvot ja hakeaksesi ne ajonaikaisesti .notebookutils.credentials.getSecret

Rajoitukset ja turvallisuus

Ennen kuin käytät tunnistetietotyökaluja, ole tietoinen näistä rajoituksista:

Tokenien vanheneminen – Tokenit vanhenevat tietyn ajan kuluttua. Pitkäaikaisissa operaatioissa toteuta virkistyslogiikka pyytääksesi uutta tokenia ennen vanhenemista.
Palvelupään laajuuden rajoitukset – Kun niitä ajetaan palveluperiaatteen alla, yleisön pbi tokeneilla on rajattu laajuus verrattuna käyttäjäidentiteettiin.
MSAL koko laajuudelle – Jos tarvitset koko Fabric-palvelun laajuuden palvelupään alla, käytä MSAL-tunnistautumista sen sijaan, että käyttäisit getToken.
Salainen sensurointi – Muistikirjan tulostus yrittää sensuroida alkuperäisen salaisen arvon, kun koodi tulostaa tai näyttää sen suoraan. Tämä paras keino vähentää vahingossa tapahtuvaa paljastusta, myös ruudunjakamisen yhteydessä. Se ei ole turvallisuusraja. Haun jälkeen valtuutetun muistikirjan koodi vastaanottaa selkotekstiä ja voi käsitellä, muuntaa tai paljastaa salaisesta tai salaisesta sisällöstä.
Key Vaultin käyttöoikeudet – Sinulla täytyy olla asianmukaiset oikeudet (Get lukemiseen, Set kirjoittamiseen) Azure Key Vaultissa, jotta voit käyttää tai tallentaa salaisuuksia.
Yleisön muutokset – Token-yleisön laajuudet voivat kehittyä ajan myötä. Tarkista nykyiset scope-alueet dokumentaatiosta.

Saat yleiskatsauksen käytettävissä olevista menetelmistä suorittamalla seuraavan komennon:

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

Seuraavassa taulukossa on lueteltu saatavilla olevat tunnistekoodimenetelmät:

Menetelmä	Allekirjoitus	Description
`getToken`	`getToken(audience: String): String`	Palauttaa Microsoft Entra -tokenin määritetylle yleisölle.
`getSecret`	`getSecret(akvName: String, secret: String): String`	Palauttaa salaisuuden arvon määritetystä Azure Key Vaultista.
`putSecret`	`putSecret(akvName: String, secretName: String, secretValue: String): String`	Tallentaa salaisuuden määritettyyn Azure Key Vaultiin. Tämä menetelmä toimii vain muistikirjoissa, jotka käyttävät Python-ajonaikaa. Spark-muistikirjat eivät tue sitä, vaikka ne ajaisivat Python-koodia PySparkilla. Spark-muistikirjat, joissa käytetään Scalaa tai R:ää, eivät myöskään tue sitä.
`isValidToken`	`isValidToken(token: String): Boolean`	Tarkistaa, onko annettu token voimassa eikä vanhentunut. Tätä menetelmää ei ole saatavilla julkisessa Scala API:ssa.

Hanki tunnus

getToken palauttaa Microsoft Entra -tokenin tietylle yleisölle. Seuraava taulukko näyttää tällä hetkellä saatavilla olevat yleisön avaimet:

Yleisön avain	Resurssi	Käyttötapaus
`storage`	Azure-tallennus	Pääsy ADLS Gen2:een ja Blob Storageen
`pbi`	Power BI	Kutsu Power BI- ja Fabric REST -rajapintoja
`keyvault`	Azure Key Vault	Hae avainholvin salaisuudet
`kusto`	Synapse RTA KQL DB	Yhdistä Azure Data Explorer

Saat tunnuksen suorittamalla seuraavan komennon:

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

Tokenin käytön esimerkkejä

Voit käyttää palautettua tokenia tunnistautuaksesi eri Azure-palveluihin.

Azure-tallennus

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

Power BI- ja Fabric REST -rajapinnat

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

Käytä tokeneita Azure SDK:n kanssa

Fabric-muistikirjat eivät tue DefaultAzureCredential tätä suoraan. Voit käyttää mukautettua tunnisteluokkaa kiertotienä NotebookUtils-tokenien välittämiseen Azure SDK -asiakkaille.

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

Vinkki

Tokenit vanhenevat tietyn ajan kuluttua. Jos muistikirjasi suorittaa pitkiä operaatioita, toteuta päivityslogiikka pyytääksesi uutta tokenia ennen kuin nykyinen vanhenee.

Huomioitavia seikkoja

Token-tähtäimet, joiden pbi kohderyhmä voi muuttua ajan myötä.
Kun kutsut notebookutils.credentials.getToken("pbi"), palautetulla tokenilla on rajallinen ulottuvuus, jos notebook toimii palvelupään alla. Tokenilla ei ole koko Fabric-palvelun laajuutta. Jos muistikirja toimii käyttäjätunnuksella, tokenilla on edelleen koko Fabric-palvelun laajuus, mutta tämä voi muuttua tietoturvaparannusten myötä. Varmistaaksesi, että tokenilla on koko Fabric-palvelun laajuus, käytä MSAL-tunnistautumista API:n sijaan notebookutils.credentials.getToken . Lisätietoja on artikkelissa Todentaminen Microsoft Entra ID:llä.
Seuraavat scopet ovat käytettävissä, kun kutsut notebookutils.credentials.getToken audience-avaimella pbi palvelun päähenkilötunnuksen alla:
- Lakehouse.ReadWrite.All – Lue ja kirjoita pääsy järvenrakennuksen esineisiin
- MLExperiment.ReadWrite.All – Lue ja kirjoita pääsy kokeelliseen kohteeseen
- MLModel.ReadWrite.All – Luku- ja kirjoitusoikeudet koneoppimismallin kohteisiin
- Notebook.ReadWrite.All – Lue ja kirjoita pääsy muistikirjan esineisiin
- SparkJobDefinition.ReadWrite.All – Lue ja kirjoita pääsy Spark-tehtävien määrittelykohteisiin
- Workspace.ReadWrite.All – Luku- ja kirjoitusoikeudet työtiloihin
- Dataset.ReadWrite.All – Luku- ja kirjoitusoikeudet semanttisiin mallin kohteisiin

Vinkki

Jos tarvitset pääsyn lisäFabric-palveluihin tai laajempiin käyttöoikeuksiin palvelupään kautta, käytä MSAL for Pythonia todentaaksesi suoraan koko Fabric-palvelun laajuudella sen sijaan, että luottaisit .getToken("pbi")

Hanki salaisuus

getSecret palauttaa Azure Key Vaultin salaisuuden annetulle Azure Key Vaultin päätepisteelle ja salaiselle nimelle. Puhelu käyttää nykyisiä käyttäjätunnuksiasi todennukseen Key Vaultia vastaan.

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

Voit hakea useita salaisuuksia rakentaaksesi yhteysmerkkijonoja tai konfiguroidaksesi palveluita:

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

Tärkeää

Onnistuneen haun jälkeen valtuutetun muistikirjan koodi saa salaisen arvon selväkielisenä. Notebookin tulostus yrittää sensuroida alkuperäisen salaisen arvon, kun koodi tulostaa tai näyttää sen suoraan.

Tämä paras keino vähentää vahingossa tapahtuvaa paljastumista kannettavan ulostuloksissa, myös näytön jakamisen yhteydessä. Se ei ole turvallisuusraja eikä estä salaisuuteen perustuvan sisällön käsittelyä, muuntamista tai paljastamista.

Käytä täysin pätevää Key Vault -URL-osoitetta muodossa https://<vault-name>.vault.azure.net/. Sinulla on oltava asianmukaiset oikeudet päästäksesi avainholviin ja yksittäisiin salaisuuksiin.

Tietoturvan parhaat käytännöt

Noudata näitä suosituksia, kun työskentelet Fabric-muistikirjojen kanssa:

Tallenna kaikki arkaluontoiset arvot Azure Key Vaultiin. Älä koskaan upota tunnuksia, yhteysmerkkijonoja tai API-avaimia suoraan muistikirjan koodiin.
Älä paljasta salaisia arvoja. Älä tulosta tai kirjaa salaisuuksia, kirjoita niitä tiedostoihin tai välitä niitä muistikirjan parametreina. Tulostuksen sensurointi pyrkii suojaamaan alkuperäistä arvoa suorassa muistikirjan tulosteessa. Se ei estä salaperäisen sisällön paljastamista.
Käytä oikeaa yleisöavainta. Yhdistä yleisöavain kohde-Azure-resurssiin, jotta tokenilla on vain tarvitsemansa oikeudet.
Ymmärrä identiteettikonteksti. Tiedä, toimiiko muistikirjasi käyttäjätunnuksella vai palvelupäähenkilöllä, sillä käytettävissä olevat token-laajuudet voivat vaihdella. Testaa todennus sekä interaktiivisissa että putkikonteksteissa.
Hoida tokenien vanheneminen. Tokenit vanhenevat. Pitkäaikaisissa operaatioissa toteuta virkistyslogiikka pyytääksesi uutta tunnistetta ennen kuin nykyinen vanhenee.
Rajoita pääsyä Key Vaultiin. Myönnä vain vähimmäisvaaditut oikeudet Key Vaultillesi. Auditoi salainen pääsy Azure Key Vaultin diagnostiikkalokien kautta.
Käytä hallittuja identiteettejä aina kun mahdollista. Hallitut identiteetit vähentävät tarvetta hallita tunnistetietoja manuaalisesti ja tarjoavat turvallisemman tunnistautumisprosessin.

Laita salaisuus

putSecrettallentaa tai päivittää salaisuuden määritellyssä Azure Key Vault. Se toimii vain muistikirjoissa, jotka käyttävät Python-ajonaikaa.

Tärkeää

Spark-muistikirjat eivät tue putSecret, vaikka ne ajaisivat Python-koodia PySparkilla. Spark-muistikirjat, joissa käytetään Scalaa tai R:ää, eivät myöskään tue sitä. Käytä Python-muistikirjaa, joka käyttää Python-ajonaikaa.

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

Salaisuuksien kirjoittamiseen tarvitset asianmukaiset oikeudet (Set permission) Azure Key Vault:ssa. Suorita seuraava esimerkki vain muistikirjassa, joka käyttää Python-ajonaikaa. Älä aja sitä Fabric Spark -muistikirjassa.

# 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")

Validoi token

Käytä isValidToken sitä tarkistamaan, onko token voimassa eikä vanhentunut ennen kuin kutsut API:n sillä.

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 (entinen MSSparkUtils) Fabricille

Palaute

Onko tästä sivusta apua?

Last updated on 2026-09-23

NotebookUtils credentials utilities for Fabric

Rajoitukset ja turvallisuus

Hanki tunnus

Tokenin käytön esimerkkejä

Azure-tallennus

Power BI- ja Fabric REST -rajapinnat

Azure Data Explorer (Kusto)

Azure Key Vault

Käytä tokeneita Azure SDK:n kanssa

Huomioitavia seikkoja

Hanki salaisuus

Tietoturvan parhaat käytännöt

Laita salaisuus

Validoi token

Liittyvä sisältö

Palaute

Lisäresursseja