مرجع Databricks Utilities (dbutils)

هذه المقالة هي مرجع ل Databricks Utilities (dbutils). dbutils تتوفر الأدوات المساعدة في دفاتر ملاحظات Python وR وSc scala. يمكنك استخدام الأدوات المساعدة من أجل:

• العمل مع الملفات وتخزين الكائنات بكفاءة.
• العمل مع الأسرار.

كيفية: سرد الأدوات المساعدة، أوامر القائمة، عرض تعليمات الأمر

الأدوات المساعدة: البيانات، fs، الوظائف، المكتبة، دفتر الملاحظات، الأسرار، عناصر واجهة المستخدم، مكتبة واجهة برمجة تطبيقات الأدوات المساعدة

سرد الأدوات المساعدة المتوفرة

لسرد الأدوات المساعدة المتوفرة مع وصف قصير لكل أداة مساعدة، قم بتشغيل dbutils.help() ل Python أو Scala.

يسرد هذا المثال الأوامر المتوفرة ل Databricks Utilities.

Python

dbutils.help()

Scala

dbutils.help()

This module provides various utilities for users to interact with the rest of Databricks.

credentials: DatabricksCredentialUtils -> Utilities for interacting with credentials within notebooks
data: DataUtils -> Utilities for understanding and interacting with datasets (EXPERIMENTAL)
fs: DbfsUtils -> Manipulates the Databricks filesystem (DBFS) from the console
jobs: JobsUtils -> Utilities for leveraging jobs features
library: LibraryUtils -> Utilities for session isolated libraries
meta: MetaUtils -> Methods to hook into the compiler (EXPERIMENTAL)
notebook: NotebookUtils -> Utilities for the control flow of a notebook (EXPERIMENTAL)
preview: Preview -> Utilities under preview category
secrets: SecretUtils -> Provides utilities for leveraging secrets within notebooks
widgets: WidgetsUtils -> Methods to create and get bound value of input widgets inside notebooks

سرد الأوامر المتوفرة لأداة مساعدة

لسرد الأوامر المتوفرة لأداة مساعدة مع وصف قصير لكل أمر، قم بتشغيل .help() بعد الاسم البرمجي للأداة المساعدة.

يسرد هذا المثال الأوامر المتوفرة للأداة المساعدة Databricks File System (DBFS).

Python

dbutils.fs.help()

R

dbutils.fs.help()

Scala

dbutils.fs.help()

dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".

fsutils

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

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
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one

عرض التعليمات لأمر

لعرض تعليمات لأمر، قم بتشغيل .help("<command-name>") بعد اسم الأمر.

يعرض هذا المثال تعليمات لأمر نسخ DBFS.

Python

dbutils.fs.help("cp")

R

dbutils.fs.help("cp")

Scala

dbutils.fs.help("cp")

/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean

الأداة المساعدة للبيانات (dbutils.data)

الأوامر: تلخيص

تتيح لك الأداة المساعدة للبيانات فهم مجموعات البيانات وتفسيرها. لسرد الأوامر المتوفرة، قم بتشغيل dbutils.data.help().

dbutils.data provides utilities for understanding and interpreting datasets. This module is currently in preview and may be unstable. For more info about a method, use dbutils.data.help("methodName").

summarize(df: Object, precise: boolean): void -> Summarize a Spark DataFrame and visualize the statistics to get quick insights

الأمر "تلخيص" (dbutils.data.summarize)

حساب وعرض إحصائيات ملخصة ل Apache Spark DataFrame أو pandas DataFrame. يتوفر هذا الأمر ل Python وSc scala وR.

يحلل هذا الأمر المحتويات الكاملة ل DataFrame. يمكن أن يكون تشغيل هذا الأمر ل DataFrames كبيرة جدا مكلفا للغاية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.data.help("summarize").

في Databricks Runtime 10.4 LTS وما فوق، يمكنك استخدام المعلمة الإضافية precise لضبط دقة الإحصائيات المحسوبة.

