Notebook-WorkflowsNotebook workflows

Mit dem Befehl " % Run " können Sie ein anderes Notebook in ein Notebook einschließen.The %run command allows you to include another notebook within a notebook. Mit diesem Befehl können Sie verschiedene Notebooks verketten, die wichtige ETL-Schritte, Spark-Analyse Schritte oder Ad-hoc-Untersuchungen darstellen.This command lets you concatenate various notebooks that represent key ETL steps, Spark analysis steps, or ad-hoc exploration. Es ist jedoch nicht möglich, komplexere Daten Pipelines zu erstellen.However, it lacks the ability to build more complex data pipelines.

Notebook-Workflows sind eine Ergänzung %run von, da Sie die Rückgabe von Werten aus einem Notebook ermöglichen.Notebook workflows are a complement to %run because they let you return values from a notebook. Dies ermöglicht es Ihnen, problemlos komplexe Workflows und Pipelines mit Abhängigkeiten zu erstellen.This allows you to easily build complex workflows and pipelines with dependencies. Sie können Ausführungen ordnungsgemäß parametrisieren (z. b. eine Liste von Dateien in einem Verzeichnis erhalten und die Namen an ein anderes Notebook übergeben – etwas, das mit nicht möglich ist %run ), und auch if/then/else-Workflows auf der Grundlage von Rückgabe Werten erstellen.You can properly parameterize runs (for example, get a list of files in a directory and pass the names to another notebook—something that’s not possible with %run) and also create if/then/else workflows based on return values. Mithilfe von Notebook-Workflows können Sie andere Notebooks über relative Pfade abrufen.Notebook workflows allow you to call other notebooks via relative paths.

Sie implementieren Notebook-Workflows mit- dbutils.notebook Methoden.You implement notebook workflows with dbutils.notebook methods. Diese Methoden, wie alle dbutils APIs, sind nur in Scala und Python verfügbar.These methods, like all of the dbutils APIs, are available only in Scala and Python. Sie können jedoch verwenden, dbutils.notebook.run um ein R-Notebook aufzurufen .However, you can use dbutils.notebook.run to invoke an R notebook.

Hinweis

Aufträge mit langer Ausführungszeit für Notebooks, die mehr als 48 Stunden zum Abschluss benötigen, werden nicht unterstützt.Long-running notebook workflow jobs that take more than 48 hours to complete are not supported.

APIAPI

Die Methoden, die in der dbutils.notebook API zum Erstellen von Notebook-Workflows verfügbar sind, sind: run und exit .The methods available in the dbutils.notebook API to build notebook workflows are: run and exit. Beide Parameter und Rückgabewerte müssen Zeichen folgen sein.Both parameters and return values must be strings.

run(path: String, timeout_seconds: int, arguments: Map): String

Ausführen eines Notebooks und Zurückgeben des Beendigungs Werts.Run a notebook and return its exit value. Die-Methode startet einen kurzlebigen Auftrag, der sofort ausgeführt wird.The method starts an ephemeral job that runs immediately.

Der- timeout_seconds Parameter steuert das Timeout der Ausführung (0 bedeutet kein Timeout): der Aufruf von löst run eine Ausnahme aus, wenn er nicht innerhalb der angegebenen Zeit abgeschlossen wird.The timeout_seconds parameter controls the timeout of the run (0 means no timeout): the call to run throws an exception if it doesn’t finish within the specified time. Wenn Azure Databricks länger als 10 Minuten ausfällt, schlägt die Notebook-Laufzeit unabhängig von fehl timeout_seconds .If Azure Databricks is down for more than 10 minutes, the notebook run fails regardless of timeout_seconds.

Der- arguments Parameter legt die widgewerte des Ziel Notebooks fest.The arguments parameter sets widget values of the target notebook. Insbesondere, wenn das Notebook, das Sie ausführen, über ein Widget namens verfügt A und Sie ein Schlüssel-Wert-Paar ("A": "B") als Teil des Arguments-Parameters an den-Befehl übergeben run() , gibt das Abrufen des Werts des Widgets A zurück "B" .Specifically, if the notebook you are running has a widget named A, and you pass a key-value pair ("A": "B") as part of the arguments parameter to the run() call, then retrieving the value of widget A will return "B". Die Anweisungen zum Erstellen und arbeiten mit Widgets finden Sie im Artikel zu Widgets .You can find the instructions for creating and working with widgets in the Widgets article.

Warnung

