NotebookUtils file mount and unmount for Fabric

NotebookUtils tukee tiedostojen liittämistä ja irrottamista Microsoft Spark Utilities -paketin kautta. Voit käyttää mount, unmount, getMountPath(), ja mounts() rajapintoja yhdistääksesi etätallennusta (ADLS Gen2, Azure Blob Storage, OneLake) kaikkiin toimiviin solmuihin (ajuri- ja työntekijäsolmut). Kun tallennustilan käyttöönottopiste on paikallaan, käytä paikallista tiedoston ohjelmointirajapintaa tietojen käyttämiseen ikään kuin ne olisi tallennettu paikalliseen tiedostojärjestelmään.

Mount-operaatiot ovat erityisen hyödyllisiä, kun:

• Työskentele kirjastojen kanssa, jotka odottavat paikallisia tiedostopolkuja.
• Tarvitsen yhtenäiset tiedostojärjestelmän semantiikan pilvitallennuksen yli.
• Käytä OneLake-pikanäppäimiä (S3/GCS) tehokkaasti.
• Rakenna kannettavaa koodia, joka toimii useiden tallennustaustajärjestelmien kanssa.

Ohjelmointirajapinnan viittaus

Seuraava taulukko tiivistää saatavilla olevat mount-rajapinnat:

Menetelmä	Allekirjoitus	Description
mount	mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Kiinnittää etätallennuksen määritettyyn kiinnityspisteeseen.
unmount	unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Irrottaa ja poistaa kiinnityspisteen.
mounts	mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]	Listaa kaikki olemassa olevat kiinnityspisteet yksityiskohtineen.
getMountPath	getMountPath(mountPoint: String, scope: String = ""): String	Saa paikallisen tiedostojärjestelmän polun kiinnityspisteelle.

Todennusmenetelmät

Mount-toiminnot tukevat useita tunnistautumismenetelmiä. Valitse menetelmä tallennustyyppisi ja turvallisuusvaatimusten perusteella.

Microsoft Entra -token (oletus ja suositeltu)

Microsoft Entra -token-tunnistautuminen käyttää muistikirjan suorittajan identiteettiä, joko käyttäjä- tai palvelupäähenkilöä. Se ei vaadi nimenomaisia tunnuksia mount-kutsussa, mikä tekee siitä turvallisimman vaihtoehdon. Käytä tätä vaihtoehtoa Lakehouse-asennukseen ja kankaan työtilan säilytykseen.

# Mount using Microsoft Entra token (no credentials needed)
notebookutils.fs.mount(
    "abfss://mycontainer@mystorageaccount.dfs.core.windows.net",
    "/mydata"
)

Vinkki

Käytä Microsoft Entra -token-tunnistautumista aina kun mahdollista. Se poistaa tunnistetunnisteiden altistumisen riskin eikä vaadi lisäasetuksia Fabric-työtilan tallennukseen.

Tiliavain

Käytä tilin avainta, kun tallennustili ei tue Microsoft Entra -tunnistautumista tai kun käytät ulkoista tai kolmannen osapuolen tallennusta. Tallenna tiliavaimet Azure Key Vaultiin ja hae ne API notebookutils.credentials.getSecret :n avulla.

# Retrieve account key from Azure Key Vault
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"accountKey": accountKey}
)

Jaetun pääsyn allekirjoitustunnus (SAS)

Käytä jaetun pääsyn allekirjoitusta (SAS) aikarajoitettuun ja käyttöoikeuslaajuuteen perustuvaan käyttöön. Tämä vaihtoehto on hyödyllinen, kun sinun täytyy myöntää väliaikainen pääsy ulkopuolisille osapuolille. Tallenna SAS-tokenit Azure Key Vaultiin.

# Retrieve SAS token from Azure Key Vault
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"sasToken": sasToken}
)

Tärkeää

Turvallisuussyistä vältä tietojen upottamista suoraan koodiin. Kaikki muistikirjan tulosteissa näkyvät salaisuudet poistetaan automaattisesti. Lisätietoja on kohdassa Salainen hävitys.

Liitä ADLS Gen2 -tili

Seuraavassa esimerkissä havainnollistetaan, miten Azure Data Lake Storage Gen2 voidaan ottaa käyttöön. Blob Storagen ja Azure File Share:n asentaminen toimii samalla tavalla.

Tässä esimerkissä oletetaan, että sinulla on yksi Data Lake Storage Gen2 -tili nimeltä storegen2, jossa on mycontainer-niminen säilö, jonka haluat liittää /test-tiedostoon muistikirjan Spark-istunnossa.

