تحويل البيانات عن طريق تشغيل دفتر ملاحظات Synapse

ينطبق على:Azure Data Factory Azure Synapse Analytics

تلميح

جرب Data Factory في Microsoft Fabric، وهو حل تحليلي متكامل للمؤسسات. يغطي Microsoft Fabric كل شيء بدءا من حركة البيانات إلى علم البيانات والتحليلات في الوقت الحقيقي والمعلومات المهنية وإعداد التقارير. تعرف على كيفية بدء إصدار تجريبي جديد مجانا!

يقوم نشاط دفتر ملاحظات Azure Synapse في البنية الأساسية لبرنامج ربط العمليات التجارية لـ Synapse بتشغيل دفتر ملاحظات Synapse في مساحة عمل Azure Synapse الخاصة بك. تقوم هذه المقالة بالاعتماد على مقالةأنشطة تحويل البيانات، والتي تقدم نظرة عامة لتحويل البيانات وأنشطة التحويل المدعومة. 

إنشاء نشاط دفتر ملاحظات Synapse

يمكنك إنشاء نشاط دفتر ملاحظات Synapse مباشرة من لوحة البنية الأساسية لبرنامج ربط العمليات التجارية لـ Synapse أو من محرر دفتر الملاحظات. يتم تشغيل نشاط دفتر ملاحظات Synapse على تجمع Spark الذي يتم اختياره في دفتر ملاحظات Synapse.

إضافة نشاط دفتر ملاحظات Synapse من لوحة البنية الأساسية لبرنامج ربط العمليات التجارية

اسحب دفتر ملاحظات Synapse وأفلته ضمن الأنشطة على لوحة البنية الأساسية لبرنامج ربط العمليات التجارية لـ Synapse. حدد في مربع نشاط دفتر ملاحظات Synapse وقم بتكوين محتوى دفتر الملاحظات للنشاط الحالي في الإعدادات. يمكنك تحديد دفتر ملاحظات موجود من مساحة العمل الحالية أو إضافة دفتر ملاحظات جديد.

إذا قمت بتحديد دفتر ملاحظات موجود من مساحة العمل الحالية، يمكنك النقر فوق الزر فتح لفتح صفحة دفتر الملاحظات مباشرة.

(اختياري) يمكنك أيضًا إعادة تكوين تجمع Spark\حجم المنفذ\التخصيص الديناميكي للمنفذين\Min المنفذين\الحد الأقصى من المنفذين\حجم برنامج التشغيل في الإعدادات. تجدر الإشارة إلى أن الإعدادات التي تمت إعادة تكوينها هنا ستحل محل إعدادات جلسة التكوين في Notebook. إذا لم يتم تعيين أي شيء في إعدادات نشاط دفتر الملاحظات الحالي، فسيتم تشغيله مع إعدادات جلسة التكوين في دفتر الملاحظات هذا.

الخاصية	الوصف	مطلوب
تجمع Spark	مرجع إلى تجمع Spark. يمكنك تحديد تجمع Apache Spark من القائمة. إذا كان هذا الإعداد فارغًا، فسيتم تشغيله في مجموعة spark دفتر الملاحظات نفسه.	لا
حجم المنفذ	عدد المعالجات والذاكرة التي سيتم استخدامها للمنفذين المخصصين في تجمع Apache Spark المحدد للجلسة.	لا
ديناميكي تخصيص المنفذين	يعيّن هذا الإعداد خاصية التخصيص الديناميكي في تكوين Spark لتخصيص منفذي تطبيق Spark.	لا
حد المنفذين	الحد الأدنى لعدد المنفذين الذين سيتم تخصيصهم في مجموعة Spark المحددة للوظيفة.	لا
Max executors	الحد الأقصى لعدد المنفذين الذين سيتم تخصيصهم في مجموعة Spark المحددة للوظيفة.	لا
حجم برنامج التشغيل	عدد النوى والذاكرة التي سيتم استخدامها لبرنامج التشغيل في تجمع Apache Spark المحدد لهذه المهمة.	لا

ملاحظة

يتم وضع تنفيذ دفاتر ملاحظات Spark المتوازية في البنية الأساسية لبرنامج ربط العمليات التجارية لـ Azure Synapse في قائمة الانتظار وتنفيذها بطريقة FIFO، وترتيب المهام في قائمة الانتظار وفقاً للتسلسل الزمني، ووقت انتهاء صلاحية المهمة في قائمة الانتظار هو 3 أيام، يرجى ملاحظة أن قائمة الانتظار لدفتر الملاحظات تعمل فقط في البنية الأساسية لبرنامج ربط العمليات التجارية لـ synapse.

إضافة دفتر ملاحظات إلى البنية الأساسية لبرنامج ربط العمليات التجارية لـ Synapse

حدد الزر إضافة إلى البنية الأساسية لبرنامج ربط العمليات التجارية في الزاوية العلوية اليسرى لإضافة دفتر ملاحظات إلى البنية الأساسية لبرنامج ربط العمليات التجارية الموجودة أو إنشاء بنية أساسية لبرنامج ربط العمليات التجارية جديدة.

تمرير المعلمات

عيّن خلية المعلمات

لتحديد معلمات دفتر الملاحظات الخاص بك، قم بتحديد علامات الحذف (...) للوصول إلى المزيد من الأوامر في شريط أدوات الخلية. ثم حدد تبديل خلية المعلمة لتعيين الخلية كخلية المعلمات.

