NotebookUtils (dawniej MSSparkUtils) dla sieci szkieletowej

Notes Utilities (NotebookUtils) to wbudowany pakiet ułatwiający wykonywanie typowych zadań w notesie sieci szkieletowej. Narzędzia NotebookUtils umożliwiają pracę z systemami plików, uzyskiwanie zmiennych środowiskowych, łączenie notesów i pracę z wpisami tajnymi. Pakiet NotebookUtils jest dostępny w potokach PySpark (Python) Scala, SparkR notebooks i Fabric.

Uwaga

• Nazwa narzędzia MsSparkUtils została oficjalnie zmieniona na NotebookUtils. Istniejący kod pozostanie zgodny z poprzednimi wersjami i nie spowoduje żadnych zmian powodujących niezgodność. Zdecydowanie zaleca się uaktualnienie do narzędzia notebookutils, aby zapewnić ciągłą obsługę i dostęp do nowych funkcji. Przestrzeń nazw mssparkutils zostanie wycofana w przyszłości.
• Narzędzia NotebookUtils są przeznaczone do pracy z platformą Spark 3.4 (środowisko uruchomieniowe w wersji 1.2) lub nowszej. Wszystkie nowe funkcje i aktualizacje będą obsługiwane wyłącznie w przypadku przestrzeni nazw notebookutils.

Narzędzia systemu plików

notebookutils.fs udostępnia narzędzia do pracy z różnymi systemami plików, w tym usługą Azure Data Lake Storage (ADLS) Gen2 i usługą Azure Blob Storage. Upewnij się, że odpowiednio skonfigurowaliśmy dostęp do usług Azure Data Lake Storage Gen2 i Azure Blob Storage .

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

notebookutils.fs.help()

Wyjście

notebookutils.fs provides utilities for working with various FileSystems.

Below is overview about the available methods:

cp(from: String, to: String, recurse: Boolean = false): Boolean -> Copies a file or directory, possibly across FileSystems
fastcp(from: String, to: String, recurse: Boolean = true): Boolean -> [Preview] Copies a file or directory via azcopy, possibly across FileSystems
mv(from: String, to: String, createPath: Boolean = false, overwrite: Boolean = false): Boolean -> Moves a file or directory, possibly across FileSystems
ls(dir: String): Array -> Lists the contents of a directory
mkdirs(dir: String): Boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
put(file: String, contents: String, overwrite: Boolean = false): Boolean -> Writes the given String out to a file, encoded in UTF-8
head(file: String, maxBytes: int = 1024 * 100): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
append(file: String, content: String, createFileIfNotExists: Boolean): Boolean -> Append the content to a file
rm(dir: String, recurse: Boolean = false): Boolean -> Removes a file or directory
exists(file: String): Boolean -> Check if a file or directory exists
mount(source: String, mountPoint: String, extraConfigs: Map[String, Any]): Boolean -> Mounts the given remote storage directory at the given mount point
unmount(mountPoint: String): Boolean -> Deletes a mount point
mounts(): Array[MountPointInfo] -> Show information about what is mounted
getMountPath(mountPoint: String, scope: String = ""): String -> Gets the local path of the mount point

Use notebookutils.fs.help("methodName") for more info about a method.

NotebookUtils współdziała z systemem plików w taki sam sposób jak interfejsy API platformy Spark. Weź na przykład użycie narzędzia notebookutils.fs.mkdirs() i usługi Fabric lakehouse:

Użycie	Ścieżka względna z katalogu głównego systemu plików HDFS	Ścieżka bezwzględna dla systemu plików ABFS	Ścieżka bezwzględna dla lokalnego systemu plików w węźle sterownika
Jezioro inne niż domyślne	Nieobsługiwane	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/<> new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Domyślny lakehouse	Katalog w obszarze "Pliki" lub "Tabele": notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/<> new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")

Lista plików

Aby wyświetlić listę zawartości katalogu, użyj notebookutils.fs.ls(Ścieżka katalogu)).. Na przykład:

notebookutils.fs.ls("Files/tmp") # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # based on ABFS file system 
notebookutils.fs.ls("file:/tmp")  # based on local file system of driver node 

