استخدام الأنشطة المخصصة في Azure Data Factory أو مسار Azure Synapse Analytics

مقالة
12/09/2023

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

تلميح

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

هناك نوعان من الأنشطة التي يمكنك استخدامها في Azure Data Factory أو مسار Synapse.

أنشطة حركة البيانات لنقل البيانات بين مخازن بيانات المصدر والمتلقي المدعومة.
أنشطة تحويل البيانات لتحويل البيانات باستخدام خدمات الحوسبة مثل Azure HDInsight وAzure Batch.

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

إشعار

نوصي باستخدام الوحدة النمطية Azure Az PowerShell للتفاعل مع Azure. راجع تثبيت Azure PowerShell للبدء. لمعرفة كيفية الترحيل إلى الوحدة النمطية Az PowerShell، راجع ترحيل Azure PowerShell من AzureRM إلى Az.

راجع المقالات التالية إذا كنت جديدا على خدمة Azure Batch:

أساسيات Azure Batch للحصول على نظرة عامة حول خدمة Azure Batch.
New-AzBatchAccount cmdlet لإنشاء حساب Azure Batch (أو) مدخل Azure لإنشاء حساب Azure Batch باستخدام مدخل Azure. راجع مقالة استخدام PowerShell لإدارة حساب Azure Batch للحصول على إرشادات مفصلة حول استخدام cmdlet.
New-AzBatchPool cmdlet لإنشاء مجموعة Azure Batch.

هام

عند إنشاء مجموعة Azure Batch جديدة، يجب استخدام "VirtualMachineConfiguration" وليس "CloudServiceConfiguration". لمزيد من التفاصيل راجع إرشادات ترحيل مجموعة Azure Batch.

إضافة أنشطة مخصصة للبنية الأساسية لبرنامج ربط العمليات التجارية باستخدام واجهة المستخدم

لاستخدام نشاط مخصص في مسار، أكمل الخطوات التالية:

ابحث عن مخصص في جزء أنشطة البنية الأساسية لبرنامج ربط العمليات التجارية، واسحب نشاطًا مخصصًا إلى لوحة البنية الأساسية لبرنامج ربط العمليات التجارية.
حدد النشاط المخصص الجديد على اللوحة إذا لم يكن محددًا بالفعل.
حدد علامة التبويب Azure Batch لتحديد أو إنشاء خدمة Azure Batch المرتبطة الجديدة التي ستقوم بتنفيذ النشاط المخصص.
حدد علامة التبويب الإعدادات وحدد أمرًا ليتم تنفيذه على Azure Batch، والتفاصيل المتقدمة الاختيارية.

الخدمة المرتبطة Azure Batch

يعرّف JSON التالي عينة من خدمة Azure Batch المرتبطة. للحصول على التفاصيل، راجع بيئات الحوسبة المعتمدة

{
    "name": "AzureBatchLinkedService",
    "properties": {
        "type": "AzureBatch",
        "typeProperties": {
            "accountName": "batchaccount",
            "accessKey": {
                "type": "SecureString",
                "value": "access key"
            },
            "batchUri": "https://batchaccount.region.batch.azure.com",
            "poolName": "poolname",
            "linkedServiceName": {
                "referenceName": "StorageLinkedService",
                "type": "LinkedServiceReference"
            }
        }
    }
}

لمعرفة المزيد حول خدمة Azure Batch المرتبطة، راجع مقالة حساب الخدمات المرتبطة .

النشاط المخصص

يحدد مقتطف JSON التالي مساراً مع نشاط مخصص بسيط. يحتوي تعريف النشاط على مرجع إلى خدمة Azure Batch المرتبطة.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "helloworld.exe",
        "folderPath": "customactv2/helloworld",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        }
      }
    }]
  }
}

في هذا النموذج، يعد helloworld.exe تطبيقًا مخصصًا مخزنًا في المجلد customactv2 / helloworld لحساب Azure Storage المستخدم في ResourceLinkedService. يرسل النشاط المخصص هذا التطبيق المخصص ليتم تنفيذه على Azure Batch. يمكنك استبدال الأمر بأي تطبيق مفضل يمكن تنفيذه على نظام التشغيل الهدف لعُقد مجموعة Azure Batch.