يبحث Azure Data Factory عن خلية المعلمات ويستخدم القيم كإعدادات افتراضية للمعلمات التي تم تمريرها في وقت التنفيذ. سيضيف محرك التنفيذ خلية جديدة أسفل خلية المعلّمات مع معلّمات الإدخال من أجل الكتابة فوق القيم الافتراضية.

تعيين قيم المعلمات من البنية الأساسية لبرنامج ربط العمليات التجارية

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

عند تعيين قيم المعلمات، يمكنك استخدام لغة تعبير البنية الأساسية لبرنامج ربط العمليات التجارية أو متغيرات النظام.

قراءة قيمة إخراج خلية دفتر الملاحظات Synapse

يمكنك قراءة قيمة إخراج خلية دفتر الملاحظات في الأنشطة التالية باتباع الخطوات التالية:

1. استدعاء واجهة برمجة التطبيقات mssparkutils.notebook.exit في نشاط دفتر ملاحظات Synapse لإرجاع القيمة التي تريد إظهارها في إخراج النشاط، على سبيل المثال:

   mssparkutils.notebook.exit("hello world") 
   

   حفظ محتوى دفتر الملاحظات وإعادة تشغيل البنية الأساسية لبرنامج ربط العمليات التجارية، سوف يحتوي إخراج نشاط دفتر الملاحظات على exitValue التي يمكن استهلاكها للأنشطة التالية في الخطوة 2.

2. قراءة الخاصية exitValue من إخراج نشاط دفتر الملاحظات. فيما يلي عينة تعبير تستخدم للتحقق مما إذا كان exitValue الذي تم إحضاره من إخراج نشاط دفتر الملاحظات يساوي "مرحباً بالعالم":

   

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

يمكنك الرجوع إلى دفاتر الملاحظات الأخرى في نشاط دفتر ملاحظات Synapse عبر استدعاء %run magic أو mssparkutils notebook utilities. يدعم كلاهما استدعاءات دالة التداخل. الاختلافات الرئيسية من هاتين الطريقتين التي يجب أن تأخذ في الاعتبار استناداً إلى السيناريو الخاص بك هي:

• يقوم %run magic بنسخ كل الخلايا من دفتر الملاحظات المشار إليه إلى الخلية %run ومشاركة سياق المتغير. عندما يشير دفتر الملاحظات 1 إلى دفتر الملاحظات 2 عبر %run notebook2 ويستدعي دفتر الملاحظات 2 دالة mssparkutils.notebook.exit، سيتم إيقاف تنفيذ الخلية في دفتر الملاحظات 1. نوصي باستخدام %run magic عندما تريد "تضمين" ملف دفتر ملاحظات.
• تستدعي الأدوات المساعدة لدفتر الملاحظات mssparkutils دفتر الملاحظات المشار إليه كطريقة أو دالة. سياق المتغير غير مشترك. عندما يشير دفتر الملاحظات 1 إلى دفتر الملاحظات 2 عبر mssparkutils.notebook.run("notebook2") ويستدعي دفتر الملاحظات 2 دالة mssparkutils.notebook.exit، سيستمر تنفيذ الخلية في دفتر الملاحظات 1. نوصي باستخدام الأدوات المساعدة لدفتر ملاحظات mssparkutils عندما تريد "استيراد" دفتر ملاحظات.

راجع محفوظات تشغيل نشاط دفتر الملاحظات

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

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

افتح لقطة دفتر الملاحظات:

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

تعريف نشاط دفتر ملاحظات Synapse

إليك تعريف JSON النموذجي لنشاط دفتر ملاحظات Synapse:

{
    "name": "parameter_test",
    "type": "SynapseNotebook",
    "dependsOn": [],
    "policy": {
        "timeout": "7.00:00:00",
        "retry": 0,
        "retryIntervalInSeconds": 30,
        "secureOutput": false,
        "secureInput": false
    },
    "userProperties": [],
    "typeProperties": {
        "notebook": {
            "referenceName": "parameter_test",
            "type": "NotebookReference"
        },
        "parameters": {
            "input": {
                "value": {
                    "value": "@pipeline().parameters.input",
                    "type": "Expression"
                }
            }
        }
    }
}

إخراج نشاط دفتر ملاحظات Synapse

إليك عينة JSON لإخراج نشاط دفتر ملاحظات Synapse:

{
{
    "status": {
        "Status": 1,
        "Output": {
            "status": <livySessionInfo>
            },
            "result": {
                "runId": "<GUID>",
                "runStatus": "Succeed",
                "message": "Notebook execution is in Succeeded state",
                "lastCheckedOn": "2021-03-23T00:40:10.6033333Z",
                "errors": {
                    "ename": "",
                    "evalue": ""
                },
                "sessionId": 4,
                "sparkpool": "sparkpool",
                "snapshotUrl": "https://myworkspace.dev.azuresynapse.net/notebooksnapshot/{guid}",
                "exitCode": "abc" // return value from user notebook via mssparkutils.notebook.exit("abc")
            }
        },
        "Error": null,
        "ExecutionDetails": {}
    },

    "effectiveIntegrationRuntime": "DefaultIntegrationRuntime (West US 2)",
    "executionDuration": 234,
    "durationInQueue": {
        "integrationRuntimeQueue": 0
    },
    "billingReference": {
        "activityType": "ExternalActivity",
        "billableDuration": [
            {
                "meterType": "AzureIR",
                "duration": 0.06666666666666667,
                "unit": "Hours"
            }
        ]
    }
}

المشكلات المعروفة

إذا تم قياس اسم دفتر الملاحظات في نشاط Pipeline Notebook، فلا يمكن الرجوع إلى إصدار دفتر الملاحظات في حالة غير منشورة في عمليات تشغيل التصحيح.