• عندما precise يتم تعيين إلى خطأ (الافتراضي)، تتضمن بعض الإحصائيات التي تم إرجاعها تقريبات لتقليل وقت التشغيل.
  • قد يحتوي عدد القيم المميزة للأعمدة الفئوية على خطأ نسبي بنسبة 5٪ تقريبا للأعمدة ذات العلاقة الأساسية العالية.
  • قد يكون لعدد القيم المتكررة خطأ يصل إلى 0.01٪ عندما يكون عدد القيم المميزة أكبر من 10000.
  • قد تحتوي المدرجات التكرارية والتقديرات المئوية على خطأ يصل إلى 0.01٪ بالنسبة إلى العدد الإجمالي للصفوف.
• عندما precise يتم تعيين إلى صحيح، يتم حساب الإحصائيات بدقة أعلى. أصبحت الآن جميع الإحصائيات باستثناء المدرجات التكرارية والنسب المئوية للأعمدة الرقمية دقيقة.
  • قد تحتوي المدرجات التكرارية والتقديرات المئوية على خطأ يصل إلى 0.0001٪ بالنسبة إلى العدد الإجمالي للصفوف.

يشير تلميح الأدوات في أعلى إخراج ملخص البيانات إلى وضع التشغيل الحالي.

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

Python

df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)

R

df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)

Scala

val df = spark.read.format("csv")
  .option("inferSchema", "true")
  .option("header", "true")
  .load("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv")
dbutils.data.summarize(df)

تستخدم المرئيات رمز SI لعرض القيم الرقمية الأصغر من 0.01 أو أكبر من 10000 بشكل موجز. على سبيل المثال، سيتم عرض القيمة 1.25e-15 الرقمية ك 1.25f. استثناء واحد: يستخدم المرئيات "B" ل 1.0e9 (giga) بدلا من "G".

الأداة المساعدة لنظام الملفات (dbutils.fs)

الأوامر: cp، head، ls، mkdirs، mount، mounts، mv، put، refreshMounts، rm، unmount، updateMount

تسمح لك الأداة المساعدة لنظام الملفات بالوصول إلى ما هو DBFS؟، ما يسهل استخدام Azure Databricks كنظام ملفات.

في دفاتر الملاحظات، يمكنك استخدام %fs الأمر السحري للوصول إلى DBFS. على سبيل المثال، %fs ls /Volumes/main/default/my-volume/ هو نفس duties.fs.ls("/Volumes/main/default/my-volume/"). راجع الأوامر السحرية.

لسرد الأوامر المتوفرة، قم بتشغيل dbutils.fs.help().

dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".

fsutils

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

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
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one

أمر cp (dbutils.fs.cp)

نسخ ملف أو دليل، ربما عبر أنظمة الملفات.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("cp").

ينسخ هذا المثال الملف المسمى data.csv من /Volumes/main/default/my-volume/ إلى new-data.csv في نفس وحدة التخزين.

Python

dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

# Out[4]: True

R

dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

# [1] TRUE

Scala

dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

// res3: Boolean = true

أمر الرأس (dbutils.fs.head)

إرجاع ما يصل إلى الحد الأقصى المحدد لعدد وحدات البايت في الملف المحدد. يتم إرجاع وحدات البايت كسلسلة مشفرة UTF-8.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("head").

يعرض هذا المثال أول 25 بايت من الملف data.csv الموجود في /Volumes/main/default/my-volume/.

Python

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'

R

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

# [1] "Year,First Name,County,Se"

Scala

dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

// [Truncated to first 25 bytes]
// res4: String =
// "Year,First Name,County,Se"

الأمر ls (dbutils.fs.ls)

يسرد محتويات دليل.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("ls").

يعرض هذا المثال معلومات حول محتويات /Volumes/main/default/my-volume/. modificationTime يتوفر الحقل في Databricks Runtime 10.4 LTS وما فوق. في R، modificationTime يتم إرجاع كسلسلة.