يصف الجدول التالي أسماء وأوصاف الخصائص الخاصة بهذا النشاط.

الخاصية	الوصف	مطلوب
الاسم	اسم النشاط في المسار	‏‏نعم‬
الوصف	نص يصف ما يفعله النشاط.	لا
النوع	بالنسبة للنشاط المخصص، يكون نوع النشاط مخصصاً.	‏‏نعم‬
linkedServiceName	خدمة مرتبطة بـ Azure Batch. للتعرف على هذه الخدمة المرتبطة، راجع مقالة خدمات الحوسبة المرتبطة.	‏‏نعم‬
الأمر	الأمر الخاص بالتطبيق المخصص الذي سيتم تنفيذه. إذا كان التطبيق متاحًا بالفعل على عقد مجموعة Azure Batch، فيمكن تخطي ResourceLinkedService وfolderPath. على سبيل المثال، يمكنك تحديد الأمر ليكون `cmd /c dir`، والذي يتم دعمه أصلاً بواسطة عقدة مجموعة Windows Batch.	‏‏نعم‬
resourceLinkedService	خدمة Azure Storage المرتبطة بحساب التخزين حيث يتم تخزين التطبيق المخصص	لا *
folderPath	المسار إلى مجلد التطبيق المخصص وجميع تبعياته إذا كان لديك تبعيات مخزنة في مجلدات فرعية - أي في هيكل مجلد هرمي ضمن مسار المجلد - فسيتم حالياً تسوية بنية المجلد عند نسخ الملفات إلى Azure Batch. أي، يتم نسخ جميع الملفات في مجلد واحد دون مجلدات فرعية. للتغلب على هذا السلوك، ضع في الاعتبار ضغط الملفات، ونسخ الملف المضغوط، ثم فك ضغطه باستخدام التعليمات البرمجية المخصصة في الموقع المطلوب.	لا *
referenceObjects	صفيفة من الخدمات المرتبطة ومجموعات البيانات الموجودة. يتم تمرير الخدمات المرتبطة ومجموعات البيانات المشار إليها إلى التطبيق المخصص بتنسيق JSON حتى يمكن أن تشير التعليمات البرمجية المخصصة إلى موارد الخدمة	لا
extendedProperties	الخصائص المعرفة من قبل المستخدم التي يمكن تمريرها إلى التطبيق المخصص بتنسيق JSON بحيث يمكن أن تشير التعليمات البرمجية المخصصة إلى خصائص إضافية	لا
retentionTimeInDays	وقت الاحتفاظ بالملفات المرسلة للنشاط المخصص. القيمة الافتراضية هي 30 يوماً.	لا

* يجب أن يتم تحديد الخاصيتين resourceLinkedServiceوfolderPath أو حذفهما معاً.

إشعار

إذا كنت تقوم بتمرير الخدمات المرتبطة ككائنات مرجعية في نشاط مخصص، فمن الممارسات الأمنية الجيدة تمرير خدمة مرتبطة تم تمكينها لـ Azure Key Vault (نظرًا لأنها لا تحتوي على أي سلاسل آمنة) وجلب بيانات الاعتماد باستخدام الاسم السري مباشرة من Key Vault من التعليمات البرمجية. يمكنك العثور على مثال هنا يشير إلى خدمة مرتبطة ممكنة من AKV، ويسترد بيانات الاعتماد من Key Vault، ثم يصل إلى التخزين في التعليمات البرمجية.

إشعار

حاليا يتم دعم تخزين Azure Blob فقط ل resourceLinkedService في النشاط المخصص، وهي الخدمة المرتبطة الوحيدة التي يتم إنشاؤها بشكل افتراضي ولا يوجد خيار لاختيار موصلات أخرى مثل ADLS Gen2.

أذونات نشاط مخصصة

