واجهة برمجة تطبيقات تنفيذ العبارة: تشغيل SQL على المستودعات
هام
للوصول إلى واجهات برمجة تطبيقات Databricks REST، يجب عليك المصادقة.
يوضح لك هذا البرنامج التعليمي كيفية استخدام Databricks SQL Statement Execution API 2.0 لتشغيل عبارات SQL من مستودعات Databricks SQL.
لعرض مرجع Databricks SQL Statement Execution API 2.0، راجع تنفيذ العبارة.
قبل البدء
قبل البدء في هذا البرنامج التعليمي، تأكد من أن لديك:
إما Databricks CLI الإصدار 0.205 أو أعلى أو
curl، كما يلي:Databricks CLI هو أداة سطر أوامر لإرسال طلبات واجهة برمجة تطبيقات REST ل Databricks واستقبالها. إذا كنت تستخدم Databricks CLI الإصدار 0.205 أو أعلى، فيجب تكوينه للمصادقة مع مساحة عمل Azure Databricks. راجع تثبيت أو تحديث Databricks CLI والمصادقة ل Databricks CLI.
على سبيل المثال، للمصادقة باستخدام مصادقة رمز الوصول الشخصي Databricks، أنشئ رمز وصول شخصي كما يلي:
- في مساحة عمل Azure Databricks، انقر فوق اسم مستخدم Azure Databricks في الشريط العلوي، ثم حدد الإعدادات من القائمة المنسدلة.
- انقر فوق المطور.
- إلى جانب رموز الوصول المميزة، انقر فوق إدارة.
- النقر على Generate new token.
- (اختياري) أدخل تعليقا يساعدك على تحديد هذا الرمز المميز في المستقبل، وتغيير العمر الافتراضي للرمز المميز وهو 90 يوما. لإنشاء رمز مميز بدون مدة بقاء (غير مستحسن)، اترك مربع مدة البقاء (أيام) فارغا (فارغ).
- انقر فوق "Generate".
- انسخ الرمز المميز المعروض إلى موقع آمن، ثم انقر فوق تم.
إشعار
تأكد من حفظ الرمز المميز المنسخ في موقع آمن. لا تشارك الرمز المميز المنسخ مع الآخرين. إذا فقدت الرمز المميز المنسخ، فلا يمكنك إعادة إنشاء نفس الرمز المميز بالضبط. بدلا من ذلك، يجب تكرار هذا الإجراء لإنشاء رمز مميز جديد. إذا فقدت الرمز المميز الذي تم نسخه، أو كنت تعتقد أنه تم اختراق الرمز المميز، فإن Databricks يوصي بشدة بحذف هذا الرمز المميز على الفور من مساحة العمل الخاصة بك عن طريق النقر فوق أيقونة سلة المهملات (إبطال) بجوار الرمز المميز في صفحة رموز Access المميزة .
إذا لم تتمكن من إنشاء الرموز المميزة أو استخدامها في مساحة العمل الخاصة بك، فقد يرجع ذلك إلى قيام مسؤول مساحة العمل بتعطيل الرموز المميزة أو عدم منحك الإذن لإنشاء الرموز المميزة أو استخدامها. راجع مسؤول مساحة العمل أو المواضيع التالية:
ثم لاستخدام Databricks CLI لإنشاء ملف تعريف تكوين Azure Databricks للرمز المميز للوصول الشخصي، قم بما يلي:
إشعار
يستخدم الإجراء التالي Databricks CLI لإنشاء ملف تعريف تكوين Azure Databricks باسم
DEFAULT. إذا كان لديكDEFAULTملف تعريف تكوين بالفعل، فإن هذا الإجراء يحل محل ملف تعريف التكوين الحاليDEFAULT.للتحقق مما إذا كان لديك
DEFAULTملف تعريف تكوين بالفعل، ولعرض إعدادات ملف التعريف هذا إذا كان موجودا، استخدم Databricks CLI لتشغيل الأمرdatabricks auth env --profile DEFAULT.لإنشاء ملف تعريف تكوين باسم آخر غير
DEFAULT، استبدلDEFAULTالجزء من--profile DEFAULTفي الأمر التاليdatabricks configureباسم مختلف لملف تعريف التكوين.استخدم Databricks CLI لإنشاء ملف تعريف تكوين Azure Databricks المسمى
DEFAULTالذي يستخدم مصادقة رمز الوصول الشخصي Azure Databricks. للقيام بذلك، قم بتشغيل الأمر التالي:databricks configure --profile DEFAULTلمضيف Databricks المطالبة، أدخل عنوان URL الخاص بك في Azure Databricks لكل مساحة عمل، على سبيل المثال
https://adb-1234567890123456.7.azuredatabricks.net.بالنسبة إلى الرمز المميز للوصول الشخصي الموجه، أدخل رمز الوصول الشخصي Azure Databricks لمساحة العمل الخاصة بك.
في أمثلة Databricks CLI لهذا البرنامج التعليمي، لاحظ ما يلي:
- يفترض هذا البرنامج التعليمي أن لديك متغير
DATABRICKS_SQL_WAREHOUSE_IDبيئة على جهاز التطوير المحلي الخاص بك. يمثل متغير البيئة هذا معرف مستودع Databricks SQL الخاص بك. هذا المعرف هو سلسلة الأحرف والأرقام التالية/sql/1.0/warehouses/في حقل مسار HTTP لمستودعك. لمعرفة كيفية الحصول على قيمة مسار HTTP لمستودعك، راجع الحصول على تفاصيل الاتصال لمورد حساب Azure Databricks. - إذا كنت تستخدم Windows Command shell بدلا من shell أمر ل Unix أو Linux أو macOS، فاستبدل
\ب^، واستبدل${...}ب%...%. - إذا كنت تستخدم Windows Command shell بدلا من shell الأوامر ل Unix أو Linux أو macOS، في إعلانات مستند JSON، استبدل الفتح والإغلاق
'ب"، واستبدل inner"ب\".
curl هي أداة سطر أوامر لإرسال طلبات واجهة برمجة تطبيقات REST والاستجابات وتلقيها. راجع أيضا تثبيت curl. أو قم بتكييف أمثلة هذا البرنامج التعليمي
curlللاستخدام مع أدوات مماثلة مثل HTTPie.في أمثلة
curlهذا البرنامج التعليمي، لاحظ ما يلي:- بدلا من
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"، يمكنك استخدام ملف .netrc . إذا كنت تستخدم ملفا.netrc، فاستبدل--header "Authorization: Bearer ${DATABRICKS_TOKEN}"ب--netrc. - إذا كنت تستخدم Windows Command shell بدلا من shell أمر ل Unix أو Linux أو macOS، فاستبدل
\ب^، واستبدل${...}ب%...%. - إذا كنت تستخدم Windows Command shell بدلا من shell الأوامر ل Unix أو Linux أو macOS، في إعلانات مستند JSON، استبدل الفتح والإغلاق
'ب"، واستبدل inner"ب\".
أيضا، بالنسبة لأمثلة هذا البرنامج التعليمي
curl، يفترض هذا البرنامج التعليمي أن لديك متغيرات البيئة التالية على جهاز التطوير المحلي الخاص بك:DATABRICKS_HOST، يمثل اسم مثيل مساحة العمل، على سبيل المثالadb-1234567890123456.7.azuredatabricks.net، لمساحة عمل Azure Databricks.DATABRICKS_TOKEN، يمثل رمز وصول شخصي إلى Azure Databricks لمستخدم مساحة عمل Azure Databricks.DATABRICKS_SQL_WAREHOUSE_ID، يمثل معرف مستودع Databricks SQL الخاص بك. هذا المعرف هو سلسلة الأحرف والأرقام التالية/sql/1.0/warehouses/في حقل مسار HTTP لمستودعك. لمعرفة كيفية الحصول على قيمة مسار HTTP لمستودعك، راجع الحصول على تفاصيل الاتصال لمورد حساب Azure Databricks.
إشعار
كأفضل ممارسة أمان، عند المصادقة باستخدام الأدوات والأنظمة والبرامج النصية والتطبيقات التلقائية، توصي Databricks باستخدام رموز الوصول الشخصية التي تنتمي إلى كيانات الخدمة بدلا من مستخدمي مساحة العمل. لإنشاء رموز مميزة لكيانات الخدمة، راجع إدارة الرموز المميزة لكيان الخدمة.
لإنشاء رمز مميز للوصول الشخصي إلى Azure Databricks، قم بما يلي:
- في مساحة عمل Azure Databricks، انقر فوق اسم مستخدم Azure Databricks في الشريط العلوي، ثم حدد الإعدادات من القائمة المنسدلة.
- انقر فوق المطور.
- إلى جانب رموز الوصول المميزة، انقر فوق إدارة.
- النقر على Generate new token.
- (اختياري) أدخل تعليقا يساعدك على تحديد هذا الرمز المميز في المستقبل، وتغيير العمر الافتراضي للرمز المميز وهو 90 يوما. لإنشاء رمز مميز بدون مدة بقاء (غير مستحسن)، اترك مربع مدة البقاء (أيام) فارغا (فارغ).
- انقر فوق "Generate".
- انسخ الرمز المميز المعروض إلى موقع آمن، ثم انقر فوق تم.
إشعار
تأكد من حفظ الرمز المميز المنسخ في موقع آمن. لا تشارك الرمز المميز المنسخ مع الآخرين. إذا فقدت الرمز المميز المنسخ، فلا يمكنك إعادة إنشاء نفس الرمز المميز بالضبط. بدلا من ذلك، يجب تكرار هذا الإجراء لإنشاء رمز مميز جديد. إذا فقدت الرمز المميز الذي تم نسخه، أو كنت تعتقد أنه تم اختراق الرمز المميز، فإن Databricks يوصي بشدة بحذف هذا الرمز المميز على الفور من مساحة العمل الخاصة بك عن طريق النقر فوق أيقونة سلة المهملات (إبطال) بجوار الرمز المميز في صفحة رموز Access المميزة .
إذا لم تتمكن من إنشاء الرموز المميزة أو استخدامها في مساحة العمل الخاصة بك، فقد يرجع ذلك إلى قيام مسؤول مساحة العمل بتعطيل الرموز المميزة أو عدم منحك الإذن لإنشاء الرموز المميزة أو استخدامها. راجع مسؤول مساحة العمل أو المواضيع التالية:
تحذير
تثبط Databricks بشدة معلومات الترميز المضمن في البرامج النصية الخاصة بك، حيث يمكن كشف هذه المعلومات الحساسة في نص عادي من خلال أنظمة التحكم في الإصدار. توصي Databricks باستخدام نهج مثل متغيرات البيئة التي قمت بتعيينها على جهاز التطوير بدلا من ذلك. تساعد إزالة هذه المعلومات ذات التعليمات البرمجية المضمنة من البرامج النصية على جعل هذه البرامج النصية أكثر قابلية للنقل أيضا.
- بدلا من
يفترض هذا البرنامج التعليمي أن لديك أيضا jq، وهو معالج سطر أوامر للاستعلام عن حمولات استجابة JSON، والتي ترجعها لك واجهة برمجة تطبيقات تنفيذ عبارة Databricks SQL بعد كل استدعاء تجريه إلى Databricks SQL Statement Execution API. راجع تنزيل jq.
يجب أن يكون لديك جدول واحد على الأقل يمكنك تنفيذ عبارات SQL ضده. يستند هذا البرنامج التعليمي إلى
lineitemالجدول فيtpchالمخطط (المعروف أيضا باسم قاعدة البيانات) داخل الكتالوجsamples. إذا لم يكن لديك حق الوصول إلى هذا الكتالوج أو المخطط أو الجدول من مساحة العمل الخاصة بك، فاستبدلها خلال هذا البرنامج التعليمي بالبرنامج التعليمي الخاص بك.
الخطوة 1: تنفيذ عبارة SQL وحفظ نتيجة البيانات ك JSON
قم بتشغيل الأمر التالي، الذي يقوم بالتالي:
- يستخدم مستودع SQL المحدد، جنبا إلى جنب مع الرمز المميز المحدد إذا كنت تستخدم
curl، للاستعلام عن ثلاثة أعمدة من أول صفين منlineitemالجدول فيtcphالمخطط داخل الكتالوجsamples. - حفظ حمولة الاستجابة بتنسيق JSON في ملف مسمى
sql-execution-response.jsonداخل دليل العمل الحالي. - طباعة محتويات
sql-execution-response.jsonالملف. - تعيين متغير بيئة محلي يسمى
SQL_STATEMENT_ID. يحتوي هذا المتغير على معرف عبارة SQL المقابلة. يمكنك استخدام معرف عبارة SQL هذا للحصول على معلومات حول هذه العبارة لاحقا حسب الحاجة، وهو ما يظهر في الخطوة 2. يمكنك أيضا عرض عبارة SQL هذه والحصول على معرف العبارة الخاص بها من قسم محفوظات الاستعلام في وحدة تحكم Databricks SQL، أو عن طريق استدعاء واجهة برمجة تطبيقات محفوظات الاستعلام. - تعيين متغير بيئة محلي إضافي يسمى
NEXT_CHUNK_EXTERNAL_LINKيحتوي على جزء عنوان URL لواجهة برمجة التطبيقات للحصول على المجموعة التالية من بيانات JSON. إذا كانت بيانات الاستجابة كبيرة جدا، فإن واجهة برمجة تطبيقات تنفيذ عبارة Databricks SQL توفر الاستجابة في مجموعات. يمكنك استخدام جزء عنوان URL لواجهة برمجة التطبيقات هذا للحصول على المجموعة التالية من البيانات، والتي يتم توضيحها في الخطوة 2. إذا لم تكن هناك مجموعة تالية، تعيين متغير البيئة هذا إلىnull. - طباعة قيم
SQL_STATEMENT_IDمتغيرات البيئة وNEXT_CHUNK_INTERNAL_LINK.
Databricks CLI
databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
في الطلب السابق:
تتكون الاستعلامات ذات المعلمات من اسم كل معلمة استعلام يسبقها نقطتان (على سبيل المثال،
:extended_price) مع مطابقةnameوعنصرvalueفيparametersالصفيف. يمكن أيضا تحديد اختياريtype، مع القيمة الافتراضيةSTRINGإذا لم يتم تحديدها.تحذير
توصي Databricks بشدة باستخدام المعلمات كأفضل ممارسة لعبارات SQL الخاصة بك.
إذا كنت تستخدم Databricks SQL Statement Execution API مع تطبيق يقوم بإنشاء SQL ديناميكيا، يمكن أن يؤدي ذلك إلى هجمات حقن SQL. على سبيل المثال، إذا قمت بإنشاء تعليمات SQL البرمجية استنادا إلى تحديدات المستخدم في واجهة مستخدم ولم تتخذ التدابير المناسبة، يمكن للمهاجم إدخال تعليمات SQL البرمجية الضارة لتغيير منطق الاستعلام الأولي، وبالتالي قراءة البيانات الحساسة أو تغييرها أو حذفها.
تساعد الاستعلامات ذات المعلمات في الحماية من هجمات حقن SQL من خلال معالجة وسيطات الإدخال بشكل منفصل عن بقية التعليمات البرمجية ل SQL وتفسير هذه الوسيطات كقيم حرفية. تساعد المعلمات أيضا في إعادة استخدام التعليمات البرمجية.
بشكل افتراضي، تكون أي بيانات تم إرجاعها بتنسيق صفيف JSON، والموقع الافتراضي لأي من نتائج بيانات عبارة SQL داخل حمولة الاستجابة. لجعل هذا السلوك صريحا، أضف
"format":"JSON_ARRAY","disposition":"INLINE"إلى حمولة الطلب. إذا حاولت إرجاع نتائج بيانات أكبر من 25 ميجابايت في حمولة الاستجابة، يتم إرجاع حالة فشل ويتم إلغاء عبارة SQL. للحصول على نتائج بيانات أكبر من 25 ميجابايت، يمكنك استخدام ارتباطات خارجية بدلا من محاولة إرجاعها في حمولة الاستجابة، والتي تظهر في الخطوة 3.يخزن الأمر محتويات حمولة الاستجابة إلى ملف محلي. تخزين البيانات المحلية غير مدعوم من قبل واجهة برمجة تطبيقات تنفيذ عبارة Databricks SQL مباشرة.
بشكل افتراضي، بعد 10 ثوان، إذا لم تنتهي عبارة SQL من التنفيذ من خلال المستودع، فإن Databricks SQL Statement Execution API ترجع فقط معرف عبارة SQL وحالته الحالية، بدلا من نتيجة العبارة. لتغيير هذا السلوك، أضف
"wait_timeout"إلى الطلب واضبطه على"<x>s"، حيث<x>يمكن أن يكون بين5والثوان50ضمنا، على سبيل المثال"50s". لإرجاع معرف عبارة SQL وحالته الحالية على الفور، قم بتعيينwait_timeoutإلى0s.بشكل افتراضي، يستمر تشغيل عبارة SQL إذا تم الوصول إلى فترة المهلة. لإلغاء عبارة SQL إذا تم الوصول إلى فترة المهلة بدلا من ذلك، أضف
"on_wait_timeout":"CANCEL"إلى حمولة الطلب.للحد من عدد وحدات البايت التي تم إرجاعها، أضف
"byte_limit"إلى الطلب وقم بتعيينه إلى عدد وحدات البايت، على سبيل المثال1000.للحد من عدد الصفوف التي تم إرجاعها، بدلا من إضافة
LIMITعبارة إلىstatement، يمكنك إضافة"row_limit"إلى الطلب وتعيينه إلى عدد الصفوف، على سبيل المثال"statement":"SELECT * FROM lineitem","row_limit":2.إذا كانت النتيجة أكبر من المحدد
byte_limitأوrow_limit،truncatedيتم تعيين الحقل إلىtrueفي حمولة الاستجابة.
إذا كانت نتيجة العبارة متوفرة قبل انتهاء مهلة الانتظار، تكون الاستجابة كما يلي:
{
"manifest": {
"chunks": [
{
"chunk_index": 0,
"row_count": 2,
"row_offset": 0
}
],
"format": "JSON_ARRAY",
"schema": {
"column_count": 3,
"columns": [
{
"name": "l_orderkey",
"position": 0,
"type_name": "LONG",
"type_text": "BIGINT"
},
{
"name": "l_extendedprice",
"position": 1,
"type_name": "DECIMAL",
"type_precision": 18,
"type_scale": 2,
"type_text": "DECIMAL(18,2)"
},
{
"name": "l_shipdate",
"position": 2,
"type_name": "DATE",
"type_text": "DATE"
}
]
},
"total_chunk_count": 1,
"total_row_count": 2,
"truncated": false
},
"result": {
"chunk_index": 0,
"data_array": [
[
"2",
"71433.16",
"1997-01-28"
],
[
"7",
"86152.02",
"1996-01-15"
]
],
"row_count": 2,
"row_offset": 0
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
إذا انتهت مهلة الانتظار قبل توفر نتيجة العبارة، فستبدو الاستجابة كما يلي بدلا من ذلك:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
إذا كانت بيانات نتيجة العبارة كبيرة جدا (على سبيل المثال في هذه الحالة، عن طريق تشغيل SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000)، يتم تقسيم بيانات النتيجة وتبدو مثل هذا بدلا من ذلك. لاحظ أن "...": "..." يشير إلى النتائج المحذفة هنا للإيجاز:
{
"manifest": {
"chunks": [
{
"chunk_index": 0,
"row_count": 188416,
"row_offset": 0
},
{
"chunk_index": 1,
"row_count": 111584,
"row_offset": 188416
}
],
"format":"JSON_ARRAY",
"schema": {
"column_count":3,
"columns": [
{
"...": "..."
}
]
},
"total_chunk_count": 2,
"total_row_count": 300000,
"truncated": false
},
"result": {
"chunk_index": 0,
"data_array": [
[
"2",
"71433.16",
"1997-01-28"
],
[
"..."
]
],
"next_chunk_index": 1,
"next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
"row_count": 188416,
"row_offset": 0
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
الخطوة 2: الحصول على حالة التنفيذ الحالية للبيانات ونتيجة البيانات ك JSON
يمكنك استخدام معرف عبارة SQL للحصول على حالة التنفيذ الحالية لتلك العبارة، وإذا نجح التنفيذ، نتيجة تلك العبارة. إذا نسيت معرف العبارة، يمكنك الحصول عليه من قسم محفوظات الاستعلام في وحدة تحكم Databricks SQL، أو عن طريق استدعاء واجهة برمجة تطبيقات محفوظات الاستعلام. على سبيل المثال، يمكنك الاستمرار في التحقق من هذا الأمر، والتحقق في كل مرة لمعرفة ما إذا كان التنفيذ قد نجح.
للحصول على حالة التنفيذ الحالية لبيان SQL، وإذا نجح التنفيذ، فإن نتيجة هذه العبارة وجزء عنوان URL لواجهة برمجة التطبيقات للحصول على أي مجموعة تالية من بيانات JSON، قم بتشغيل الأمر التالي. يفترض هذا الأمر أن لديك متغير بيئة على جهاز التطوير المحلي المسمى SQL_STATEMENT_ID، والذي تم تعيينه إلى قيمة معرف عبارة SQL من الخطوة السابقة. بالطبع، يمكنك استبدال ${SQL_STATEMENT_ID} في الأمر التالي بمعرف التعليمات البرمجية المضمنة لبيان SQL.
Databricks CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
NEXT_CHUNK_INTERNAL_LINK إذا تم تعيين إلى قيمة غيرnull، يمكنك استخدامها للحصول على المجموعة التالية من البيانات، وهكذا، على سبيل المثال باستخدام الأمر التالي:
Databricks CLI
databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
يمكنك الاستمرار في تشغيل الأمر السابق، مرارا وتكرارا، للحصول على المجموعة التالية، وما إلى ذلك. لاحظ أنه بمجرد إحضار المجموعة الأخيرة، يتم إغلاق عبارة SQL. بعد هذا الإغلاق، لا يمكنك استخدام معرف هذه العبارة للحصول على حالته الحالية أو لجلب أي أجزاء أخرى.
الخطوة 3: إحضار نتائج كبيرة باستخدام ارتباطات خارجية
يوضح هذا القسم تكوينا اختياريا يستخدم EXTERNAL_LINKS الترتيب لاسترداد مجموعات البيانات الكبيرة. يقع الموقع الافتراضي (الترتيب) لبيانات نتيجة عبارة SQL ضمن حمولة الاستجابة، ولكن تقتصر هذه النتائج على 25 ميبي بايت. عن طريق تعيين disposition إلى EXTERNAL_LINKS، تحتوي الاستجابة على عناوين URL التي يمكنك استخدامها لجلب مجموعات من بيانات النتائج باستخدام HTTP القياسي. تشير عناوين URL إلى DBFS الداخلي لمساحة العمل، حيث يتم تخزين مجموعات النتائج مؤقتا.
تحذير
توصي Databricks بشدة بحماية عناوين URL والرموز المميزة التي يتم إرجاعها بواسطة EXTERNAL_LINKS الترتيب.
عند استخدام EXTERNAL_LINKS الترتيب، يتم إنشاء عنوان URL لتوقيع الوصول المشترك (SAS)، والذي يمكن استخدامه لتنزيل النتائج مباشرة من تخزين Azure. نظرا لأن رمز SAS المميز قصير الأجل مضمن في عنوان URL SAS هذا، يجب عليك حماية كل من عنوان URL SAS ورمز SAS المميز.
نظرا لأن عناوين URL ل SAS تم إنشاؤها بالفعل باستخدام رموز SAS المميزة المؤقتة المضمنة، يجب عدم تعيين Authorization عنوان في طلبات التنزيل.
EXTERNAL_LINKS يمكن تعطيل الترتيب عند الطلب عن طريق إنشاء حالة دعم.
راجع أيضا أفضل ممارسات الأمان.
إشعار
لا يمكن تغيير تنسيق إخراج حمولة الاستجابة وسلوكها، بمجرد تعيينها لمعرف عبارة SQL معين.
في هذا الوضع، تمكنك واجهة برمجة التطبيقات من تخزين بيانات النتائج بتنسيق JSON (JSON)، أو تنسيق CSV (CSV)، أو تنسيق سهم Apache (ARROW_STREAM)، التي يجب الاستعلام عنها بشكل منفصل باستخدام HTTP. أيضا، عند استخدام هذا الوضع، لا يمكن تضمين بيانات النتيجة داخل حمولة الاستجابة.
يوضح الأمر التالي استخدام EXTERNAL_LINKS وتنسيق سهم Apache. استخدم هذا النمط بدلا من الاستعلام المماثل الموضح في الخطوة 1:
Databricks CLI
databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
الاستجابة هي كما يلي:
{
"manifest": {
"chunks": [
{
"byte_count": 2843848,
"chunk_index": 0,
"row_count": 100000,
"row_offset": 0
}
],
"format": "ARROW_STREAM",
"schema": {
"column_count": 3,
"columns": [
{
"name": "l_orderkey",
"position": 0,
"type_name": "LONG",
"type_text": "BIGINT"
},
{
"name": "l_extendedprice",
"position": 1,
"type_name": "DECIMAL",
"type_precision": 18,
"type_scale": 2,
"type_text": "DECIMAL(18,2)"
},
{
"name": "l_shipdate",
"position": 2,
"type_name": "DATE",
"type_text": "DATE"
}
]
},
"total_byte_count": 2843848,
"total_chunk_count": 1,
"total_row_count": 100000,
"truncated": false
},
"result": {
"external_links": [
{
"byte_count": 2843848,
"chunk_index": 0,
"expiration": "<url-expiration-timestamp>",
"external_link": "<url-to-data-stored-externally>",
"row_count": 100000,
"row_offset": 0
}
]
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
إذا انتهت مهلة الطلب، تبدو الاستجابة كما يلي بدلا من ذلك:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
للحصول على حالة التنفيذ الحالية لتلك العبارة، وإذا نجح التنفيذ، فقم بتشغيل الأمر التالي:
Databricks CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
إذا كانت الاستجابة كبيرة بما يكفي (على سبيل المثال في هذه الحالة، عن طريق التشغيل SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem بدون حد صف)، سيكون للاستجابة مجموعات متعددة، كما في المثال التالي أدناه. لاحظ أن "...": "..." يشير إلى النتائج المحذفة هنا للإيجاز:
{
"manifest": {
"chunks": [
{
"byte_count": 11469280,
"chunk_index": 0,
"row_count": 403354,
"row_offset": 0
},
{
"byte_count": 6282464,
"chunk_index": 1,
"row_count": 220939,
"row_offset": 403354
},
{
"...": "..."
},
{
"byte_count": 6322880,
"chunk_index": 10,
"row_count": 222355,
"row_offset": 3113156
}
],
"format":"ARROW_STREAM",
"schema": {
"column_count": 3,
"columns": [
{
"...": "..."
}
]
},
"total_byte_count": 94845304,
"total_chunk_count": 11,
"total_row_count": 3335511,
"truncated": false
},
"result": {
"external_links": [
{
"byte_count": 11469280,
"chunk_index": 0,
"expiration": "<url-expiration-timestamp>",
"external_link": "<url-to-data-stored-externally>",
"next_chunk_index": 1,
"next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
"row_count": 403354,
"row_offset": 0
}
]
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
لتنزيل نتائج المحتوى المخزن، يمكنك تشغيل الأمر التالي curl ، باستخدام عنوان URL في external_link الكائن وتحديد المكان الذي تريد تنزيل الملف فيه. لا تقم بتضمين رمز Azure Databricks المميز في هذا الأمر:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
لتنزيل جزء معين من نتائج المحتوى المتدفق، يمكنك استخدام أحد الإجراءات التالية:
next_chunk_indexالقيمة من حمولة الاستجابة للتقسيم التالي (إذا كانت هناك مجموعة تالية).- أحد فهارس المجموعة من بيان حمولة الاستجابة لأي مجموعة متاحة إذا كانت هناك مجموعات متعددة.
على سبيل المثال، للحصول على المجموعة مع من chunk_index 10 من الاستجابة السابقة، قم بتشغيل الأمر التالي:
Databricks CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
إشعار
يؤدي تشغيل الأمر السابق إلى إرجاع عنوان URL SAS جديد.
لتنزيل المجموعة المخزنة، استخدم عنوان URL في external_link الكائن .
لمزيد من المعلومات حول تنسيق سهم Apache، راجع:
الخطوة 4: إلغاء تنفيذ عبارة SQL
إذا كنت بحاجة إلى إلغاء عبارة SQL التي لم تنجح بعد، فقم بتشغيل الأمر التالي:
Databricks CLI
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
استبدل <profile-name> باسم ملف تعريف تكوين Azure Databricks للمصادقة.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
أفضل الممارسات الأمنية
تزيد واجهة برمجة تطبيقات تنفيذ عبارة Databricks SQL من أمان عمليات نقل البيانات باستخدام تشفير أمان طبقة النقل من طرف إلى طرف (TLS) وبيانات الاعتماد قصيرة الأجل مثل رموز SAS المميزة.
هناك عدة طبقات في نموذج الأمان هذا. في طبقة النقل، من الممكن فقط استدعاء Databricks SQL Statement Execution API باستخدام TLS 1.2 أو أعلى. أيضا، يجب مصادقة المتصلين بواجهة برمجة تطبيقات تنفيذ بيان Databricks SQL باستخدام رمز وصول شخصي صالح ل Azure Databricks أو رمز وصول OAuth المميز أو رمز معرف Microsoft Entra (المعروف سابقا باسم Azure Active Directory) الذي يعين إلى مستخدم لديه الحق في استخدام Databricks SQL. يجب أن يكون لدى هذا المستخدم إمكانية الوصول إلى CAN USE لمستودع SQL المحدد الذي يتم استخدامه، ويمكن تقييد الوصول باستخدام قوائم الوصول إلى IP. ينطبق هذا على جميع الطلبات إلى Databricks SQL Statement Execution API. علاوة على ذلك، لتنفيذ العبارات، يجب أن يكون لدى المستخدم المصادق عليه إذن لعناصر البيانات (مثل الجداول وطرق العرض والوظائف) المستخدمة في كل عبارة. يتم فرض هذا بواسطة آليات التحكم في الوصول الموجودة في كتالوج Unity أو باستخدام قوائم التحكم بالوصول للجدول. (راجع إدارة البيانات باستخدام كتالوج Unity لمزيد من التفاصيل.) وهذا يعني أيضا أن المستخدم الذي ينفذ عبارة فقط يمكنه تقديم طلبات إحضار لنتائج العبارة.
توصي Databricks بأفضل ممارسات الأمان التالية كلما استخدمت Databricks SQL Statement Execution API جنبا إلى جنب مع EXTERNAL_LINKS الترتيب لاسترداد مجموعات البيانات الكبيرة:
- إزالة رأس تخويل Databricks لطلبات تخزين Azure
- حماية عناوين URL ل SAS ورمز SAS المميز
EXTERNAL_LINKS يمكن تعطيل الترتيب عند الطلب عن طريق إنشاء حالة دعم. لإجراء هذا الطلب، اتصل بفريق حساب Azure Databricks.
إزالة رأس تخويل Databricks لطلبات تخزين Azure
يجب أن تتضمن جميع الاستدعاءات إلى Databricks SQL Statement Execution API التي تستخدم curl عنوانا Authorization يحتوي على بيانات اعتماد الوصول إلى Azure Databricks. لا تقم بتضمين هذا Authorization العنوان كلما قمت بتنزيل البيانات من تخزين Azure. هذا العنوان غير مطلوب وقد يعرض بيانات اعتماد الوصول إلى Azure Databricks عن غير قصد.
حماية عناوين URL ل SAS ورمز SAS المميز
كلما كنت تستخدم EXTERNAL_LINKS الترتيب، يتم إنشاء عنوان URL SAS قصير الأجل، والذي يمكن للمتصل استخدامه لتنزيل النتائج مباشرة من تخزين Azure باستخدام TLS. نظرا لأن رمز SAS المميز قصير الأجل مضمن في عنوان URL SAS هذا، يجب عليك حماية كل من عنوان URL SAS ورمز SAS المميز.