Der- arguments Parameter akzeptiert nur lateinische Zeichen (ASCII-Zeichensatz).The arguments parameter accepts only Latin characters (ASCII character set). Wenn Sie nicht-ASCII-Zeichen verwenden, wird ein Fehler zurückgegeben.Using non-ASCII characters will return an error. Beispiele für ungültige, nicht-ASCII-Zeichen sind Chinesisch, Japanisch Kanjis und Emojis.Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.

run Verwendungrun Usage

PythonPython

dbutils.notebook.run("notebook-name", 60, {"argument": "data", "argument2": "data2", ...})

ScalaScala

dbutils.notebook.run("notebook-name", 60, Map("argument" -> "data", "argument2" -> "data2", ...))

run Beispielrun Example

Angenommen, Sie verfügen über ein Notebook workflows mit dem Namen mit einem Widget namens foo , das den Wert des Widgets ausgibt:Suppose you have a notebook named workflows with a widget named foo that prints the widget’s value:

dbutils.widgets.text("foo", "fooDefault", "fooEmptyLabel")
print dbutils.widgets.get("foo")

Das Ausführen von dbutils.notebook.run("workflows", 60, {"foo": "bar"}) führt zu folgendem Ergebnis:Running dbutils.notebook.run("workflows", 60, {"foo": "bar"}) produces the following result:

Notebook-Workflow mit widgetNotebook workflow with widget

Das Widget enthielt den Wert, den Sie über den Workflow übergebenen, "bar" anstelle der Standardeinstellung.The widget had the value you passed in through the workflow, "bar", rather than the default.

exit(value: String): void Beenden Sie ein Notebook mit einem Wert.exit(value: String): void Exit a notebook with a value. Wenn Sie ein Notebook mithilfe der- run Methode aufzurufen, ist dies der zurückgegebene Wert.If you call a notebook using the run method, this is the value returned.

dbutils.notebook.exit("returnValue")

dbutils.notebook.exitDas Aufrufen von in einem Auftrag bewirkt, dass das Notebook erfolgreich abgeschlossen wird.Calling dbutils.notebook.exit in a job causes the notebook to complete successfully. Wenn Sie bewirken möchten, dass der Auftrag fehlschlägt, lösen Sie eine Ausnahme aus.If you want to cause the job to fail, throw an exception.

Beispiel Example

Im folgenden Beispiel übergeben Sie Argumente an DataImportNotebook und führen verschiedene Notebooks ( DataCleaningNotebook oder ErrorHandlingNotebook ) basierend auf dem Ergebnis von aus DataImportNotebook .In the following example, you pass arguments to DataImportNotebook and run different notebooks (DataCleaningNotebook or ErrorHandlingNotebook) based on the result from DataImportNotebook.

Notebook-WorkflowNotebook workflow

Wenn der Notebook-Workflow ausgeführt wird, wird ein Link zum ausgeführten Notebook angezeigt:When the notebook workflow runs, you see a link to the running notebook:

Notebook-Workflow-ausführenNotebook workflow run

Klicken Sie auf den Notebook Link Notebook- Auftrag #xxxx , um die Details des Testlaufs anzuzeigen:Click the notebook link Notebook job #xxxx to view the details of the run:

Ergebnis der Notebook-Workflow LaufzeitNotebook workflow run result

Übergeben strukturierter DatenPass structured data

In diesem Abschnitt wird veranschaulicht, wie strukturierte Daten zwischen Notebooks übergeben werden.This section illustrates how to pass structured data between notebooks.

PythonPython

# Example 1 - returning data through temporary views.
# You can only return one string using dbutils.notebook.exit(), but since called notebooks reside in the same JVM, you can
# return a name referencing data stored in a temporary view.

## In callee notebook
sqlContext.range(5).toDF("value").createOrReplaceGlobalTempView("my_data")
dbutils.notebook.exit("my_data")

## In caller notebook
returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
global_temp_db = spark.conf.get("spark.sql.globalTempDatabase")
display(table(global_temp_db + "." + returned_table))

# Example 2 - returning data through DBFS.
# For larger datasets, you can write the results to DBFS and then return the DBFS path of the stored data.

## In callee notebook
dbutils.fs.rm("/tmp/results/my_data", recurse=True)
sqlContext.range(5).toDF("value").write.parquet("dbfs:/tmp/results/my_data")
dbutils.notebook.exit("dbfs:/tmp/results/my_data")

## In caller notebook
returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
display(sqlContext.read.parquet(returned_table))

# Example 3 - returning JSON data.
# To return multiple values, you can use standard JSON libraries to serialize and deserialize results.

## In callee notebook
import json
dbutils.notebook.exit(json.dumps({
  "status": "OK",
  "table": "my_data"
}))