Wyświetlanie właściwości pliku

Ta metoda zwraca właściwości pliku, w tym nazwę pliku, ścieżkę pliku, rozmiar pliku oraz to, czy jest to katalog i plik.

files = notebookutils.fs.ls('Your directory path')
for file in files:
    print(file.name, file.isDir, file.isFile, file.path, file.size)

Tworzenie nowego katalogu

Ta metoda tworzy dany katalog, jeśli nie istnieje, i tworzy wszelkie niezbędne katalogi nadrzędne.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # based on ABFS file system 
notebookutils.fs.ls("file:/<new_dir>")  # based on local file system of driver node 

Kopiuj plik

Ta metoda kopiuje plik lub katalog i obsługuje działanie kopiowania w systemach plików.

notebookutils.fs.cp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Wydajny plik kopiowania

Ta metoda oferuje bardziej wydajne podejście do kopiowania lub przenoszenia plików, szczególnie w przypadku obsługi dużych woluminów danych. W celu zwiększenia wydajności w sieci szkieletowej zaleca się użycie fastcp jako zamiennik tradycyjnej cp metody.

Uwaga

notebookutils.fs.fastcp() program nie obsługuje kopiowania plików w usłudze OneLake w różnych regionach. W takim przypadku można użyć zamiast notebookutils.fs.cp() tego.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Podgląd zawartości pliku

Ta metoda zwraca do pierwszych bajtów "maxBytes" danego pliku jako ciąg zakodowany w formacie UTF-8.

notebookutils.fs.head('file path', maxBytes to read)

Przenieś plik

Ta metoda przenosi plik lub katalog i obsługuje przenoszenie między systemami plików.

notebookutils.fs.mv('source file or directory', 'destination directory', True) # Set the last parameter as True to firstly create the parent directory if it does not exist
notebookutils.fs.mv('source file or directory', 'destination directory', True, True) # Set the third parameter to True to firstly create the parent directory if it does not exist. Set the last parameter to True to overwrite the updates.

Zapisywanie pliku

Ta metoda zapisuje podany ciąg w pliku zakodowanym w formacie UTF-8.

notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it existed already

Dołączanie zawartości do pliku

Ta metoda dołącza dany ciąg do pliku zakodowanego w formacie UTF-8.

notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it does not exist

Uwaga

• notebookutils.fs.append() i notebookutils.fs.put() nie obsługują równoczesnego zapisu w tym samym pliku z powodu braku gwarancji niepodzielności.
• W przypadku używania interfejsu notebookutils.fs.append API w for pętli do zapisu w tym samym pliku zalecamy dodanie sleep instrukcji około 0,5s~1s między zapisami cyklicznym. Dzieje się tak dlatego, że notebookutils.fs.append wewnętrzna flush operacja interfejsu API jest asynchroniczna, dlatego krótkie opóźnienie pomaga zapewnić integralność danych.

Usuwanie pliku lub katalogu

Ta metoda usuwa plik lub katalog.

notebookutils.fs.rm('file path', True) # Set the last parameter as True to remove all files and directories recursively

Instalowanie/odinstalowywanie katalogu

Aby uzyskać więcej informacji na temat szczegółowego użycia, zobacz Instalowanie i odinstalowywanie plików.

Narzędzia notesu

Użyj narzędzi notesu, aby uruchomić notes lub zamknąć notes z wartością. Uruchom następujące polecenie, aby uzyskać przegląd dostępnych metod:

notebookutils.notebook.help()

Wyjście:

The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map, workspace: String): String -> This method runs a notebook and returns its exit value.
runMultiple(DAG: Any): Map[String, MsNotebookRunResult] -> [Preview] Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> [Preview] This method check if the DAG is correctly defined.

[Preview] Below methods are only support Fabric Notebook.
create(name: String, description: String = "", content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = ""): Artifact -> Create a new Notebook.
get(name: String, workspaceId: String = ""): Artifact -> Get a Notebook by name or id.
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact -> Update a Artifact by name.
delete(name: String, workspaceId: String = ""): Boolean -> Delete a Notebook by name.
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact] -> List all Notebooks in the workspace.
updateDefinition(name: String, content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = "") -> Update the definition of a Notebook.