يعيّن النشاط المخصص حساب المستخدم التلقائي Azure Batch على وصول غير إداري مع نطاق مهمة (المواصفات الافتراضية للمستخدم التلقائي). لا يمكنك تغيير مستوى الإذن لحساب المستخدم التلقائي. لمزيد من المعلومات، راجع تشغيل المهام ضمن حسابات المستخدمين في دُفعة | حسابات المستخدمين التلقائيين.

تنفيذ الأوامر

يمكنك تنفيذ أمر مباشرة باستخدام نشاط مخصص. يقوم المثال التالي بتشغيل الأمر "echo hello world" على عقد مجموعة Azure Batch المستهدفة ويطبع الإخراج إلى stdout.

{
  "name": "MyCustomActivity",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "cmd /c echo hello world"
      }
    }]
  }
}

تمرير الكائنات والخصائص

يوضح هذا النموذج كيفية استخدام referenceObjects و extendedProperties لتمرير الكائنات والخصائص المعرفة من قبل المستخدم من الخدمة إلى التطبيق المخصص.

{
  "name": "MyCustomActivityPipeline",
  "properties": {
    "description": "Custom activity sample",
    "activities": [{
      "type": "Custom",
      "name": "MyCustomActivity",
      "linkedServiceName": {
        "referenceName": "AzureBatchLinkedService",
        "type": "LinkedServiceReference"
      },
      "typeProperties": {
        "command": "SampleApp.exe",
        "folderPath": "customactv2/SampleApp",
        "resourceLinkedService": {
          "referenceName": "StorageLinkedService",
          "type": "LinkedServiceReference"
        },
        "referenceObjects": {
          "linkedServices": [{
            "referenceName": "AzureBatchLinkedService",
            "type": "LinkedServiceReference"
          }]
        },
        "extendedProperties": {          
          "connectionString": {
            "type": "SecureString",
            "value": "aSampleSecureString"
          },
          "PropertyBagPropertyName1": "PropertyBagValue1",
          "propertyBagPropertyName2": "PropertyBagValue2",
          "dateTime1": "2015-04-12T12:13:14Z"
        }
      }
    }]
  }
}

عند تنفيذ النشاط، يتم تخزين referenceObjects وextendedProperties في الملفات التالية التي يتم نشرها في نفس مجلد التنفيذ الخاص بـ SampleApp.exe:

activity.json

مخازن extendedProperties وخصائص النشاط المخصص.
linkedServices.json

يخزن صفيف الخدمات المرتبطة المعرفة في خاصية referenceObjects.
datasets.json

يخزن صفيف مجموعة البيانات المعرفة في خاصية referenceObjects.

يوضح نموذج التعليمات البرمجية التالي كيف يمكن لـ SampleApp.exe الوصول إلى المعلومات المطلوبة من ملفات JSON:

using Newtonsoft.Json;
using System;
using System.IO;

namespace SampleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            //From Extend Properties
            dynamic activity = JsonConvert.DeserializeObject(File.ReadAllText("activity.json"));
            Console.WriteLine(activity.typeProperties.extendedProperties.connectionString.value);

            // From LinkedServices
            dynamic linkedServices = JsonConvert.DeserializeObject(File.ReadAllText("linkedServices.json"));
            Console.WriteLine(linkedServices[0].properties.typeProperties.accountName);
        }
    }
}

استرداد مخرجات التنفيذ

يمكنك بدء تشغيل مسار باستخدام الأمر PowerShell التالي:

$runId = Invoke-AzDataFactoryV2Pipeline -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineName $pipelineName

عند تشغيل مسار، يمكنك التحقق من إخراج التنفيذ باستخدام الأوامر التالية:

while ($True) {
    $result = Get-AzDataFactoryV2ActivityRun -DataFactoryName $dataFactoryName -ResourceGroupName $resourceGroupName -PipelineRunId $runId -RunStartedAfter (Get-Date).AddMinutes(-30) -RunStartedBefore (Get-Date).AddMinutes(30)

    if(!$result) {
        Write-Host "Waiting for pipeline to start..." -foregroundcolor "Yellow"
    }
    elseif (($result | Where-Object { $_.Status -eq "InProgress" } | Measure-Object).count -ne 0) {
        Write-Host "Pipeline run status: In Progress" -foregroundcolor "Yellow"
    }
    else {
        Write-Host "Pipeline '"$pipelineName"' run finished. Result:" -foregroundcolor "Yellow"
        $result
        break
    }
    ($result | Format-List | Out-String)
    Start-Sleep -Seconds 15
}