Python

dbutils.fs.ls("/Volumes/main/default/my-volume/")

# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]

R

dbutils.fs.ls("/Volumes/main/default/my-volume/")

# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`

# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"

# [[1]]$name
# [1] "data.csv"

# [[1]]$size
# [1] 2258987

# [[1]]$isDir
# [1] FALSE

# [[1]]$isFile
# [1] TRUE

# [[1]]$modificationTime
# [1] "1711357839000"

Scala

dbutils.fs.ls("/tmp")

// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))

أمر mkdirs (dbutils.fs.mkdirs)

إنشاء الدليل المحدد إذا لم يكن موجودا. ينشئ أيضا أي دلائل أصلية ضرورية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("mkdirs").

ينشئ هذا المثال الدليل my-data داخل /Volumes/main/default/my-volume/.

Python

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# Out[15]: True

R

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# [1] TRUE

Scala

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

// res7: Boolean = true

أمر التحميل (dbutils.fs.mount)

تحميل الدليل المصدر المحدد في DBFS عند نقطة التحميل المحددة.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("mount").

Python

dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})

Scala

dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
  mountPoint = "/mnt/<mount-name>",
  extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))

للحصول على أمثلة تعليمات برمجية إضافية، راجع الاتصال ب Azure Data Lake Storage Gen2 وBlob Storage.

الأمر mounts (dbutils.fs.mounts)

يعرض معلومات حول ما يتم تحميله حاليا داخل DBFS.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("mounts").

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

للحصول على أمثلة تعليمات برمجية إضافية، راجع الاتصال ب Azure Data Lake Storage Gen2 وBlob Storage.

أمر mv (dbutils.fs.mv)

نقل ملف أو دليل، ربما عبر أنظمة الملفات. النقل هو نسخة متبوعة بحذف، حتى بالنسبة إلى التحركات داخل أنظمة الملفات.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("mv").

ينقل هذا المثال الملف rows.csv من /Volumes/main/default/my-volume/ إلى /Volumes/main/default/my-volume/my-data/.

Python

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

# Out[2]: True

R

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

# [1] TRUE

Scala

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

// res1: Boolean = true

الأمر put (dbutils.fs.put)

كتابة السلسلة المحددة إلى ملف. السلسلة مشفرة UTF-8.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("put").

يكتب هذا المثال السلسلة Hello, Databricks! إلى ملف مسمى hello.txt في /Volumes/main/default/my-volume/. إذا كان الملف موجودا، الكتابة فوقه.

Python

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

# Wrote 2258987 bytes.
# Out[6]: True

R

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)

# [1] TRUE

Scala

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", true)

// Wrote 2258987 bytes.
// res2: Boolean = true

الأمر refreshMounts (dbutils.fs.refreshMounts)

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

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

للحصول على أمثلة التعليمات البرمجية الإضافية، راجع الاتصال ب Azure Data Lake Storage Gen2 وBlob Storage.

أمر rm (dbutils.fs.rm)

إزالة ملف أو دليل، واختياريا، كافة محتوياته. إذا تم تحديد ملف، يتم تجاهل المعلمة recurse . إذا تم تحديد دليل، يحدث خطأ عند recurse تعطيله والدليل غير فارغ.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("rm").

يزيل هذا المثال الدليل /Volumes/main/default/my-volume/my-data/ بأكمله بما في ذلك محتوياته.

Python

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)

# Out[8]: True

R

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", TRUE)

# [1] TRUE

Scala

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)

// res6: Boolean = true

إلغاء تحميل الأمر (dbutils.fs.unmount)

حذف نقطة تحميل DBFS.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("unmount").

dbutils.fs.unmount("/mnt/<mount-name>")

للحصول على أمثلة تعليمات برمجية إضافية، راجع الاتصال ب Azure Data Lake Storage Gen2 وBlob Storage.