Use notebookutils.notebook.help("methodName") for more info about a method.

Uwaga

Narzędzia notesu nie mają zastosowania do definicji zadań platformy Apache Spark (SJD).

Odwołanie do notesu

Ta metoda odwołuje się do notesu i zwraca wartość zakończenia. Wywołania funkcji zagnieżdżania można uruchamiać w notesie interaktywnie lub w potoku. Przywoływany notes jest uruchamiany w puli Spark notesu, który wywołuje tę funkcję.

notebookutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>, <workspaceId>)

Na przykład:

notebookutils.notebook.run("Sample1", 90, {"input": 20 })

Notes sieci szkieletowej obsługuje również odwoływanie się do notesów w wielu obszarach roboczych, określając identyfikator obszaru roboczego.

notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

Możesz otworzyć link migawki przebiegu odwołania w danych wyjściowych komórki. Migawka przechwytuje wyniki uruchomienia kodu i umożliwia łatwe debugowanie przebiegu odwołania.

Uwaga

• Notes referencyjny między obszarami roboczymi jest obsługiwany przez środowisko uruchomieniowe w wersji 1.2 lub nowszej.
• Jeśli używasz plików w obszarze Zasób notesu, użyj notebookutils.nbResPath w notesie, do którego się odwołujesz, aby upewnić się, że wskazuje on ten sam folder co uruchomienie interakcyjne.

Odwołanie do uruchamiania wielu notesów równolegle

Ważne

Ta funkcja jest dostępna w wersji zapoznawczej.

Metoda notebookutils.notebook.runMultiple() umożliwia równoległe uruchamianie wielu notesów lub ze wstępnie zdefiniowaną strukturą topologiczną. Interfejs API korzysta z mechanizmu implementacji wielowątowej w ramach sesji platformy Spark, co oznacza, że zasoby obliczeniowe są współużytkowane przez przebiegi notesu referencyjnego.

Za pomocą notebookutils.notebook.runMultiple()programu można wykonywać następujące czynności:

• Wykonaj wiele notesów jednocześnie bez oczekiwania na zakończenie każdego z nich.

• Określ zależności i kolejność wykonywania notesów przy użyciu prostego formatu JSON.

• Zoptymalizuj użycie zasobów obliczeniowych platformy Spark i zmniejsz koszty projektów sieci szkieletowej.

• Wyświetl migawki każdego rekordu przebiegu notesu w danych wyjściowych i wygodnie debuguj/monitoruj zadania notesu.

• Pobierz wartość zakończenia każdej aktywności wykonawczej i użyj ich w zadaniach podrzędnych.

Możesz również spróbować uruchomić notesutils.notebook.help("runMultiple"), aby znaleźć przykład i szczegółowe użycie.

Oto prosty przykład uruchamiania listy notesów równolegle przy użyciu tej metody:

notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])

Wynik wykonania z notesu głównego wygląda następująco:

Poniżej przedstawiono przykład uruchamiania notesów ze strukturą topologiczną przy użyciu polecenia notebookutils.notebook.runMultiple(). Ta metoda umożliwia łatwe organizowanie notesów za pomocą środowiska kodu.

# run multiple notebooks with parameters
DAG = {
    "activities": [
        {
            "name": "NotebookSimple", # activity name, must be unique
            "path": "NotebookSimple", # notebook path
            "timeoutPerCellInSeconds": 90, # max timeout for each cell, default to 90 seconds
            "args": {"p1": "changed value", "p2": 100}, # notebook parameters
        },
        {
            "name": "NotebookSimple2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200}
        },
        {
            "name": "NotebookSimple2.2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["NotebookSimple"] # list of activity names that this activity depends on
        }
    ],
    "timeoutInSeconds": 43200, # max timeout for the entire DAG, default to 12 hours
    "concurrency": 50 # max number of notebooks to run concurrently, default to 50
}
notebookutils.notebook.runMultiple(DAG, {"displayDAGViaGraphviz": False})