Write-Host "Activity `Output` section:" -foregroundcolor "Yellow"
$result.Output -join "`r`n"

Write-Host "Activity `Error` section:" -foregroundcolor "Yellow"
$result.Error -join "`r`n"

يتم حفظ stdout وstderr للتطبيق المخصص الخاص بك إلى حاوية adfjobs في خدمة Azure Storage المرتبطة التي قمت بتعريفها عند إنشاء خدمة Azure Batch المرتبطة مع GUID للمهمة. يمكنك الحصول على المسار التفصيلي من إخراج تشغيل النشاط كما هو موضح في قصاصة المحتوى التالية:

Pipeline ' MyCustomActivity' run finished. Result:

ResourceGroupName : resourcegroupname
DataFactoryName   : datafactoryname
ActivityName      : MyCustomActivity
PipelineRunId     : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PipelineName      : MyCustomActivity
Input             : {command}
Output            : {exitcode, outputs, effectiveIntegrationRuntime}
LinkedServiceName :
ActivityRunStart  : 10/5/2017 3:33:06 PM
ActivityRunEnd    : 10/5/2017 3:33:28 PM
DurationInMs      : 21203
Status            : Succeeded
Error             : {errorCode, message, failureType, target}

Activity Output section:
"exitcode": 0
"outputs": [
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stdout.txt",
  "https://<container>.blob.core.windows.net/adfjobs/<GUID>/output/stderr.txt"
]
"effectiveIntegrationRuntime": "DefaultIntegrationRuntime (East US)"
Activity Error section:
"errorCode": ""
"message": ""
"failureType": ""
"target": "MyCustomActivity"

إذا كنت ترغب في استهلاك محتوى stdout.txt في أنشطة انتقال البيانات، يمكنك الحصول على المسار إلى ملف stdout.txt في التعبير "@activity('MyCustomActivity').output.outputs[0]".

هام

يتم تخزين كل من Activity.json وlinkedServices.json وdatasets.json في مجلد وقت التشغيل الخاص بمهمة الدُّفعة. في هذا المثال، يتم تخزين النشاطات activity.json وlinkedServices.json وdatasets.json في مسار https://adfv2storage.blob.core.windows.net/adfjobs/<GUID>/runtime/. إذا لزم الأمر، تحتاج إلى تنظيفها بشكل منفصل.
بالنسبة إلى الخدمات المرتبطة التي تستخدم وقت تشغيل التكامل المستضاف ذاتيًا، يتم تشفير المعلومات الحساسة مثل المفاتيح أو كلمات المرور بواسطة وقت تشغيل التكامل المستضاف ذاتيًا لضمان بقاء بيانات الاعتماد في بيئة شبكة الاتصال الخاصة المعرفة من قبل العميل. قد تكون بعض الحقول الحساسة مفقودة عند الرجوع إليها بواسطة التعليمات البرمجية للتطبيق المخصص بهذه الطريقة. استخدم SecureString في extendedProperties بدلاً من استخدام مرجع الخدمة المرتبطة إذا لزم الأمر.

تمرير المخرجات إلى نشاط آخر

يمكنك إرسال قيم مخصصة من التعليمات البرمجية الخاصة بك في نشاط مخصص إلى الخدمة مرة أخرى. يمكنك القيام بذلك عن طريق كتابتها في outputs.json من تطبيقك. تنسخ الخدمة محتوى outputs.json وتقوم بإلحاقه بإخراج النشاط كقيمة للخاصية customOutput. (الحد الأقصى للحجم هو 2 ميغا بايت). إذا كنت تريد استهلاك محتوى outputs.json في أنشطة انتقال البيانات، يمكنك الحصول على القيمة باستخدام التعبير @activity('<MyCustomActivity>').output.customOutput.

