تشغيل دفتر ملاحظات Databricks من دفتر ملاحظات آخر

هام

لتنسيق دفتر الملاحظات، استخدم وظائف Databricks. بالنسبة لسيناريوهات وحدات التعليمات البرمجية، استخدم ملفات مساحة العمل. يجب عليك استخدام التقنيات الموضحة في هذه المقالة فقط عندما لا يمكن تنفيذ حالة الاستخدام الخاصة بك باستخدام مهمة Databricks، مثل تكرار دفاتر الملاحظات عبر مجموعة ديناميكية من المعلمات، أو إذا لم يكن لديك حق الوصول إلى ملفات مساحة العمل. لمزيد من المعلومات، راجع جدولة مهام سير العمل وتنسيقها ومشاركة التعليمات البرمجية.

مقارنة بين %run و dbutils.notebook.run()

%run يسمح لك الأمر بتضمين دفتر ملاحظات آخر داخل دفتر ملاحظات. يمكنك استخدام %run لنمذجة التعليمات البرمجية الخاصة بك، على سبيل المثال عن طريق وضع وظائف الدعم في دفتر ملاحظات منفصل. يمكنك أيضا استخدامه لسلسلة دفاتر الملاحظات التي تنفذ الخطوات في التحليل. عند استخدام %run، يتم تنفيذ دفتر الملاحظات المسمى على الفور وتصبح الوظائف والمتغيرات المحددة فيه متوفرة في دفتر الملاحظات الاستدعاء.

dbutils.notebook تعد واجهة برمجة التطبيقات مكملا لها %run لأنها تتيح لك تمرير المعلمات وإرجاع القيم من دفتر ملاحظات. يسمح لك هذا بإنشاء مهام سير عمل ومسارات معقدة مع تبعيات. على سبيل المثال، يمكنك الحصول على قائمة بالملفات في دليل وتمرير الأسماء إلى دفتر ملاحظات آخر، وهو أمر غير ممكن مع %run. يمكنك أيضا إنشاء مهام سير عمل if-then-else استنادا إلى قيم الإرجاع أو استدعاء دفاتر الملاحظات الأخرى باستخدام مسارات نسبية.

على عكس %run، dbutils.notebook.run() يبدأ الأسلوب مهمة جديدة لتشغيل دفتر الملاحظات.

تتوفر هذه الأساليب، مثل جميع dbutils واجهات برمجة التطبيقات، فقط في Python وSc scala. ومع ذلك، يمكنك استخدام dbutils.notebook.run() لاستدعاء دفتر ملاحظات R.

استخدام %run لاستيراد دفتر ملاحظات

في هذا المثال، يعرف دفتر الملاحظات الأول دالة، ، reverseوالتي تتوفر في دفتر الملاحظات الثاني بعد استخدام %run السحر لتنفيذ shared-code-notebook.

نظرا لوجود كل من دفتري الملاحظات في نفس الدليل في مساحة العمل، استخدم البادئة ./ في ./shared-code-notebook للإشارة إلى أنه يجب حل المسار بالنسبة إلى دفتر الملاحظات قيد التشغيل حاليا. يمكنك تنظيم دفاتر الملاحظات في دلائل، مثل %run ./dir/notebook، أو استخدام مسار مطلق مثل %run /Users/username@organization.com/directory/notebook.

إشعار

• %run يجب أن يكون في خلية بمفرده، لأنه يقوم بتشغيل دفتر الملاحظات بأكمله مضمنا.
• لا يمكنك استخدام %run لتشغيل ملف Python والكيانات import المعرفة في هذا الملف في دفتر ملاحظات. للاستيراد من ملف Python، راجع تعديل التعليمات البرمجية باستخدام الملفات. أو قم بحزم الملف في مكتبة Python، وأنشئ مكتبة Azure Databricks من مكتبة Python هذه، وقم بتثبيت المكتبة في المجموعة التي تستخدمها لتشغيل دفتر الملاحظات.
• عند استخدام %run لتشغيل دفتر ملاحظات يحتوي على عناصر واجهة مستخدم، يتم تشغيل دفتر الملاحظات المحدد افتراضيا مع القيم الافتراضية لعنواة واجهة المستخدم. يمكنك أيضا تمرير القيم إلى عناصر واجهة المستخدم؛ راجع استخدام عناصر واجهة مستخدم Databricks مع ٪run.

dbutils.notebook API

الأساليب المتوفرة dbutils.notebook في واجهة برمجة التطبيقات هي run و exit. يجب أن تكون كل من المعلمات والقيم المرجعة سلاسل.

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

قم بتشغيل دفتر ملاحظات وإرجاع قيمة الخروج الخاصة به. يبدأ الأسلوب مهمة سريعة الزوال تعمل على الفور.