Wynik wykonania z notesu głównego wygląda następująco:

Udostępniamy również metodę sprawdzania, czy grupa DAG jest poprawnie zdefiniowana.

notebookutils.notebook.validateDAG(DAG)

Uwaga

• Stopień równoległości przebiegu wielu notesów jest ograniczony do całkowitego dostępnego zasobu obliczeniowego sesji platformy Spark.
• Górny limit działań notesu lub notesów współbieżnych wynosi 50. Przekroczenie tego limitu może prowadzić do problemów ze stabilnością i wydajnością z powodu wysokiego użycia zasobów obliczeniowych. Jeśli wystąpią problemy, rozważ rozdzielenie notesów na wiele runMultiple wywołań lub zmniejszenie współbieżności przez dostosowanie pola współbieżności w parametrze DAG.
• Domyślny limit czasu dla całej grupy DAG wynosi 12 godzin, a domyślny limit czasu dla każdej komórki w notesie podrzędnym wynosi 90 sekund. Limit czasu można zmienić, ustawiając limit czasuInSeconds i limit czasuPerCellInSeconds w parametrze DAG.

Zamykanie notesu

Ta metoda kończy notes z wartością. Wywołania funkcji zagnieżdżania można uruchamiać w notesie interaktywnie lub w potoku.

• Po interakcyjnym wywołaniu funkcji exit() z notesu notes sieć szkieletowa zgłasza wyjątek, pomija uruchamianie kolejnych komórek i utrzymuje sesję platformy Spark przy życiu.

• Gdy organizujesz notes w potoku, który wywołuje funkcję exit(), działanie notesu zwraca wartość z wartością zakończenia, kończy przebieg potoku i zatrzymuje sesję platformy Spark.

• Po wywołaniu funkcji exit() w notesie, do którego się odwołujesz, platforma Spark zatrzyma dalsze wykonywanie przywoływanego notesu i będzie nadal uruchamiać następne komórki w głównym notesie, który wywołuje funkcję run(). Na przykład: Notes1 ma trzy komórki i wywołuje funkcję exit() w drugiej komórce. Notes2 zawiera pięć komórek i wywołuje polecenie run(notebook1) w trzeciej komórce. Po uruchomieniu notesu Notebook2 notes1 zatrzymuje się w drugiej komórce po naciśnięciu funkcji exit(). Notes2 nadal działa w czwartej komórce i piątej komórce.

notebookutils.notebook.exit("value string")

Uwaga

Funkcja exit() zastąpi bieżące dane wyjściowe komórki, aby uniknąć utraty danych wyjściowych innych instrukcji kodu, wywołaj metodę notebookutils.notebook.exit() w osobnej komórce.

Na przykład:

Przykład1 notes z następującymi dwoma komórkami:

• Komórka 1 definiuje parametr wejściowy z wartością domyślną ustawioną na 10.

• Komórka 2 zamyka notes z danymi wejściowymi jako wartością zakończenia.

Przykład1 można uruchomić w innym notesie z wartościami domyślnymi:

exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)

Wyjście:

Notebook is executed successfully with exit value 10

Przykład1 można uruchomić w innym notesie i ustawić wartość wejściową na 20:

exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)

Wyjście:

Notebook is executed successfully with exit value 20

Zarządzanie artefaktami notesu

notebookutils.notebook Programowe zarządzanie elementami notesu zapewnia wyspecjalizowane narzędzia. Te interfejsy API mogą ułatwić tworzenie, pobieranie, aktualizowanie i usuwanie elementów notesu.

Aby skutecznie wykorzystać te metody, rozważ następujące przykłady użycia:

Tworzenie notesu

with open("/path/to/notebook.ipynb", "r") as f:
    content = f.read()

artifact = notebookutils.notebook.create("artifact_name", "description", "content", "default_lakehouse_name", "default_lakehouse_workspace_id", "optional_workspace_id")

Pobieranie zawartości notesu

artifact = notebookutils.notebook.get("artifact_name", "optional_workspace_id")

Aktualizowanie notesu