Mycontainer-nimisen kontin liittämiseksi NotebookUtilsin täytyy ensin tarkistaa, onko sinulla oikeus käyttää konttia. Tällä hetkellä Fabric tukee kolmea todennusmenetelmää trigger-kiinnitystoiminnolle: Microsoft Entra -token (oletus), accountKey ja sasToken.

Turvallisuussyistä tallenna tiliavaimet tai SAS-tokenit Azure Key Vaultiin (kuten seuraava kuvakaappaus osoittaa). Voit sitten hakea ne API:n avulla notebookutils.credentials.getSecret . Lisätietoja Azure Key Vaultista on artikkelissa Tietoja Azure Key Vaultin hallitun tallennustilin avaimista.

Esimerkkikoodi accountKey-menetelmälle :

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Esimerkkikoodi sasTokenille:

# get access token for keyvault resource
# You can also use the full audience, such as https://vault.azure.net.
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Kiinnitysparametrit

Voit säätää mount-käyttäytymistä extraConfigs seuraavilla valinnaisilla parametreilla kartassa:

• fileCacheTimeout: Möykkyt välimuistitetaan oletuksena paikalliseen väliaikaiseen kansioon 120 sekunniksi. Tänä aikana blobfuse ei tarkista, onko tiedosto ajan tasalla. Voit asettaa tämän parametrin muuttamaan oletusaikakatkaisuaikaa. Kun useat asiakkaat muokkaavat tiedostoja samanaikaisesti, paikallisten ja etätiedostojen välisten ristiriitojen välttämiseksi lyhennä välimuistiaikaa tai aseta se nollaan, jotta palvelimelta saadaan aina uusimmat tiedostot.
• aikakatkaisu: Kiinnitystoiminnon aikakatkaisu on oletuksena 30 sekuntia. Voit asettaa tämän parametrin muuttamaan oletusaikakatkaisuaikaa. Kun toimeenpanijoita on liikaa tai kun mount-aika päättyy, nosta arvoa.

Voit käyttää näitä parametreja seuraavasti:

notebookutils.fs.mount(
   "abfss://mycontainer@<accountname>.dfs.core.windows.net",
   "/test",
   {"fileCacheTimeout": 120, "timeout": 30}
)

Välimuistin konfigurointisuositukset

Valitse välimuistin aikakatkaisuarvo käyttökuviosi perusteella:

Esimerkkitilanne	Suositeltu fileCacheTimeout	Huomautuksia
Lukupainotteinen, yksittäinen asiakas	120 (oletus)	Hyvä tasapaino suorituskyvyn ja raikkauden välillä.
Kohtuullinen moniasiakasyhteys	30–60	Vähentää vanhentuneen datan riskiä.
Useat asiakkaat muokkaamassa tiedostoja	0	Hae aina uusimmat tiedot palvelimelta.
Tiedostot muuttuvat harvoin	300+	Optimoi lukusuorituskyvyn.

Nollavälimuistikuvio

Kun useat asiakkaat muokkaavat tiedostoja samanaikaisesti, käytä nollavälimuistikonfiguraatiota ja hae aina uusin versio palvelimelta:

# For scenarios with multiple clients modifying files
# Use zero cache to always fetch the latest from the server
notebookutils.fs.mount(
    "abfss://shared@account.dfs.core.windows.net",
    "/shared_data",
    {"fileCacheTimeout": 0}
)

Muistio

Lisää timeout parametria, kun asennat useilla suorittajilla tai kun kohtaat aikakatkaisuvirheitä.

Mount a Lakehouse

Lakehouse-asennus tukee vain Microsoft Entra -token-tunnistautumista. Esimerkkikoodi Lakehousen kiinnittämiseen /<mount_name>:een:

notebookutils.fs.mount( 
 "abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse", 
 "/<mount_name>"
)

Tiedostoihin pääsy mount-pisteen alla notebookutils fs API:n avulla

Käytä mount-toimintoja, kun haluat päästä käsiksi etätallennusdataan paikallisen tiedostojärjestelmän API:n kautta. Voit myös käyttää liitettyä dataa API notebookutils.fs :n avulla, jossa on liitetty polku, mutta polkumuoto eroaa.