## In caller notebook
result = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
print json.loads(result)

ScalaScala

// Example 1 - returning data through temporary views.
// You can only return one string using dbutils.notebook.exit(), but since called notebooks reside in the same JVM, you can
// return a name referencing data stored in a temporary view.

/** In callee notebook */
sc.parallelize(1 to 5).toDF().createOrReplaceGlobalTempView("my_data")
dbutils.notebook.exit("my_data")

/** In caller notebook */
val returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
val global_temp_db = spark.conf.get("spark.sql.globalTempDatabase")
display(table(global_temp_db + "." + returned_table))

// Example 2 - returning data through DBFS.
// For larger datasets, you can write the results to DBFS and then return the DBFS path of the stored data.

/** In callee notebook */
dbutils.fs.rm("/tmp/results/my_data", recurse=true)
sc.parallelize(1 to 5).toDF().write.parquet("dbfs:/tmp/results/my_data")
dbutils.notebook.exit("dbfs:/tmp/results/my_data")

/** In caller notebook */
val returned_table = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
display(sqlContext.read.parquet(returned_table))

// Example 3 - returning JSON data.
// To return multiple values, you can use standard JSON libraries to serialize and deserialize results.

/** In callee notebook */

// Import jackson json libraries
import com.fasterxml.jackson.module.scala.DefaultScalaModule
import com.fasterxml.jackson.module.scala.experimental.ScalaObjectMapper
import com.fasterxml.jackson.databind.ObjectMapper

// Create a json serializer
val jsonMapper = new ObjectMapper with ScalaObjectMapper
jsonMapper.registerModule(DefaultScalaModule)

// Exit with json
dbutils.notebook.exit(jsonMapper.writeValueAsString(Map("status" -> "OK", "table" -> "my_data")))

/** In caller notebook */
val result = dbutils.notebook.run("LOCATION_OF_CALLEE_NOTEBOOK", 60)
println(jsonMapper.readValue[Map[String, String]](result))

Behandeln von FehlernHandle errors

In diesem Abschnitt wird veranschaulicht, wie Fehler in Notebook-Workflows behandelt werden.This section illustrates how to handle errors in notebook workflows.

PythonPython

# Errors in workflows thrown a WorkflowException.

def run_with_retry(notebook, timeout, args = {}, max_retries = 3):
  num_retries = 0
  while True:
    try:
      return dbutils.notebook.run(notebook, timeout, args)
    except Exception as e:
      if num_retries > max_retries:
        raise e
      else:
        print "Retrying error", e
        num_retries += 1

run_with_retry("LOCATION_OF_CALLEE_NOTEBOOK", 60, max_retries = 5)

ScalaScala

// Errors in workflows thrown a WorkflowException.

import com.databricks.WorkflowException

// Since dbutils.notebook.run() is just a function call, you can retry failures using standard Scala try-catch
// control flow. Here we show an example of retrying a notebook a number of times.
def runRetry(notebook: String, timeout: Int, args: Map[String, String] = Map.empty, maxTries: Int = 3): String = {
  var numTries = 0
  while (true) {
    try {
      return dbutils.notebook.run(notebook, timeout, args)
    } catch {
      case e: WorkflowException if numTries < maxTries =>
        println("Error, retrying: " + e)
    }
    numTries += 1
  }
  "" // not reached
}

runRetry("LOCATION_OF_CALLEE_NOTEBOOK", timeout = 60, maxTries = 5)

Gleichzeitiges Ausführen mehrerer NotebooksRun multiple notebooks concurrently

Sie können mehrere Notebooks gleichzeitig ausführen, indem Sie Standard-Scala-und python-Konstrukte wie z. b. Threads (Scala, python) und Futures (Scala, python) verwenden.You can run multiple notebooks at the same time by using standard Scala and Python constructs such as Threads (Scala, Python) and Futures (Scala, Python). Die Advanced Notebook-Workflow Notebooks veranschaulichen die Verwendung dieser Konstrukte.The advanced notebook workflow notebooks demonstrate how to use these constructs. Die Notebooks sind in Scala, aber Sie können das entsprechende in python problemlos schreiben.The notebooks are in Scala but you could easily write the equivalent in Python. So führen Sie das Beispiel aus:To run the example:

  1. Laden Sie das Notebook-Archivherunter.Download the notebook archive.
  2. Importieren Sie das Archiv in einen Arbeitsbereich.Import the archive into a workspace.
  3. Führen Sie das Notebook für gleichzeitige Notebooks aus.Run the Concurrent Notebooks notebook.