مقدمة إلى واجهات برمجة تطبيقات تحميل/إلغاء تحميل الملف في Azure Synapse Analytics

قام فريق Azure Synapse Studio ببناء اثنين من واجهات برمجة التطبيقات الجديدة للتركيب/إلغاء التحميل في حزمة Microsoft Spark Utilities (mssparkutils). يمكنك استخدام واجهات برمجة التطبيقات هذه لإرفاق التخزين عن بعد (مساحة تخزين Azure Blob أو Azure Data Lake Storage Gen2 أو Azure File Share) بجميع العقد العاملة (عقدة برنامج التشغيل وعقد العامل). بعد أن يكون التخزين في مكانه، يمكنك استخدام واجهة برمجة تطبيقات الملفات المحلية للوصول إلى البيانات كما لو كانت مخزنة في نظام الملفات المحلي. لمزيد من المعلومات، راجع مقدمة Microsoft Spark Utilities.

يوضح لك المقال كيفية استخدام واجهات برمجة التطبيقات (API) للتثبيت/ إلغاء التحميل في مساحة العمل الخاصة بك. ستتعلم ما يلي:

• كيفية تحميل Data Lake Storage Gen2 أو مخزن البيانات الثنائية الكبيرة أو مشاركة الملفات Azure.
• كيفية الوصول إلى الملفات الموجودة تحت نقطة التركيب عبر واجهة برمجة تطبيقات نظام الملفات المحلي.
• كيفية الوصول إلى الملفات تحت نقطة التركيب باستخدام mssparkutils fs واجهة برمجة التطبيقات.
• كيفية الوصول إلى الملفات الموجودة تحت نقطة التركيب باستخدام واجهة برمجة تطبيقات قراءة Spark.
• كيفية إلغاء تحميل نقطة التحميل.

تحذير

Azure Data Lake Storage Gen1 التخزين غير مدعوم. يمكنك الترحيل إلى Data Lake Storage Gen2 باتباع Azure Data Lake Storage Gen1 إلى إرشادات ترحيل Gen2 قبل استخدام واجهات برمجة تطبيقات التحميل.

تخزين التركيب

يوضح هذا القسم كيفية تحميل Data Lake Storage Gen2 خطوة بخطوة كمثال. يعمل تحميل مخزن البيانات الثنائية الكبيرة ومشاركة الملفات Azure بشكل مماثل.

يفترض المثال أن لديك حساب Data Lake Storage Gen2 واحد يسمى storegen2. يحتوي الحساب على حاوية واحدة باسم mycontainer تريد تحميلها /test في تجمع Spark الخاص بك.

لتحميل الحاوية المسماة mycontainer، يحتاج mssparkutils أولاً إلى التحقق مما إذا كان لديك إذن بالوصول إلى الحاوية. حاليا، يدعم Azure Synapse Analytics ثلاث طرق مصادقة لعملية تحميل المشغل: linkedService، accountKey، و sastoken.

التحميل باستخدام خدمة مرتبطة (موصى به)

نوصي بتحميل المشغل عبر الخدمة المرتبطة. تتجنب هذه الطريقة تسريبات الأمان، لأن mssparkutils لا يخزن أي قيم سرية أو مصادقة بنفسه. بدلاً من ذلك، يجلب mssparkutils دائمًا قيم المصادقة من الخدمة المرتبطة لطلب بيانات الكائن الثنائي كبير الحجم من التخزين البعيد.

يمكنك إنشاء خدمة مرتبطة Data Lake Storage Gen2 أو مخزن البيانات الثنائية الكبيرة. حاليا، يدعم Azure Synapse Analytics طريقتين للمصادقة عند إنشاء خدمة مرتبطة:

• إنشاء خدمة مرتبطة باستخدام مفتاح حساب

  

• إنشاء خدمة مرتبطة باستخدام هوية مدارة يعينها النظام

  

هام

• إذا كانت الخدمة المرتبطة التي تم إنشاؤها أعلاه إلى Azure Data Lake Storage Gen2 تستخدم نقطة نهاية خاصة إدارة (مع dfs URI)، فإننا بحاجة إلى إنشاء نقطة نهاية خاصة ثانوية أخرى مدارة باستخدام مساحة تخزين Azure Blob الخيار (مع blob URI) للتأكد من أن التعليمات البرمجية الداخلية fsspec/adlfs يمكنها الاتصال باستخدام واجهة BlobServiceClient.
• في حالة عدم تكوين نقطة النهاية الخاصة الثانوية المدارة بشكل صحيح، سنرى رسالة خطأ مثل ServiceRequestError: لا يمكن الاتصال باستضافة [storageaccountname].blob.core.windows.net:443 ssl:True [الاسم أو الخدمة غير معروفة]