الأمر updateMount (dbutils.fs.updateMount)

على dbutils.fs.mount غرار الأمر ، ولكن يحدث نقطة تحميل موجودة بدلا من إنشاء نقطة جديدة. إرجاع خطأ إذا لم تكن نقطة التحميل موجودة.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.fs.help("updateMount").

يتوفر هذا الأمر في Databricks Runtime 10.4 LTS وما فوق.

Python

dbutils.fs.updateMount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})

Scala

dbutils.fs.updateMount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
  mountPoint = "/mnt/<mount-name>",
  extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))

الأداة المساعدة للوظائف (dbutils.jobs)

التبعيات: قيم المهام

تتيح لك الأداة المساعدة للوظائف الاستفادة من ميزات الوظائف. لعرض التعليمات لهذه الأداة المساعدة، قم بتشغيل dbutils.jobs.help().

Provides utilities for leveraging jobs features.

taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values

تماثل قيم المهام (dbutils.jobs.taskValues)

الأوامر: الحصول على، تعيين

يوفر أوامر للاستفادة من قيم المهام الوظيفية.

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

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

لعرض التعليمات لهذا الإحلال، قم بتشغيل dbutils.jobs.taskValues.help().

الحصول على الأمر (dbutils.jobs.taskValues.get)

يحصل على محتويات قيمة المهمة المحددة للمهمة المحددة في تشغيل المهمة الحالية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.jobs.taskValues.help("get").

على سبيل المثال:

dbutils.jobs.taskValues.get(taskKey    = "my-task", \
                            key        = "my-key", \
                            default    = 7, \
                            debugValue = 42)

في المثال السابق:

• taskKey هو اسم المهمة التي تعين قيمة المهمة. إذا تعذر على الأمر العثور على هذه المهمة، ValueError يتم رفع.
• key هو اسم مفتاح قيمة المهمة الذي قمت بتعيينه باستخدام أمر المجموعة (dbutils.jobs.taskValues.set). إذا تعذر على الأمر العثور على مفتاح قيمة المهمة هذه، ValueError يتم رفع (ما لم default يتم تحديد).
• default هي قيمة اختيارية يتم إرجاعها إذا key تعذر العثور عليها. default لا يمكن أن يكون None.
• debugValue هي قيمة اختيارية يتم إرجاعها إذا حاولت الحصول على قيمة المهمة من داخل دفتر ملاحظات يعمل خارج الوظيفة. يمكن أن يكون هذا مفيدا أثناء تصحيح الأخطاء عندما تريد تشغيل دفتر الملاحظات يدويا وإرجاع بعض القيمة بدلا من رفعها TypeError بشكل افتراضي. debugValue لا يمكن أن يكون None.

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

تعيين الأمر (dbutils.jobs.taskValues.set)

تعيين قيمة مهمة أو تحديثها. يمكنك إعداد ما يصل إلى 250 قيمة مهمة لتشغيل مهمة.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.jobs.taskValues.help("set").

تشمل بعض الأمثلة ما يلي:

dbutils.jobs.taskValues.set(key   = "my-key", \
                            value = 5)

dbutils.jobs.taskValues.set(key   = "my-other-key", \
                            value = "my other value")

في الأمثلة السابقة:

• key هو مفتاح قيمة المهمة. يجب أن يكون هذا المفتاح فريدا للمهمة. أي، إذا عينت مهمتان مختلفتان كل منهما قيمة مهمة بالمفتاح K، فهذه قيمتان مختلفتان للمهمة لها نفس المفتاح K.
• value هي قيمة مفتاح قيمة المهمة هذه. يجب أن يكون هذا الأمر قادرا على تمثيل القيمة داخليا بتنسيق JSON. لا يمكن أن يتجاوز حجم تمثيل JSON للقيمة 48 KiB.

إذا حاولت تعيين قيمة مهمة من داخل دفتر ملاحظات يعمل خارج مهمة، فهذا الأمر لا يفعل شيئا.

