Databricks-HilfsprogrammeDatabricks Utilities

Databricks-Hilfsprogramme (dbutils) vereinfachen die Durchführung leistungsfähiger Kombinationen von Tasks.Databricks Utilities (DBUtils) make it easy to perform powerful combinations of tasks. Mit den Dienstprogrammen können Sie effizient mit dem Objektspeicher arbeiten, Notebooks verketten und parametrisieren und mit Geheimnissen arbeiten.You can use the utilities to work with object storage efficiently, to chain and parameterize notebooks, and to work with secrets. Dbutils werden außerhalb von Notebooks nicht unterstützt.DBUtils are not supported outside of notebooks.

Alle dbutils Hilfsprogramme sind in Python-, R-und Scala-Notebooks verfügbar.All dbutils utilities are available in Python, R, and Scala notebooks. Dateisystem-Hilfsprogramme sind in R-Notebooks nicht verfügbar. Sie können jedoch einen sprach Magic-Befehl verwenden, um diese dbutils Methoden in R-und SQL-Notebooks aufzurufen.File system utilities are not available in R notebooks; however, you can use a language magic command to invoke those dbutils methods in R and SQL notebooks. Führen Sie beispielsweise den folgenden Befehl aus, um den Ordner " Azure Databricks Datasets dBFS" in einem R-oder SQL-Notebook aufzulisten:For example, to list the Azure Databricks datasets DBFS folder in an R or SQL notebook, run the command:

dbutils.fs.ls("/databricks-datasets")

Alternativ können Sie Folgendes verwenden %fs :Alternatively, you can use %fs:

%fs ls /databricks-datasets

Dateisystem-Hilfsprogramme File system utilities

Die Dateisystem-Hilfsprogramme greifen auf das databricks-Dateisystem (dBFS)zu, um die Verwendung Azure Databricks als Dateisystem zu vereinfachen.The file system utilities access Databricks File System (DBFS), making it easier to use Azure Databricks as a file system. Weitere Informationen finden Sie unter:Learn more by running:

dbutils.fs.help()
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> 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
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point

dbutils.fs.ls-Befehldbutils.fs.ls Command

Die vom Befehl zurückgegebene Sequenz ls enthält die folgenden Attribute:The sequence returned by the ls command contains the following attributes:

attributeAttribute typeType BeschreibungDescription
pathpath Zeichenfolgestring Der Pfad der Datei oder des Verzeichnisses.The path of the file or directory.
namename Zeichenfolgestring Der Name der Datei oder des Verzeichnisses.The name of the file or directory.
isDir ()isDir() booleanboolean True, wenn der Pfad ein Verzeichnis ist.True if the path is a directory.
sizesize Long/Int64long/int64 Die Länge der Datei in Bytes oder 0 (null), wenn der Pfad ein Verzeichnis ist.The length of the file in bytes or zero if the path is a directory.

Hinweis

Ausführliche Informationen zu den einzelnen Befehlen können Sie mithilfe von erhalten help , beispielsweise: dbutils.fs.help("ls")You can get detailed information about each command by using help, for example: dbutils.fs.help("ls")

Notebook-Workflow Dienstprogramme Notebook workflow utilities

Notebook-Workflows ermöglichen es Ihnen, Notebooks zu verketten und ihre Ergebnisse zu agieren.Notebook workflows allow you to chain together notebooks and act on their results. Siehe Notebook-Workflows.See Notebook workflows. Weitere Informationen finden Sie unter:Learn more by running:

dbutils.notebook.help()
exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value.

Hinweis

Die maximale Länge des von zurückgegebenen Zeichen folgen Werts run beträgt 5 MB.The maximum length of the string value returned from run is 5 MB. Siehe Ausführungen Get Output.See Runs get output.

Hinweis

Ausführliche Informationen zu den einzelnen Befehlen können Sie mithilfe von erhalten help , beispielsweise: dbutils.notebook.help("exit")You can get detailed information about each command by using help, for example: dbutils.notebook.help("exit")