Oletetaan, että olet asentanut Data Lake Storage Gen2 -säilön mycontainerkohteeseen /test käyttämällä asennusohjelmointirajapintaa. Kun käytät paikallisen tiedostojärjestelmän ohjelmointirajapinnan tietoja, polkumuoto on seuraavanlainen:

/synfs/notebook/{sessionId}/test/{filename}

Kun haluat päästä dataan notebookutils fs API:n kautta, käytä getMountPath() sitä saadaksesi tarkan reitin:

path = notebookutils.fs.getMountPath("/test")

• Listaa hakemistot.

  notebookutils.fs.ls(f"file://{notebookutils.fs.getMountPath('/test')}")
  

• Lue tiedoston sisältö.

  notebookutils.fs.head(f"file://{notebookutils.fs.getMountPath('/test')}/myFile.txt")
  

• Luo hakemisto.

  notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")
  

Käyttötiedostot käyttöönottopisteen alla paikallisen polun kautta

Voit lukea ja kirjoittaa tiedostoja kiinnityspisteessä käyttämällä tavallista tiedostojärjestelmää. Seuraava Python-esimerkki osoittaa tämän kaavan:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Tarkista olemassa olevat kiinnityspisteet

Käytä notebookutils.fs.mounts() API:a tarkistaaksesi kaikki olemassa olevat kiinnityspisteen tiedot:

notebookutils.fs.mounts()

Vinkki

Tarkista aina olemassa olevat mounts() ratsut ennen uusien kiinnityspisteiden luomista konfliktien välttämiseksi.

Tarkista, onko kiinnike olemassa ennen asennusta

existing_mounts = notebookutils.fs.mounts()
mount_point = "/mydata"

if any(m.mountPoint == mount_point for m in existing_mounts):
    print(f"Mount point {mount_point} already exists")
else:
    notebookutils.fs.mount(
        "abfss://container@account.dfs.core.windows.net",
        mount_point
    )
    print("Mount created successfully")

Irrota kiinnityspiste

Käytä seuraavaa koodia irrottaaksesi kiinnityspisteesi (/test tässä esimerkissä):

notebookutils.fs.unmount("/test")

Tärkeää

Irrotusmekanismi ei ole automaattisesti käytössä. Kun sovelluksen suorittaminen on valmis, jotta voit poistaa kiinnityskohdan ja vapauttaa levytilan, sinun on eksplisiittisesti kutsuttava koodin määrittämätöntä ohjelmointirajapintaa. Muussa tapauksessa kiinnityspiste on edelleen olemassa solmussa sovelluksen suorituksen jälkeen.

Mount-process-unmount -työnkulku

Luotettavan resurssien hallinnan takaamiseksi kääreä asennusoperaatiot try/finally lohkoon, jotta puhdistus tapahtuu, vaikka virhe tapahtuisi:

def process_with_mount(source_uri, mount_point):
    """Complete workflow: mount, process, unmount."""
    
    try:
        # Step 1: Check if already mounted
        existing = notebookutils.fs.mounts()
        if any(m.mountPoint == mount_point for m in existing):
            print(f"Already mounted at {mount_point}")
        else:
            notebookutils.fs.mount(source_uri, mount_point)
            print(f"Mounted {source_uri} at {mount_point}")
        
        # Step 2: Process data using local file system
        mount_path = notebookutils.fs.getMountPath(mount_point)
        
        with open(f"{mount_path}/data/input.txt", "r") as f:
            data = f.read()
        
        processed = data.upper()
        
        with open(f"{mount_path}/output/result.txt", "w") as f:
            f.write(processed)
        
        print("Processing complete")
        
    finally:
        # Step 3: Always unmount to release resources
        notebookutils.fs.unmount(mount_point)
        print(f"Unmounted {mount_point}")

process_with_mount(
    "abfss://mycontainer@mystorage.dfs.core.windows.net",
    "/temp_mount"
)

Tunnetut rajoitukset

• Mountit ovat työtasoisia kokoonpanoja. Käytä API: mounts a tarkistaaksesi, onko mount-piste jo olemassa tai saatavilla.
• Irrotus ei tapahdu automaattisesti. Kun sovelluksen suoritus päättyy, kutsu koodissasi irrotusrajapinta vapauttaaksesi levytilaa. Muussa tapauksessa kiinnityspiste pysyy solmussa sovellussuorituksen päätyttyä.
• ADLS Gen1 -tallennustilin asentamista ei tueta.

Liittyvä sisältö

• NotebookUtils for Fabric
• NotebookUtils tiedostojärjestelmän apuohjelmat