الأداة المساعدة للمكتبة (dbutils.library)

يتم إهمال معظم الأساليب في dbutils.library الوحدات الفرعية. راجع الأداة المساعدة للمكتبة (dbutils.library) (قديم).

قد تحتاج إلى إعادة تشغيل عملية Python برمجيا على Azure Databricks للتأكد من أن المكتبات المثبتة محليا أو التي تمت ترقيتها تعمل بشكل صحيح في نواة Python ل SparkSession الحالي. للقيام بذلك، قم بتشغيل dbutils.library.restartPython الأمر . راجع إعادة تشغيل عملية Python على Azure Databricks.

الأداة المساعدة لدفتر الملاحظات (dbutils.notebook)

الأوامر: إنهاء، تشغيل

تسمح لك الأداة المساعدة لدفتر الملاحظات بتسلسل دفاتر الملاحظات والتصرف بناء على نتائجها. راجع تشغيل دفتر ملاحظات Databricks من دفتر ملاحظات آخر.

لسرد الأوامر المتوفرة، قم بتشغيل 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.

أمر الخروج (dbutils.notebook.exit)

يقوم بالخروج من دفتر ملاحظات بقيمة.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.notebook.help("exit").

ينهي هذا المثال دفتر الملاحظات بالقيمة Exiting from My Other Notebook.

Python

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

R

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

Scala

dbutils.notebook.exit("Exiting from My Other Notebook")

// Notebook exited: Exiting from My Other Notebook

تشغيل الأمر (dbutils.notebook.run)

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

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.notebook.help("run").

يقوم هذا المثال بتشغيل دفتر ملاحظات باسم My Other Notebook في نفس موقع دفتر الملاحظات المتصل. ينتهي دفتر الملاحظات المسمى بخط التعليمات البرمجية dbutils.notebook.exit("Exiting from My Other Notebook"). إذا لم ينتهي تشغيل دفتر الملاحظات المسمى في غضون 60 ثانية، يتم طرح استثناء.

Python

dbutils.notebook.run("My Other Notebook", 60)

# Out[14]: 'Exiting from My Other Notebook'

Scala

dbutils.notebook.run("My Other Notebook", 60)

// res2: String = Exiting from My Other Notebook

الأداة المساعدة للبيانات السرية (dbutils.secrets)

الأوامر: get, getBytes, list, listScopes

تسمح لك الأداة المساعدة للبيانات السرية بتخزين معلومات بيانات الاعتماد الحساسة والوصول إليها دون جعلها مرئية في دفاتر الملاحظات. راجع إدارة البيانات السرية والخطوة 3: استخدام الأسرار في دفتر ملاحظات. لسرد الأوامر المتوفرة، قم بتشغيل 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

الحصول على الأمر (dbutils.secrets.get)

يحصل على تمثيل سلسلة لقيمة سرية لنطاق الأسرار المحددة والمفتاح.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.secrets.help("get").

يحصل هذا المثال على تمثيل سلسلة القيمة السرية للنطاق المسمى my-scope والمفتاح المسمى my-key.

Python

dbutils.secrets.get(scope="my-scope", key="my-key")

# Out[14]: '[REDACTED]'

R

dbutils.secrets.get(scope="my-scope", key="my-key")

# [1] "[REDACTED]"

Scala

dbutils.secrets.get(scope="my-scope", key="my-key")

// res0: String = [REDACTED]

الأمر getBytes (dbutils.secrets.getBytes)

يحصل على تمثيل وحدات البايت لقيمة سرية للنطاق والمفتاح المحددين.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.secrets.help("getBytes").

يحصل هذا المثال على تمثيل البايت للقيمة السرية (في هذا المثال، a1!b2@c3#) للنطاق المسمى my-scope والمفتاح المسمى my-key.

Python

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# Out[1]: b'a1!b2@c3#'

R

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# [1] 61 31 21 62 32 40 63 33 23

Scala

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)

