Use custom activities in an Azure Data Factory or Azure Synapse Analytics pipeline

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

تلميح

Data Factory في Microsoft Fabric هو الجيل القادم من Azure Data Factory، مع بنية أبسط، وذكاء اصطناعي مدمج، وميزات جديدة. إذا كنت جديدا في تكامل البيانات، ابدأ مع Fabric Data Factory. يمكن لأعباء عمل ADF الحالية الترقية إلى Fabric للوصول إلى قدرات جديدة في علوم البيانات، والتحليلات اللحظية، والتقارير.

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

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

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

إشعار

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

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

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

هام

عند إنشاء مجموعة Azure Batch جديدة، يجب استخدام 'VirtualMachineConfiguration' وليس 'CloudServiceConfiguration'.

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

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

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

Azure Batch linked service

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 الخدمة المرتبطة، راجع مقالة Compute linked services.

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

يحدد مقتطف 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 Pool.

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

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

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

إشعار

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

إشعار

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

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

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

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

يمكنك تنفيذ أمر مباشرة باستخدام نشاط مخصص. المثال التالي يشغل أمر "echo hello world" على عقد Azure Batch Pool المستهدفة ويطبع المخرج إلى 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 الخدمة المرتبطة مع واجهة مستخدم للمهمة. يمكنك الحصول على المسار التفصيلي من إخراج تشغيل النشاط كما هو موضح في قصاصة المحتوى التالية:

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/. إذا لزم الأمر، تحتاج إلى تنظيفها بشكل منفصل.
بالنسبة للخدمات المرتبطة التي تستخدم Self-Hosted Integration Runtime، يتم تشفير المعلومات الحساسة مثل المفاتيح أو كلمات المرور بواسطة Self-Hosted Integration 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 باستخدام ميزة autoscale. على سبيل المثال، يمكنك إنشاء مجموعة دفعات Azure بدون أي أجهزة افتراضية مخصصة وصيغة تدرج تلقائي بناء على عدد المهام المعلقة.

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-04-07

Use custom activities in an Azure Data Factory or Azure Synapse Analytics pipeline

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

Azure Batch linked service

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

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

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

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

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

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

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

التكبير التلقائي ل Azure Batch

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

الملاحظات

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