Widget-Hilfsprogramme Widget utilities

Mit Widgets können Sie Notebooks parametrisieren.Widgets allow you to parameterize notebooks. Siehe Widgets.See Widgets. Weitere Informationen finden Sie unter:Learn more by running:

dbutils.widgets.help()
combobox(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a combobox input widget with a given name, default value and choices
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a dropdown input widget a with given name, default value and choices
get(name: String): String -> Retrieves current value of an input widget
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value

Hinweis

Ausführliche Informationen zu den einzelnen Befehlen können Sie mithilfe von erhalten help , beispielsweise: dbutils.widgets.help("combobox")You can get detailed information about each command by using help, for example: dbutils.widgets.help("combobox")

Geheimnisse Secrets utilities

Mit Geheimnissen können Sie vertrauliche Anmelde Informationen speichern und darauf zugreifen, ohne Sie in Notebooks sichtbar zu machen.Secrets allow you to store and access sensitive credential information without making them visible in notebooks. Weitere Informationen finden Sie unter Secret Management und Verwenden der geheimen Schlüssel in einem Notebook.See Secret management and Use the secrets in a notebook. Weitere Informationen finden Sie unter:Learn more by running:

dbutils.secrets.help()
get(scope: String, key: String): String -> Gets the string representation of a secret value with scope and key
getBytes(scope: String, key: String): byte[] -> Gets the bytes representation of a secret value with scope and key
list(scope: String): Seq -> Lists secret metadata for secrets within a scope
listScopes: Seq -> Lists secret scopes

Hinweis

Ausführliche Informationen zu den einzelnen Befehlen können Sie mithilfe von erhalten help , beispielsweise: dbutils.secrets.help("get")You can get detailed information about each command by using help, for example: dbutils.secrets.help("get")

Bibliotheks Dienstprogramme Library utilities

Mit Bibliotheks Dienstprogrammen können Sie python-Bibliotheken installieren und eine Umgebung erstellen, die auf eine Notebook-Sitzung bezogen ist.Library utilities allow you to install Python libraries and create an environment scoped to a notebook session. Die Bibliotheken sind sowohl für den Treiber als auch für die Executors verfügbar, sodass Sie in UDFs darauf verweisen können.The libraries are available both on the driver and on the executors, so you can reference them in UDFs. Dadurch wird Folgendes ermöglicht:This enables:

  • Bibliotheksabhängigkeiten eines Notebooks, die im Notebook selbst organisiert werden sollen.Library dependencies of a notebook to be organized within the notebook itself.
  • Notebook-Benutzer mit unterschiedlichen Bibliotheksabhängigkeiten, um einen Cluster ohne Störungen freizugeben.Notebook users with different library dependencies to share a cluster without interference.

Das Trennen eines Notebooks zerstört diese Umgebung.Detaching a notebook destroys this environment. Allerdings können Sie Sie neu erstellen, indem Sie die Bibliotheks- install API-Befehle erneut im Notebook ausführen.However, you can recreate it by re-running the library install API commands in the notebook. Sehen restartPython Sie sich die API an, wie Sie Ihren Notebook-Status zurücksetzen können, ohne Ihre Umgebung zu verlieren.See the restartPython API for how you can reset your notebook state without losing your environment.

Hinweis

Bibliotheks Dienstprogramme sind auf Databricks Runtime ml oder Databricks Runtime für Genomics nicht verfügbar.Library utilities are not available on Databricks Runtime ML or Databricks Runtime for Genomics. Weitere Informationen finden Sie unter python-Bibliotheken mit NotebookBereich.Instead, see Notebook-scoped Python libraries.

Bei Databricks Runtime 7,1 oder höher können Sie auch %pip Magic-Befehle verwenden, um Bibliotheken im Notebook Bereich zu installieren.For Databricks Runtime 7.1 or above, you can also use %pip magic commands to install notebook-scoped libraries. Informationen finden Sie unter Python-Bibliotheken im Notebook-Bereich.See Notebook-scoped Python libraries.

Bibliotheks Dienstprogramme sind standardmäßig aktiviert.Library utilities are enabled by default. Daher wird die python-Umgebung für jedes Notebook standardmäßig mithilfe einer separaten ausführbaren python-Datei isoliert, die erstellt wird, wenn das Notebook an die python-Standardumgebung im Cluster angefügt wird.Therefore, by default the Python environment for each notebook is isolated by using a separate Python executable that is created when the notebook is attached to and inherits the default Python environment on the cluster. Bibliotheken, die über ein Init-Skript in der Azure Databricks python-Umgebung installiert werden, sind weiterhin verfügbar.Libraries installed through an init script into the Azure Databricks Python environment are still available. Sie können diese Funktion deaktivieren, indem Sie spark.databricks.libraryIsolation.enabled auf festlegen false .You can disable this feature by setting spark.databricks.libraryIsolation.enabled to false.

Diese API ist mit der vorhandenen Cluster weiten Bibliotheks Installation über die Benutzeroberfläche und die Rest-APIkompatibel.This API is compatible with the existing cluster-wide library installation through the UI and REST API. Bibliotheken, die über diese API installiert werden, haben eine höhere Priorität als Cluster übergreifende Bibliotheken.Libraries installed through this API have higher priority than cluster-wide libraries.

dbutils.library.help()
install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session

Hinweis

Ausführliche Informationen zu den einzelnen Befehlen können Sie mithilfe von erhalten help , beispielsweise: dbutils.library.help("install")You can get detailed information about each command by using help, for example: dbutils.library.help("install")

BeispieleExamples

  • Installieren Sie eine pypi-Bibliothek in einem Notebook.Install a PyPI library in a notebook. version, repo und extras sind optional.version, repo, and extras are optional. Verwenden Sie das- extras Argument, um das Feature "Extras " anzugeben (zusätzliche Anforderungen).Use the extras argument to specify the Extras feature (extra requirements).

    dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    Wichtig

    Die version extras Schlüssel und können nicht Teil der pypi-Paket Zeichenfolge sein.The version and extras keys cannot be part of the PyPI package string. Beispiel: dbutils.library.installPyPI("azureml-sdk[databricks]==1.0.8") ist ungültig.For example: dbutils.library.installPyPI("azureml-sdk[databricks]==1.0.8") is not valid. Verwenden version Sie das-Argument und das- extras Argument, um die Informationen zu Version und Extras wie folgt anzugebenUse the version and extras arguments to specify the version and extras information as follows:

    dbutils.library.installPyPI("azureml-sdk", version="1.0.8", extras="databricks")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    
  • Geben Sie die Bibliotheks Anforderungen in einem Notebook an, und installieren Sie Sie über %run das andere.Specify your library requirements in one notebook and install them through %run in the other.

    • Definieren Sie die Bibliotheken, die in einem Notebook namens installiert werden sollen InstallDependencies .Define the libraries to install in a notebook called InstallDependencies.

      dbutils.library.installPyPI("torch")
      dbutils.library.installPyPI("scikit-learn", version="1.19.1")
      dbutils.library.installPyPI("azureml-sdk", extras="databricks")
      dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
      
    • Installieren Sie Sie im Notebook, das diese Abhängigkeiten benötigt.Install them in the notebook that needs those dependencies.

      %run /path/to/InstallDependencies    # Install the dependencies in first cell
      
      import torch
      from sklearn.linear_model import LinearRegression
      import azureml
      # do the actual work
      
  • Listet die Bibliotheken auf, die in einem Notebook installiert sind.List the libraries installed in a notebook.

    dbutils.library.list()
    
  • Setzen Sie den Zustand des python-Notebooks bei Beibehaltung der Umgebung zurück.Reset the Python notebook state while maintaining the environment. Diese API ist nur in python-Notebooks verfügbar.This API is available only in Python notebooks. Dies kann für Folgendes verwendet werden:This can be used to:

    • Erneutes Laden von Bibliotheken Azure Databricks mit einer anderen Version vorinstalliert.Reload libraries Azure Databricks preinstalled with a different version. Zum Beispiel:For example:

      dbutils.library.installPyPI("numpy", version="1.15.4")
      dbutils.library.restartPython()
      
      # Make sure you start using the library in another cell.
      import numpy
      
    • Installieren Sie Bibliotheken wie tensorflow, die beim Prozessstart geladen werden müssen.Install libraries like tensorflow that need to be loaded on process start up. Zum Beispiel:For example:

      dbutils.library.installPyPI("tensorflow")
      dbutils.library.restartPython()
      
      # Use the library in another cell.
      import tensorflow
      
  • Installieren Sie eine- .egg oder- .whl Bibliothek in einem Notebook.Install a .egg or .whl library in a notebook.

    Wichtig

    Es wird empfohlen, dass Sie alle Ihre Bibliotheks Installations Befehle in die erste Zelle Ihres Notebooks einfügen und restartPython am Ende dieser Zelle anrufen.We recommend that you put all your library install commands in the first cell of your notebook and call restartPython at the end of that cell. Der python-Notebook-Status wird nach der Ausführung zurückgesetzt restartPython . das Notebook verliert den gesamten Zustand, einschließlich, aber nicht beschränkt auf lokale Variablen, importierte Bibliotheken und andere kurzlebige Zustände.The Python notebook state is reset after running restartPython; the notebook loses all state including but not limited to local variables, imported libraries, and other ephemeral states. Daher wird empfohlen, dass Sie Bibliotheken installieren und den Notebook-Status in der ersten Notebook-Zelle zurücksetzen.Therefore, we recommended that you install libraries and reset the notebook state in the first notebook cell.

    Die akzeptierten Bibliotheks Quellen sind dbfs , abfss , adl und wasbs .The accepted library sources are dbfs, abfss, adl, and wasbs.

    dbutils.library.install("abfss:/path/to/your/library.egg")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    
    dbutils.library.install("abfss:/path/to/your/library.whl")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

Dbutils-NotebookDBUtils notebook

Notebook abrufenGet notebook

Databricks-Hilfsprogramme-API -Bibliothek Databricks Utilities API library

Hinweis

Sie können diese Bibliothek nicht zum Ausführen von Tests vor der Bereitstellung verwenden, wenn Sie in einem Cluster bereitstellen, auf dem Databricks Runtime 7,0 oder höher ausgeführt wird, da es keine Version der Bibliothek gibt, die Scala 2,12 unterstützt.You cannot use this library to run pre-deployment tests if you are deploying to a cluster running Databricks Runtime 7.0 or above, because there is no version of the library that supports Scala 2.12.

Um die Anwendungsentwicklung zu beschleunigen, kann es hilfreich sein, Anwendungen zu kompilieren, zu erstellen und zu testen, bevor Sie Sie als Produktionsaufträge bereitstellen.To accelerate application development, it can be helpful to compile, build, and test applications before you deploy them as production jobs. Um die Kompilierung für databricks-Hilfsprogramme zu ermöglichen, stellt databricks die dbutils-api Bibliothek bereit.To enable you to compile against Databricks Utilities, Databricks provides the dbutils-api library. Sie können die dbutils-API-Bibliothek herunterladen oder die Bibliothek einschließen, indem Sie der Builddatei eine Abhängigkeit hinzufügen:You can download the dbutils-api library or include the library by adding a dependency to your build file:

  • SBTSBT

    libraryDependencies += "com.databricks" % "dbutils-api_2.11" % "0.0.4"
    
  • MavenMaven

    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_2.11</artifactId>
        <version>0.0.4</version>
    </dependency>
    
  • GradleGradle

    compile 'com.databricks:dbutils-api_2.11:0.0.4'
    

Nachdem Sie die Anwendung für diese Bibliothek erstellt haben, können Sie die Anwendung bereitstellen.Once you build your application against this library, you can deploy the application.

Wichtig

Die- dbutils-api Bibliothek ermöglicht Ihnen die lokale Kompilierung einer Anwendung dbutils , die verwendet, jedoch nicht, um Sie auszuführen.The dbutils-api library allows you to locally compile an application that uses dbutils, but not to run it. Wenn Sie die Anwendung ausführen möchten, müssen Sie Sie in Azure Databricks bereitstellen.To run the application, you must deploy it in Azure Databricks.

Drücken Sie die Scala-Version des Artefakts mit %%Express the artifact’s Scala version with %%

Wenn Sie die artefaktversion als groupID %% artifactID % revision anstelle von Ausdrücken groupID % artifactID % revision (der Unterschied ist der Double-Wert %% nach dem groupID ), fügt SBT dem Artefaktnamen die Scala-Version Ihres Projekts hinzu.If you express the artifact version as groupID %% artifactID % revision instead of groupID % artifactID % revision (the difference is the double %% after the groupID), SBT will add your project’s Scala version to the artifact name.

BeispielExample

Angenommen, scalaVersion für den Build ist 2.9.1 .Suppose the scalaVersion for your build is 2.9.1. Sie könnten die artefaktversion mit % wie folgt schreiben:You could write the artifact version with % as follows:

val appDependencies = Seq(
  "org.scala-tools" % "scala-stm_2.9.1" % "0.3"
)

Die folgende Verwendung von %% ist identisch:The following using %% is identical:

val appDependencies = Seq(
  "org.scala-tools" %% "scala-stm" % "0.3"
)

Beispiel ProjekteExample projects

Hier finden Sie ein Beispiel Archiv mit minimalen Beispielprojekten, in denen veranschaulicht wird, wie Sie mithilfe der dbutils-api Bibliothek für drei gängige Buildtools kompilieren:Here is an example archive containing minimal example projects that show you how to compile using the dbutils-api library for 3 common build tools:

  • SBT sbt packagesbt: sbt package
  • Maven mvn installMaven: mvn install
  • Gradle gradle buildGradle: gradle build

Mit diesen Befehlen werden Ausgabe JAR-Dateien an den Speicherorten erstellt:These commands create output JARs in the locations:

  • SBT target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jarsbt: target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jar
  • Maven target/dbutils-api-example-0.0.1-SNAPSHOT.jarMaven: target/dbutils-api-example-0.0.1-SNAPSHOT.jar
  • Gradle build/examples/dbutils-api-example-0.0.1-SNAPSHOT.jarGradle: build/examples/dbutils-api-example-0.0.1-SNAPSHOT.jar

Sie können diese jar-Informationen als Bibliothek an Ihren Cluster anfügen, den Cluster neu starten und dann Folgendes ausführen:You can attach this JAR to your cluster as a library, restart the cluster, and then run:

example.Test()

Mit dieser Anweisung wird ein _texteingabewidget_mit der Bezeichnung " Hello: " und "Initial Value World" erstellt.This statement creates a text input widget with the label Hello: and the initial value World.

Sie können alle anderen APIs auf dbutils die gleiche Weise verwenden.You can use all the other dbutils APIs the same way.

Um eine Anwendung zu testen, die das dbutils Objekt außerhalb von databricks verwendet, können Sie das dbutils Objekt durch Aufrufen von bereinigen:To test an application that uses the dbutils object outside Databricks, you can mock up the dbutils object by calling:

com.databricks.dbutils_v1.DBUtilsHolder.dbutils0.set(
  new com.databricks.dbutils_v1.DBUtilsV1{
    ...
  }
)

Ersetzen Sie Ihre eigene DBUtilsV1 Instanz, in der Sie die Schnittstellen Methoden wie gewünscht implementieren, z. b. das Bereitstellen eines lokalen Dateisystems für das Dateisystem dbutils.fs .Substitute your own DBUtilsV1 instance in which you implement the interface methods however you like, for example providing a local filesystem mockup for dbutils.fs.