أمر القائمة (dbutils.secrets.list)

يسرد بيانات التعريف للبيانات السرية ضمن النطاق المحدد.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.secrets.help("list").

يسرد هذا المثال بيانات التعريف للبيانات السرية ضمن النطاق المسمى my-scope.

Python

dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]

R

dbutils.secrets.list("my-scope")

# [[1]]
# [[1]]$key
# [1] "my-key"

Scala

dbutils.secrets.list("my-scope")

// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))

أمر listScopes (dbutils.secrets.listScopes)

يسرد النطاقات المتوفرة.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.secrets.help("listScopes").

يسرد هذا المثال النطاقات المتوفرة.

Python

dbutils.secrets.listScopes()

# Out[14]: [SecretScope(name='my-scope')]

R

dbutils.secrets.listScopes()

# [[1]]
# [[1]]$name
# [1] "my-scope"

Scala

dbutils.secrets.listScopes()

// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))

الأداة المساعدة لعناصر واجهة المستخدم (dbutils.widgets)

الأوامر: مربع التحرير والسرد، القائمة المنسدلة، الحصول على، getArgument، متعدد التحديد، إزالة، إزالة الكل، نص

تسمح لك الأداة المساعدة لعناصر واجهة المستخدم بإضفاء معلمات على دفاتر الملاحظات. راجع أدوات Databricks.

لسرد الأوامر المتوفرة، قم بتشغيل 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
getAll: map -> Retrieves a map of all widget names and their values
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

أمر مربع التحرير والسرد (dbutils.widgets.combobox)

ينشئ ويعرض عنصر واجهة مستخدم مربع تحرير وسرد بالاسم البرمجي المحدد والقيمة الافتراضية والخيارات والتسمية الاختيارية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("combobox").

ينشئ هذا المثال ويعرض عنصر واجهة مستخدم مربع تحرير وسرد بالاسم fruits_comboboxالبرمجي . يوفر الخيارات appleو bananacoconutو و dragon fruit ويتم تعيين إلى القيمة الأولية ل banana. يحتوي عنصر واجهة مستخدم مربع التحرير والسرد هذا على تسمية Fruitsمصاحبة . ينتهي هذا المثال بطباعة القيمة الأولية لعن طريق عنصر واجهة مستخدم مربع التحرير والسرد، banana.

Python

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=['apple', 'banana', 'coconut', 'dragon fruit'],
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# banana

R

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# [1] "banana"

Scala

dbutils.widgets.combobox(
  "fruits_combobox",
  "banana",
  Array("apple", "banana", "coconut", "dragon fruit"),
  "Fruits"
)

print(dbutils.widgets.get("fruits_combobox"))

// banana

SQL

CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

أمر القائمة المنسدلة (dbutils.widgets.dropdown)

ينشئ ويعرض عنصر واجهة مستخدم منسدلة بالاسم البرمجي المحدد والقيمة الافتراضية والخيارات والتسمية الاختيارية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("dropdown").

ينشئ هذا المثال ويعرض عنصر واجهة مستخدم منسدلة بالاسم toys_dropdownالبرمجي . يوفر الخيارات alphabet blocksو basketballcapeو و doll ويتم تعيين إلى القيمة الأولية ل basketball. يحتوي عنصر واجهة المستخدم المنسدلة هذا على تسمية Toysمصاحبة . ينتهي هذا المثال بطباعة القيمة الأولية لعن طريق عنصر واجهة المستخدم المنسدلة، basketball.

Python

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
  label='Toys'
)

print(dbutils.widgets.get("toys_dropdown"))

# basketball

R

dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
  label='Toys'
)

print(dbutils.widgets.get("toys_dropdown"))

# [1] "basketball"

Scala

dbutils.widgets.dropdown(
  "toys_dropdown",
  "basketball",
  Array("alphabet blocks", "basketball", "cape", "doll"),
  "Toys"
)