استرداد مخرجات السلاسل الآمنة

تم إخفاء قيم الخصائص الحساسة المعينة كنوع SecureString، كما هو موضح في بعض الأمثلة في هذه المقالة، في علامة التبويب المراقبة في واجهة المستخدم. ومع ذلك، في تنفيذ المسار الفعلي، يتم إجراء تسلسل لخاصية SecureString كـ JSON داخل ملف activity.json كنص عادي. على سبيل المثال:

"extendedProperties": {
  "connectionString": {
    "type": "SecureString",
    "value": "aSampleSecureString"
  }
}

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

للوصول إلى خصائص من النوع SecureString من نشاط مخصص، اقرأ ملف activity.json، الذي تم وضعه في نفس المجلد مثل ملف ‎.EXE الخاص بك، وقم بإلغاء تسلسل JSON، ثم قم بالوصول إلى خاصية JSON (extensionProperties => [propertyName] => القيمة).

التحجيم التلقائي لـ Azure Batch

يمكنك أيضًا إنشاء مجموعة Azure Batch باستخدام ميزة التحجيم التلقائي. على سبيل المثال، يمكنك إنشاء مجموعة Azure Batch مع عدم وجود أجهزة ظاهرية مخصصة وصيغة تحجيم تلقائي استناداً إلى عدد المهام المعلقة.

تحقق صيغة العينة هنا السلوك التالي: عند إنشاء المجموعة مبدئيًا، تبدأ بجهاز ظاهري واحد. يحدد مقياس $PendingTasks عدد المهام في حالة التشغيل + النشطة (في قائمة الانتظار). تجد الصيغة متوسط عدد المهام المعلقة في آخر 180 ثانية وتحدد TargetDedicated وفقاً لذلك. إنه يضمن أن TargetDedicated لا يتجاوز 25 جهازاً أبداً. لذلك، مع إرسال المهام الجديدة، تنمو المجموعة تلقائياً وعندما تكتمل المهام، تصبح الأجهزة الظاهرية حرة واحدة تلو الأخرى ويقلص التحجيم التلقائي تلك الأجهزة الظاهرية. يمكن تعديل بدء تشغيل NumberOfVMs وmaxNumberofVMs حسب احتياجاتك.

صيغة التحجيم التلقائي:

startingNumberOfVMs = 1;
maxNumberofVMs = 25;
pendingTaskSamplePercent = $PendingTasks.GetSamplePercent(180 * TimeInterval_Second);
pendingTaskSamples = pendingTaskSamplePercent < 70 ? startingNumberOfVMs : avg($PendingTasks.GetSample(180 * TimeInterval_Second));
$TargetDedicated=min(maxNumberofVMs,pendingTaskSamples);

راجع قياس العقد تلقائيًا في مجموعة Azure Batch للحصول على التفاصيل.

إذا كانت المجموعة تستخدم الافتراضي autoScaleEvaluationInterval ، فقد تستغرق خدمة Batch من 15 إلى 30 دقيقة لإعداد الجهاز الظاهري قبل تشغيل النشاط المخصص. إذا كان المجموعة تستخدم autoScaleEvaluationInterval مختلفة، فقد تستغرق خدمة الدُفعة autoScaleEvaluationInterval‏ + 10 دقائق.

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

استخدام الأنشطة المخصصة في Azure Data Factory أو مسار Azure Synapse Analytics

إضافة أنشطة مخصصة للبنية الأساسية لبرنامج ربط العمليات التجارية باستخدام واجهة المستخدم

الخدمة المرتبطة Azure Batch

النشاط المخصص

أذونات نشاط مخصصة

تنفيذ الأوامر

تمرير الكائنات والخصائص

استرداد مخرجات التنفيذ

تمرير المخرجات إلى نشاط آخر

استرداد مخرجات السلاسل الآمنة

التحجيم التلقائي لـ Azure Batch

المحتوى ذو الصلة

الموارد الإضافية