updated_artifact = notebookutils.notebook.update("old_name", "new_name", "optional_description", "optional_workspace_id")

updated_artifact_definition = notebookutils.notebook.updateDefinition("artifact_name",  "content", "default_lakehouse_name", "default_Lakehouse_Workspace_name", "optional_workspace_id")

Usuwanie notesu

is_deleted = notebookutils.notebook.delete("artifact_name", "optional_workspace_id")

Wyświetlanie listy notesów w obszarze roboczym

artifacts_list = notebookutils.notebook.list("optional_workspace_id")

Narzędzia poświadczeń

Narzędzia poświadczeń umożliwiają uzyskiwanie tokenów dostępu i zarządzanie wpisami tajnymi w usłudze Azure Key Vault.

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

notebookutils.credentials.help()

Wyjście:

Help on module notebookutils.credentials in notebookutils:

NAME
    notebookutils.credentials - Utility for credentials operations in Fabric

FUNCTIONS
    getSecret(akvName, secret) -> str
        Gets a secret from the given Azure Key Vault.
        :param akvName: The name of the Azure Key Vault.
        :param secret: The name of the secret.
        :return: The secret value.
    
    getToken(audience) -> str
        Gets a token for the given audience.
        :param audience: The audience for the token.
        :return: The token.
    
    help(method_name=None)
        Provides help for the notebookutils.credentials module or the specified method.
        
        Examples:
        notebookutils.credentials.help()
        notebookutils.credentials.help("getToken")
        :param method_name: The name of the method to get help with.

DATA
    creds = <notebookutils.notebookutils.handlers.CredsHandler.CredsHandler...

FILE
    /home/trusted-service-user/cluster-env/trident_env/lib/python3.10/site-packages/notebookutils/credentials.py

Uzyskiwanie tokenu

Funkcja getToken zwraca token entra firmy Microsoft dla danej grupy odbiorców i nazwy (opcjonalnie). Na poniższej liście przedstawiono obecnie dostępne klucze odbiorców:

• Zasób odbiorców magazynu: "storage"
• Zasób usługi Power BI: "pbi"
• Zasób usługi Azure Key Vault: "keyvault"
• Zasób usługi Synapse RTA KQL DB: "kusto"

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

notebookutils.credentials.getToken('audience Key')

Uzyskiwanie wpisu tajnego przy użyciu poświadczeń użytkownika

Polecenie getSecret zwraca wpis tajny usługi Azure Key Vault dla danego punktu końcowego usługi Azure Key Vault i nazwę wpisu tajnego przy użyciu poświadczeń użytkownika.

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

Instalowanie i odinstalowywanie plików

Sieć szkieletowa obsługuje następujące scenariusze instalacji w pakiecie Microsoft Spark Utilities. Interfejsy API instalacji, odinstalowania, getMountPath()i mounts() umożliwiają dołączenie magazynu zdalnego (ADLS Gen2) do wszystkich węzłów roboczych (węzłów sterownika i węzłów roboczych). Po zainstalowaniu punktu instalacji magazynu użyj lokalnego interfejsu API plików, aby uzyskać dostęp do danych tak, jakby był przechowywany w lokalnym systemie plików.

Jak zainstalować konto usługi ADLS Gen2

W poniższym przykładzie pokazano, jak zainstalować usługę Azure Data Lake Storage Gen2. Instalowanie usługi Blob Storage działa podobnie.

W tym przykładzie przyjęto założenie, że masz jedno konto usługi Data Lake Storage Gen2 o nazwie storegen2, a konto ma jeden kontener o nazwie mycontainer, który chcesz zainstalować do /test w sesji spark notesu.

Aby zainstalować kontener o nazwie mycontainer, najpierw należy sprawdzić, czy masz uprawnienia dostępu do kontenera. Obecnie sieć szkieletowa obsługuje dwie metody uwierzytelniania dla operacji instalacji wyzwalacza: accountKey i sastoken.

Instalowanie za pomocą tokenu sygnatury dostępu współdzielonego lub klucza konta

Aplikacja NotebookUtils obsługuje jawne przekazywanie klucza konta lub tokenu sygnatury dostępu współdzielonego (SAS) jako parametru do zainstalowania obiektu docelowego.