print(dbutils.widgets.get("toys_dropdown"))

// basketball

SQL

CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))

SELECT :toys_dropdown

-- basketball

الحصول على الأمر (dbutils.widgets.get)

يحصل على القيمة الحالية لعن الأداة بالاسم البرمجي المحدد. يمكن أن يكون هذا الاسم البرمجي إما:

• اسم عنصر واجهة مستخدم مخصص في دفتر الملاحظات، على سبيل المثال، fruits_combobox أو toys_dropdown.
• اسم معلمة مخصصة تم تمريرها إلى دفتر الملاحظات كجزء من مهمة دفتر ملاحظات، على سبيل المثال name أو age. لمزيد من المعلومات، راجع تغطية المعلمات لمهام دفتر الملاحظات في واجهة مستخدم الوظائف أو notebook_params الحقل في عملية تشغيل مهمة جديدة (POST /jobs/run-now) في واجهة برمجة تطبيقات الوظائف.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("get").

يحصل هذا المثال على قيمة عنصر واجهة المستخدم الذي يحتوي على الاسم fruits_comboboxالبرمجي .

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

SQL

SELECT :fruits_combobox

-- banana

يحصل هذا المثال على قيمة معلمة مهمة دفتر الملاحظات التي تحتوي على الاسم ageالبرمجي . تم تعيين هذه المعلمة إلى 35 عند تشغيل مهمة دفتر الملاحظات ذات الصلة.

Python

dbutils.widgets.get('age')

# 35

R

dbutils.widgets.get('age')

# [1] "35"

Scala

dbutils.widgets.get("age")

// res6: String = 35

SQL

SELECT :age

-- 35

الأمر getAll (dbutils.widgets.getAll)

الحصول على تعيين لكافة أسماء وقيم عناصر واجهة المستخدم الحالية. يمكن أن يكون هذا مفيدا بشكل خاص لتمرير قيم عنصر واجهة المستخدم بسرعة إلى spark.sql() استعلام.

يتوفر هذا الأمر في Databricks Runtime 13.3 LTS وما فوق. وهو متاح فقط ل Python وSc scala.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("getAll").

يحصل هذا المثال على خريطة قيم عنصر واجهة المستخدم ويمررها كوسيطات معلمة في استعلام Spark SQL.

Python

df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()

# Query output

Scala

val df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()

// res6: Query output

الأمر getArgument (dbutils.widgets.getArgument)

يحصل على القيمة الحالية لعن الأداة بالاسم البرمجي المحدد. إذا لم يكن عنصر واجهة المستخدم موجودا، يمكن إرجاع رسالة اختيارية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("getArgument").

يحصل هذا المثال على قيمة عنصر واجهة المستخدم الذي يحتوي على الاسم fruits_comboboxالبرمجي . إذا لم يكن عنصر واجهة المستخدم هذا موجودا، يتم إرجاع الرسالة Error: Cannot find fruits combobox .

Python

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'

R

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# [1] "banana"

Scala

dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")

// command-1234567890123456:1: warning: method getArgument in trait WidgetsUtils is deprecated: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
// dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
//                 ^
// res7: String = banana

الأمر متعدد التحديد (dbutils.widgets.multiselect)

إنشاء وعرض عنصر واجهة مستخدم متعدد التحديد بالاسم البرمجي المحدد والقيمة الافتراضية والخيارات والتسمية الاختيارية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("multiselect").

ينشئ هذا المثال ويعرض عنصر واجهة مستخدم متعدد التحديد بالاسم days_multiselectالبرمجي . يوفر الخيارات Monday من خلال Sunday ويتم تعيينه إلى القيمة الأولية ل Tuesday. يحتوي عنصر واجهة المستخدم متعدد التحديد هذا على تسمية Days of the Weekمصاحبة . ينتهي هذا المثال بطباعة القيمة الأولية لعن طريق عنصر واجهة المستخدم متعدد التحديد، Tuesday.