إشعار

إذا قمت بإنشاء خدمة مرتبطة باستخدام هوية مُدارة كطريقة مصادقة، فتأكد من أن ملف MSI لمساحة العمل لديه دور Storage Blob Data Contributor للحاوية التي تم تحميلها.

بعد إنشاء خدمة مرتبطة بنجاح، يمكنك بسهولة تحميل الحاوية إلى تجمع Spark باستخدام التعليمات البرمجية Python التالية:

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"linkedService": "mygen2account"} 
) 

إشعار

قد تحتاج إلى استيراد mssparkutils إذا لم يكن متاحًا:

from notebookutils import mssparkutils 

لا نوصي بتثبيت مجلد جذر، بغض النظر عن طريقة المصادقة التي تستخدمها.

تحميل المعلمات:

• fileCacheTimeout: سيتم تخزين الكائنات الثنائية كبيرة الحجم مؤقتا في المجلد المؤقت المحلي لمدة 120 ثانية بشكل افتراضي. خلال هذا الوقت، لن يتحقق blobfuse مما إذا كان الملف محدثا أم لا. يمكن تعيين المعلمة لتغيير المهلة الافتراضية. عندما يقوم العديد من العملاء بتعديل الملفات في نفس الوقت، لتجنب التناقضات بين الملفات المحلية والنائية، نوصي بتقصير وقت ذاكرة التخزين المؤقت، أو حتى تغييره إلى 0، والحصول دائما على أحدث الملفات من الخادم.
• المهلة: مهلة عملية التحميل هي 120 ثانية بشكل افتراضي. يمكن تعيين المعلمة لتغيير المهلة الافتراضية. عندما يكون هناك عدد كبير جدا من المنفذين أو عند مهلة التحميل، نوصي بزيادة القيمة.
• النطاق: يتم استخدام معلمة النطاق لتحديد نطاق التحميل. القيمة الافتراضية هي "job". إذا تم تعيين النطاق إلى "job"، يكون التحميل مرئيا فقط للمجموعة الحالية. إذا تم تعيين النطاق إلى "مساحة العمل"، يكون التحميل مرئيا لجميع دفاتر الملاحظات في مساحة العمل الحالية، ويتم إنشاء نقطة التحميل تلقائيا إذا لم تكن موجودة. أضف نفس المعلمات إلى واجهة برمجة تطبيقات إلغاء التحميل لإلغاء تحميل نقطة التحميل. يتم دعم تحميل مستوى مساحة العمل فقط لمصادقة الخدمة المرتبطة.

يمكنك استخدام هذه المعلمات مثل هذا:

mssparkutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

الإدخال عبر الرمز المميز لتوقيع الوصول المشترك أو مفتاح الحساب

بالإضافة إلى التحميل من خلال خدمة مرتبطة، يدعم mssparkutils تمرير مفتاح حساب أو رمز توقيع الوصول المشترك (SAS) بشكل صريح كمعلمة لتحميل الهدف.

لأسباب أمنية، نوصي باستخدام الهويات المدارة والمصادقة Microsoft Entra بدلا من مفاتيح الحساب أو رموز SAS المميزة عندما يكون ذلك ممكنا. إذا كان يجب عليك استخدام مفاتيح الحساب، فخزنها في Azure Key Vault (كما يظهر المثال التالي لقطة الشاشة). يمكنك بعد ذلك استردادها باستخدام mssparkutil.credentials.getSecret واجهة برمجة التطبيقات. لمزيد من المعلومات، راجع مصادقة الوصول إلى البيانات في تخزين Azure.

إليك عينة التعليمة البرمجية:

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
) 

إشعار

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

الوصول إلى الملفات ضمن نقطة التحميل باستخدام mssparkutils fs API

الغرض الرئيسي من عملية التحميل هو السماح للعملاء بالوصول إلى البيانات المخزنة في حساب تخزين بعيد باستخدام واجهة برمجة تطبيقات لنظام الملفات المحلي. يمكنك أيضًا الوصول إلى البيانات باستخدام mssparkutils fs واجهة برمجة التطبيقات مع مسار مُثبت كمعلمة. تنسيق المسار المستخدم هنا مختلف قليلًا.

بافتراض أنك قمت بتحميل حاوية Data Lake Storage Gen2 mycontainer إلى /test باستخدام واجهة برمجة تطبيقات التحميل. عند الوصول إلى البيانات من خلال واجهة برمجة تطبيقات نظام ملفات محلية:

• بالنسبة لإصدارات Spark الأقل من أو تساوي 3.3، يكون تنسيق المسار هو /synfs/{jobId}/test/{filename}.
• بالنسبة لإصدارات Spark الأكبر من 3.4 أو مساوية لها، يكون تنسيق المسار هو /synfs/notebook/{jobId}/test/{filename}.

نوصي باستخدام mssparkutils.fs.getMountPath() للحصول على المسار الدقيق:

path = mssparkutils.fs.getMountPath("/test")

إشعار

عند تحميل التخزين مع workspace النطاق، يتم إنشاء نقطة التحميل ضمن /synfs/workspace المجلد . وتحتاج إلى استخدام mssparkutils.fs.getMountPath("/test", "workspace") للحصول على المسار الدقيق.

عندما تريد الوصول إلى البيانات باستخدام mssparkutils fs واجهة برمجة التطبيقات، يكون تنسيق المسار كما يلي: synfs:/notebook/{jobId}/test/{filename}. يمكنك أن ترى أنه يتم استخدام synfs كمخطط في هذه الحالة، بدلاً من جزء من المسار المثبت. بالطبع، يمكنك أيضا استخدام مخطط نظام الملفات المحلي للوصول إلى البيانات. على سبيل المثال، file:/synfs/notebook/{jobId}/test/{filename}

توضح الأمثلة الثلاثة التالية كيفية الوصول إلى ملف بمسار نقطة التركيب باستخدام mssparkutils fs.

• سرد الدلائل:

  mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}') 
  

• قراءة محتويات الملف:

  mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv') 
  

• إنشاء دليل:

  mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir') 
  

الوصول إلى الملفات تحت نقطة التركيب باستخدام واجهة برمجة تطبيقات قراءة Spark

يمكنك توفير معلمة للوصول إلى البيانات من خلال واجهة برمجة تطبيقات قراءة Spark. تنسيق المسار هنا هو نفسه عند استخدام mssparkutils fs واجهة برمجة التطبيقات.

قراءة ملف من حساب تخزين Data Lake Storage Gen2 مثبت

يفترض المثال التالي أن حساب تخزين Data Lake Storage Gen2 تم تحميله بالفعل، ثم تقرأ الملف باستخدام مسار تحميل:

%%pyspark 

df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv') 
df.show() 

إشعار

عند تحميل التخزين باستخدام خدمة مرتبطة، يجب عليك دائما تعيين تكوين خدمة spark المرتبطة بشكل صريح قبل استخدام مخطط synfs للوصول إلى البيانات. راجع تخزين ADLS Gen2 مع الخدمات المرتبطة للحصول على التفاصيل.

قراءة ملف من حساب مخزن البيانات الثنائية الكبيرة مثبت

إذا قمت بتحميل حساب مخزن البيانات الثنائية الكبيرة وتريد الوصول إليه باستخدام mssparkutils أو Spark API، فأنت بحاجة إلى تكوين رمز SAS المميز بشكل صريح عبر تكوين Spark قبل محاولة تحميل الحاوية باستخدام واجهة برمجة تطبيقات التحميل:

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

   blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 
   
   spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
   

2. قم بإنشاء الخدمة المرتبطة myblobstorageaccount، وقم بتحميل حساب مخزن البيانات الثنائية الكبيرة باستخدام الخدمة المرتبطة:

   %%spark 
   mssparkutils.fs.mount( 
       "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
       "/test", 
       Map("linkedService" -> "myblobstorageaccount") 
   ) 
   

3. قم بتحميل حاوية مخزن البيانات الثنائية الكبيرة، ثم اقرأ الملف باستخدام مسار تحميل من خلال واجهة برمجة تطبيقات الملف المحلي:

       # mount the Blob Storage container, and then read the file by using a mount path
       with open(mssparkutils.fs.getMountPath("/test") + "/myFile.txt") as f:
       print(f.read())
   

4. اقرأ البيانات من حاوية مخزن البيانات الثنائية الكبيرة المثبتة من خلال واجهة برمجة تطبيقات القراءة Spark:

   %%spark
   // mount blob storage container and then read file using mount path
   val df = spark.read.text(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.txt')
   df.show()
   

كيفية إلغاء تحميل نقطة التركيب

استخدم التعليمات البرمجية التالية لإلغاء تحميل نقطة التركيب الخاصة بك (/test في هذا المثال):

mssparkutils.fs.unmount("/test") 

القيود المعروفة

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

• تحميل حساب تخزين Data Lake Storage Gen1 غير مدعوم في الوقت الحالي.

الخطوات التالية

• بدء استخدام Azure Synapse Analytics
• مراقبة مساحة عمل Synapse الخاصة بك
• مقدمة Microsoft Spark Utilities