Ze względów bezpieczeństwa zalecamy przechowywanie kluczy konta lub tokenów SAS w usłudze Azure Key Vault (jak pokazano na poniższym zrzucie ekranu). Następnie można je pobrać przy użyciu interfejsu API notebookutils.credentials.getSecret . Aby uzyskać więcej informacji na temat usługi Azure Key Vault, zobacz About Azure Key Vault managed storage account keys (Informacje o kluczach konta magazynu zarządzanego w usłudze Azure Key Vault).

Przykładowy kod metody accountKey :

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

Przykładowy kod dla sygnatury dostępu współdzielonego:

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

Parametry instalacji:

• fileCacheTimeout: obiekty blob będą domyślnie buforowane w lokalnym folderze tymczasowym przez 120 sekund. W tym czasie program blobfuse nie sprawdzi, czy plik jest aktualny, czy nie. Parametr można ustawić tak, aby zmienić domyślny limit czasu. Gdy wielu klientów modyfikuje pliki jednocześnie, aby uniknąć niespójności między plikami lokalnymi i zdalnymi, zalecamy skrócenie czasu pamięci podręcznej, a nawet zmianę jej na 0 i zawsze pobieranie najnowszych plików z serwera.
• limit czasu: limit czasu operacji instalacji wynosi domyślnie 120 sekund. Parametr można ustawić tak, aby zmienić domyślny limit czasu. Jeśli występuje zbyt wiele funkcji wykonawczych lub gdy upłynął limit czasu instalacji, zalecamy zwiększenie wartości.

Możesz użyć tych parametrów w następujący sposób:

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

Uwaga

W celach bezpieczeństwa zaleca się unikanie osadzania poświadczeń bezpośrednio w kodzie. Aby dodatkowo zabezpieczyć poświadczenia, wszelkie wpisy tajne wyświetlane w danych wyjściowych notesu zostaną zredagowane. Aby uzyskać więcej informacji, zobacz Ponowne redagowanie wpisów tajnych.

Jak zainstalować jezioro

Przykładowy kod instalowania usługi Lakehouse do /<mount_name>:

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

Uzyskiwanie dostępu do plików w punkcie instalacji przy użyciu interfejsu API notebookutils fs

Głównym celem operacji instalacji jest umożliwianie klientom dostępu do danych przechowywanych na koncie magazynu zdalnego przy użyciu lokalnego interfejsu API systemu plików. Dostęp do danych można również uzyskać przy użyciu interfejsu API notebookutils fs z zainstalowanej ścieżki jako parametru. Ten format ścieżki jest nieco inny.

Załóżmy, że w kontenerze mycontainer usługi Data Lake Storage Gen2 został zainstalowany kontener /test przy użyciu interfejsu API instalacji. Gdy uzyskujesz dostęp do danych przy użyciu lokalnego interfejsu API systemu plików, format ścieżki wygląda następująco:

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

Jeśli chcesz uzyskać dostęp do danych przy użyciu interfejsu API notebookutils fs, zalecamy użycie metody getMountPath(), aby uzyskać dokładną ścieżkę:

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

• Katalogi listy:

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

• Odczytywanie zawartości pliku:

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

• Utwórz katalog:

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

Uzyskiwanie dostępu do plików w punkcie instalacji za pośrednictwem ścieżki lokalnej

Pliki w punkcie instalacji można łatwo odczytywać i zapisywać przy użyciu standardowego systemu plików. Oto przykład języka Python:

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

Jak sprawdzić istniejące punkty instalacji

Interfejs API notebookutils.fs.mounts() umożliwia sprawdzenie wszystkich istniejących informacji o punkcie instalacji:

notebookutils.fs.mounts()

Jak odinstalować punkt instalacji

Użyj następującego kodu, aby odinstalować punkt instalacji (/test w tym przykładzie):

notebookutils.fs.unmount("/test")

Znane ograniczenia

• Bieżąca instalacja jest konfiguracją poziomu zadania; Zalecamy użycie interfejsu API instalacji, aby sprawdzić, czy punkt instalacji istnieje, czy nie jest dostępny.