timeout_seconds تتحكم المعلمة في مهلة التشغيل (0 تعني عدم وجود مهلة): الاستدعاء لطرح run استثناء إذا لم ينته خلال الوقت المحدد. إذا كان Azure Databricks معطلة لأكثر من 10 دقائق، يفشل تشغيل دفتر الملاحظات بغض النظر عن timeout_seconds.

تعين المعلمة arguments قيم عنصر واجهة المستخدم لدفتر الملاحظات الهدف. على وجه التحديد، إذا كان دفتر الملاحظات الذي تقوم بتشغيله يحتوي على عنصر واجهة مستخدم يسمى A، وقمت بتمرير زوج ("A": "B") قيم المفاتيح كجزء من معلمة الوسيطات إلى run() الاستدعاء، فسيرجع "B"استرداد قيمة عنصر واجهة المستخدم A . يمكنك العثور على إرشادات إنشاء عناصر واجهة المستخدم والعمل معها في مقالة أدوات Databricks.

إشعار

• arguments تقبل المعلمة الأحرف اللاتينية فقط (مجموعة أحرف ASCII). يؤدي استخدام أحرف غير ASCII إلى إرجاع خطأ.
• يجب أن تكتمل المهام التي تم إنشاؤها dbutils.notebook باستخدام واجهة برمجة التطبيقات في 30 يوما أو أقل.

run الاستخدام

Python

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

Scala

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

run مثال

لنفترض أن لديك دفتر ملاحظات باسم workflows عنصر واجهة مستخدم يسمى foo يطبع قيمة عنصر واجهة المستخدم:

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

ينتج عن التشغيل dbutils.notebook.run("workflows", 60, {"foo": "bar"}) النتيجة التالية:

يحتوي عنصر واجهة المستخدم على القيمة التي مررتها باستخدام dbutils.notebook.run()، "bar"، بدلا من القيمة الافتراضية.

exit(value: String): void قم بإنهاء دفتر ملاحظات بقيمة. إذا قمت باستدعاء دفتر ملاحظات باستخدام run الأسلوب ، فهذه هي القيمة التي تم إرجاعها.

dbutils.notebook.exit("returnValue")

يؤدي استدعاء dbutils.notebook.exit وظيفة إلى اكتمال دفتر الملاحظات بنجاح. إذا كنت تريد أن تتسبب في فشل المهمة، فقم بطرح استثناء.

مثل

في المثال التالي، يمكنك تمرير الوسيطات إلى DataImportNotebook دفاتر ملاحظات مختلفة وتشغيلها (DataCleaningNotebook أو ErrorHandlingNotebook) استنادا إلى النتيجة من DataImportNotebook.

عند تشغيل التعليمات البرمجية، يظهر جدول يحتوي على ارتباط إلى دفتر الملاحظات قيد التشغيل:

لعرض تفاصيل التشغيل، انقر فوق الارتباط وقت البدء في الجدول. إذا اكتمل التشغيل، يمكنك أيضا عرض تفاصيل التشغيل بالنقر فوق الارتباط وقت الانتهاء.

تمرير البيانات المنظمة

يوضح هذا القسم كيفية تمرير البيانات المنظمة بين دفاتر الملاحظات.

Python

# 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
spark.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)
spark.range(5).toDF("value").write.format("parquet").save("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(spark.read.format("parquet").load(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
import json

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

Scala

// 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.format("parquet").save("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.format("parquet").load(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 */

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

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

معالجة الأخطاء

يوضح هذا القسم كيفية معالجة الأخطاء.

Python

# Errors throw 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)

Scala

// Errors throw 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)

تشغيل دفاتر ملاحظات متعددة بشكل متزامن

يمكنك تشغيل دفاتر ملاحظات متعددة في نفس الوقت باستخدام بنيات Scala وPython القياسية مثل مؤشرات الترابط (Scala، Python) و Futures (Scala، Python). توضح دفاتر الملاحظات المثال كيفية استخدام هذه البنيات.

1. قم بتنزيل دفاتر الملاحظات الأربع التالية. تتم كتابة دفاتر الملاحظات بلغة Scala.
2. استيراد دفاتر الملاحظات إلى مجلد واحد في مساحة العمل.
3. تشغيل دفتر الملاحظات تشغيل بشكل متزامن.

تشغيل دفتر الملاحظات بشكل متزامن

الحصول على دفتر الملاحظات

تشغيل في دفتر ملاحظات متوازي

الحصول على دفتر الملاحظات

اختبار دفتر الملاحظات

الحصول على دفتر الملاحظات

دفتر ملاحظات الاختبار-2

الحصول على دفتر الملاحظات