Python

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'],
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# Tuesday

R

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'),
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# [1] "Tuesday"

Scala

dbutils.widgets.multiselect(
  "days_multiselect",
  "Tuesday",
  Array("Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"),
  "Days of the Week"
)

print(dbutils.widgets.get("days_multiselect"))

// Tuesday

SQL

CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))

SELECT :days_multiselect

-- Tuesday

إزالة الأمر (dbutils.widgets.remove)

يزيل عنصر واجهة المستخدم بالاسم البرمجي المحدد.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("remove").

يزيل هذا المثال عنصر واجهة المستخدم بالاسم fruits_comboboxالبرمجي .

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

الأمر removeAll (dbutils.widgets.removeAll)

إزالة جميع عناصر واجهة المستخدم من دفتر الملاحظات.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("removeAll").

يزيل هذا المثال جميع عناصر واجهة المستخدم من دفتر الملاحظات.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

الأمر النصي (dbutils.widgets.text)

إنشاء وعرض عنصر واجهة مستخدم نصي بالاسم البرمجي المحدد والقيمة الافتراضية والتسمية الاختيارية.

لعرض التعليمات لهذا الأمر، قم بتشغيل dbutils.widgets.help("text").

ينشئ هذا المثال ويعرض عنصر واجهة مستخدم نصيا بالاسم your_name_textالبرمجي . يتم تعيينه إلى القيمة الأولية ل Enter your name. يحتوي عنصر واجهة مستخدم النص هذا على تسمية Your nameمرفقة . ينتهي هذا المثال بطباعة القيمة الأولية لعنوة النص، Enter your name.

Python

dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

print(dbutils.widgets.get("your_name_text"))

# Enter your name

R

dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

print(dbutils.widgets.get("your_name_text"))

# [1] "Enter your name"

Scala

dbutils.widgets.text(
  "your_name_text",
  "Enter your name",
  "Your name"
)

print(dbutils.widgets.get("your_name_text"))

// Enter your name

SQL

CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

مكتبة واجهة برمجة تطبيقات Databricks Utilities

لتسريع تطوير التطبيقات، قد يكون من المفيد تجميع التطبيقات وبنائها واختبارها قبل نشرها كمهام إنتاج. لتمكينك من التحويل البرمجي مقابل Databricks Utilities، يوفر Databricks المكتبة dbutils-api . يمكنك تنزيل dbutils-api المكتبة من صفحة ويب DBUtils API على موقع Maven Repository على الويب أو تضمين المكتبة عن طريق إضافة تبعية إلى ملف الإنشاء الخاص بك:

• SBT

  libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"
  

• Maven

  <dependency>
      <groupId>com.databricks</groupId>
      <artifactId>dbutils-api_TARGET</artifactId>
      <version>VERSION</version>
  </dependency>
  

• Gradle

  compile 'com.databricks:dbutils-api_TARGET:VERSION'
  

استبدل TARGET بالهدف المطلوب (على سبيل المثال، 2.12) والإصدار VERSION المطلوب (على سبيل المثال، 0.0.5). للحصول على قائمة بالأهداف والإصدارات المتوفرة، راجع صفحة الويب DBUtils API على موقع Maven Repository على الويب.

بمجرد إنشاء التطبيق الخاص بك مقابل هذه المكتبة، يمكنك نشر التطبيق.

القيود

يمكن أن يؤدي الاتصال dbutils داخل المنفذين إلى نتائج غير متوقعة أو قد يؤدي إلى أخطاء.

إذا كنت بحاجة إلى تشغيل عمليات نظام الملفات على المنفذين باستخدام dbutils، فراجع السرد المتوازي وحذف الأساليب باستخدام Spark في كيفية سرد الملفات وحذفها بشكل أسرع في Databricks.

للحصول على معلومات حول المنفذين، راجع نظرة عامة على وضع نظام المجموعة على موقع Apache Spark على الويب.