• Mechanizm odinstalowania nie jest stosowany automatycznie. Po zakończeniu działania aplikacji, aby odinstalować punkt instalacji i zwolnić miejsce na dysku, musisz jawnie wywołać odinstalowywanie interfejsu API w kodzie. W przeciwnym razie punkt instalacji nadal będzie istnieć w węźle po zakończeniu działania aplikacji.

• Instalowanie konta magazynu usługi ADLS Gen1 nie jest obsługiwane.

Narzędzia lakehouse

notebookutils.lakehouse udostępnia narzędzia specjalnie dostosowane do zarządzania elementami Lakehouse. Te narzędzia umożliwiają łatwe tworzenie, pobieranie, aktualizowanie i usuwanie artefaktów usługi Lakehouse.

Omówienie metod

Poniżej przedstawiono omówienie dostępnych metod udostępnianych przez notebookutils.lakehouseprogram :

# Create a new Lakehouse artifact
create(name: String, description: String = "", definition: ItemDefinition = null, workspaceId: String = ""): Artifact

# Retrieve a Lakehouse artifact
get(name: String, workspaceId: String = ""): Artifact

# Get a Lakehouse artifact with properties
getWithProperties(name: String, workspaceId: String = ""): Artifact

# Update an existing Lakehouse artifact
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact

# Delete a Lakehouse artifact
delete(name: String, workspaceId: String = ""): Boolean 

# List all Lakehouse artifacts
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]

# List all tables in a Lakehouse artifact
listTables(lakehouse: String, workspaceId: String = "", maxResults: Int = 1000): Array[Table] 

# Starts a load table operation in a Lakehouse artifact
loadTable(loadOption: collection.Map[String, Any], table: String, lakehouse: String, workspaceId: String = ""): Array[Table] 

Przykłady użycia

Aby skutecznie wykorzystać te metody, rozważ następujące przykłady użycia:

Tworzenie usługi Lakehouse

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")

Uzyskiwanie usługi Lakehouse

artifact = notebookutils.lakehouse.get("artifact_name", "optional_workspace_id")

artifact = notebookutils.lakehouse.getWithProperties("artifact_name", "optional_workspace_id")

Aktualizowanie usługi Lakehouse

updated_artifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

Usuwanie usługi Lakehouse

is_deleted = notebookutils.lakehouse.delete("artifact_name", "optional_workspace_id")

Wyświetlanie listy usługi Lakehouse w obszarze roboczym

artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")

Wyświetlanie listy wszystkich tabel w usłudze Lakehouse

artifacts_tables_list = notebookutils.lakehouse.listTables("artifact_name", "optional_workspace_id")

Uruchamianie operacji tabeli ładowania w usłudze Lakehouse

notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "artifact_name", "optional_workspace_id")

Dodatkowe informacje

Aby uzyskać bardziej szczegółowe informacje o każdej metodzie i jej parametrach, skorzystaj z notebookutils.lakehouse.help("methodName") funkcji .

Narzędzia środowiska uruchomieniowego

Pokaż informacje kontekstowe sesji

Za pomocą notebookutils.runtime.context możesz uzyskać informacje kontekstowe bieżącej sesji na żywo, w tym nazwę notesu, domyślną usługę Lakehouse, informacje o obszarze roboczym, jeśli jest to uruchomienie potoku itp.

notebookutils.runtime.context

Znany problem

W przypadku korzystania z wersji środowiska uruchomieniowego powyżej 1.2 i uruchamiania notebookutils.help()wymienionej na liście fabricClient interfejsy API PBIClient nie są obecnie obsługiwane, będą dostępne w dalszej części. Ponadto interfejs API poświadczeń nie jest obecnie obsługiwany w notesach Języka Scala.

Powiązana zawartość

• Microsoft Spark Utilities (MSSparkUtils) for Fabric
• Tworzenie, wykonywanie notesów usługi Microsoft Fabric i zarządzanie nimi
• Zarządzanie notesami i wykonywanie ich w sieci szkieletowej za pomocą interfejsów API