كيفية استخدام المعلمات والتعبيرات والدالات في Azure Data Factory

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

تلميح

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

في هذا المستند، سنركز بشكلٍ أساسي على تعلم المفاهيم الأساسية بأمثلة مختلفة لاستكشاف القدرة على إنشاء تدفقات بيانات ذات معلمات داخل Azure Data Factory. تُعد المعلمات والتعبيرات الديناميكية من الإضافات الملحوظة إلى ADF لأنها يمكن أن توفر قدرًا هائلاً من الوقت وتسمح بمزيدٍ من المرونة في حل الاستخراج والتحويل والتحميل (ETL) أو الاستخراج والتحميل والتحويل (ELT)، مما سيقلل بشكل كبير من تكلفة صيانة الحلول ويسرع تنفيذ ميزات جديدة في تدفق حالي. تعود هذه المكاسب إلى أن تحديد المعلمات يقلل من مقدار الترميز الثابت ويزيد من عدد الكائنات والعمليات القابلة لإعادة الاستخدام في الحل.

واجهة مستخدم Azure Data Factory والمعلمات

إذا كنت مستخدماً جديداً لاستخدام معلمة Azure Data Factory في واجهة مستخدم ADF، فالرجاء مراجعة واجهة مستخدم Data Factory للخدمات المرتبطة ذات المعلمات وواجهة مستخدم Data Factory لمسار التدفق المستند إلى بيانات التعريف مع المعلمات للحصول على تفسير مرئي.

مفاهيم المعلمات والتعبير

يمكنك استخدام المعلمات لتمرير القيم الخارجية إلى التدفقات ومجموعات البيانات والخدمات المرتبطة وتدفقات البيانات. بمجرد تمرير المعلمة إلى المورد، لا يمكن تغييرها. فمن خلال تحديد معلمات الموارد، يمكنك إعادة استخدامها بقيم مختلفة في كل مرة. يمكن استخدام المعلمات بشكلٍ فردي أو كجزء من التعبيرات. قد تكون قيم JSON الواردة في التعريف حرفية أو تعبيرات يتم تقييمها في وقت التشغيل.

على سبيل المثال:

"name": "value"

أو

"name": "@pipeline().parameters.password"

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

قيمة JSON	نتيجة
"المعلمات"	يتم إرجاع "معلمات" الأحرف.
"المعلمات[1]"	يتم إرجاع "معلمات[1]" الأحرف.
"@@"	تم إرجاع سلسلة مكونة من حرف واحد تحتوي على "@".
" @"	تم إرجاع سلسلة مكونة من حرفين تحتوي على "@".

قد تظهر التعبيرات أيضاً داخل السلاسل، باستخدام ميزة تسمى استنتاج السلسلة حيث يتم تضمين التعبيرات في @{ ... }. على سبيل المثال: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

باستخدام استنتاج السلسلة، تكون النتيجة دائماً ضمن سلسلة. لنفترض أنني عرّفت myNumber على أنه 42 وmyString على أنه foo:

قيمة JSON	نتيجة
"@pipeline().parameters.myString"	إرجاع foo كسلسلة.
"@{pipeline().parameters.myString}"	إرجاع foo كسلسلة.
"@pipeline().parameters.myNumber"	إرجاع 42كعدد.
"@{pipeline().parameters.myNumber}"	إرجاع 42 كسلسلة.
"الإجابة هي: @{pipeline().parameters.myNumber}"	إرجاع السلسلة Answer is: 42.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))"	إرجاع السلسلة Answer is: 42
"Answer is: @@{pipeline().parameters.myNumber}"	إرجاع السلسلة Answer is: @{pipeline().parameters.myNumber}.

أمثلة على استخدام المعلمات في التعبيرات

مثال التعبير المعقد

يوضح المثال أدناه مثالاً معقداً يشير إلى حقل فرعي عميق لناتج النشاط. للإشارة إلى معلمة تدفقات يتم تقييمها إلى حقل فرعي، استخدم بناء الجملة [] بدلاً من عامل dot(.) (كما في حالة الحقل الفرعي 1 والحقل الفرعي 2)

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

محرر المحتوى الديناميكي

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

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

يقوم محرر المحتوى الديناميكي بتحويل المحتوى أعلاه إلى تعبير "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". ينتج هذا التعبير عن سلسلة بتنسيق JSON موضحة أدناه.

{
  "type": "Table",
  "name": "MYDATA"
}

مجموعة بيانات مع معلمات

في المثال التالي، تأخذ BlobDataset معلمة باسم path. يتم استخدام قيمته لتعيين قيمة للخاصية folderPath باستخدام التعبير: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

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

في المثال التالي، تأخذ التدفقات معلمات inputPath وoutputPath. يتم تعيين المسار لمجموعة البيانات الثنائية الكبيرة ذات المعلمات باستخدام قيم هذه المعلمات. بناء الجملة المستخدم هنا هو: pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

استدعاء دالات داخل التعبيرات

يمكنك استدعاء الدالات داخل التعبيرات. توفر الأقسام التالية معلومات حول الدالات التي يمكن استخدامها في تعبير.

دالات السلسلة

للعمل مع السلاسل، يمكنك استخدام دالات السلسلة هذه وكذلك بعض دالات المجموعة. تعمل دالات السلسلة فقط على السلاسل.

دالة السلسلة	مهمة
concat	ضم سلسلتين أو أكثر، ثم إرجاع السلسلة المدمجة.
endsWith	التحقق مما إذا كانت سلسلة تنتهي بالسلسلة الفرعية المحددة.
دليل	إنشاء معرف فريد عمومي (GUID) كسلسلة.
indexOf	إرجاع موضع البداية لسلسلة فرعية.
lastIndexOf	إرجاع موضع البداية لآخر تكرار لسلسة فرعية.
replace	استبدال سلسلة فرعية بالسلسلة المحددة، ثم إرجاع السلسلة المحدثة.
split	إرجاع مصفوفة تحتوي على سلاسل فرعية مفصولة بفاصلات من سلسلة أكبر استناداً إلى حرف محدد معين في السلسلة الأصلية.
startsWith	تحقق مما إذا كانت سلسلة تبدأ بسلسلة فرعية معينة.
substring	إرجاع أحرف من سلسلة، بدءاً من الموضع المحدد.
toLower	إرجاع سلسلة بتنسيق أحرف صغيرة.
toUpper	إرجاع سلسلة بتنسيق أحرف كبيرة.
trim	إزالة المسافة البيضاء البادئة والزائدة من سلسلة، ثم إرجاع السلسلة المحدثة.

دالات التحصيل

للعمل مع المجموعات، والصفائف عموماً، والسلاسل، والقواميس أحياناً، يمكنك استخدام دالات الجمع هذه.

دالة المجموعة	مهمة
تحتوي على	التحقق مما إذا كانت المجموعة تحتوي على عنصر معين.
فارغ	التحقق مما إذا كانت المجموعة فارغة أم لا.
أولاً	إرجاع العنصر الأول من المجموعة.
intersection	إرجاع مجموعة تحتوي فقط على العناصر المشتركة عبر المجموعات المحددة.
join	إرجاع سلسلة تحتوي على جميع العناصر من مصفوفة، مفصولة بالحرف المحدد.
last	إرجاع العنصر الأخير من مجموعة.
الطول	إرجاع عدد العناصر في سلسلة أو مصفوفة.
تخطي	إزالة العناصر من مقدمة المجموعة، وإعادة جميع العناصر الأخرى.
الوقت المستغرق	إرجاع العناصر من مقدمة المجموعة.
union	إرجاع مجموعة تحتوي على جميع العناصر من المجموعات المحددة.

الدالات المنطقية

هذه الدالات مفيدة في الظروف الداخلية، ويمكن استخدامها لتقييم أي نوع من المنطق.

دالة المقارنة المنطقية	مهمة
و	التحقق مما إذا كانت جميع التعبيرات صحيحة.
equals	التحقق مما إذا كانت كلتا القيمتين متساويتين.
greater	التحقق مما إذا كانت القيمة الأولى أكبر من القيمة الثانية.
greaterOrEquals	التحقق مما إذا كانت القيمة الأولى أكبر من أو مساوية للقيمة الثانية.
if	التحقق مما إذا كان التعبير صحيحاً أم خطأ. بناءً على النتيجة، قم بإرجاع قيمة محددة.
less	التحقق مما إذا كانت القيمة الأولى أقل من القيمة الثانية.
lessOrEquals	التحقق مما إذا كانت القيمة الأولى أقل من أو مساوية للقيمة الثانية.
not	التحقق مما إذا كان التعبير غير صحيح.
أو	التحقق مما إذا كان هناك تعبير واحد على الأقل صحيح.

دالات التحويل

تُستخدم هذه الدالات للتحويل بين جميع الأنواع الأصلية في اللغة:

• سلسلة
• integer
• عائم
• boolean
• الصفائف
• القواميس

دالة التحويل	مهمة
صفيف	إرجاع صفيف من إدخال واحد محدد. للحصول على مدخلات متعددة، انظر createArray.
قاعدة 64	إرجاع الإصدار المرمّز باستخدام base64 لإحدى السلاسل.
base64ToBinary	إرجاع الإصدار الثنائي لسلسلة مرمّزة باستخدام base64.
base64ToString	إرجاع إصدار السلسلة لسلسلة مرمّزة باستخدام base64.
binary	إرجاع الإصدار الثنائي لقيمة إدخال.
bool	إرجاع الإصدار المنطقي لقيمة إدخال.
coalesce	إرجاع القيمة غير الفارغة الأولى من معلمة واحدة أو أكثر.
createArray	إرجاع صفيف من مدخلات متعددة.
dataUri	إرجاع URI للبيانات لقيمة إدخال.
dataUriToBinary	إرجاع الإصدار الثنائي لـ URI للبيانات.
dataUriToString	إرجاع إصدار السلسلة لـ URI للبيانات.
decodeBase64	إرجاع إصدار السلسلة لسلسلة مرمّزة باستخدام base64.
decodeDataUri	إرجاع الإصدار الثنائي لـ URI للبيانات.
decodeUriComponent	إرجاع سلسلة استبدال أحرف الإلغاء بإصدارات غير مرمزة.
encodeUriComponent	إرجاع سلسلة يستبدل أحرف URL غير الآمنة بأحرف الإلغاء.
طفا	إرجاع رقم فاصلة عائمة لقيمة إدخال.
الباحث	إرجاع إصدار صحيح لسلسلة.
json	بإرجاع قيمة نوع JavaScript Object Notation (JSON) أو كائن لسلسلة أو XML.
string	إرجاع إصدار السلسلة لقيمة إدخال.
uriComponent	إرجاع إصدار URI المرمز لقيمة إدخال عن طريق استبدال أحرف URL غير الآمنة بأحرف إلغاء.
uriComponentToBinary	إرجاع الإصدار الثنائي لسلسلة URI المرمزة.
uriComponentToString	إرجاع إصدار السلسلة لسلسلة URI المرمزة.
xml	إرجاع إصدار XML لسلسلة.
xpath	التحقق من XML للعقد أو القيم التي تطابق تعبير XPath (لغة مسار XML)، ثم إرجاع العقد أو القيم المتطابقة.

دالات رياضيات

يمكن استخدام هذه الدالات لجميع أنواع الأعداد: أعداد صحيحة وأعداد عائمة.

الدالة الرياضية	مهمة
add	إرجاع الناتج من إضافة رقمين.
div	إرجاع الناتج من قسمة رقمين.
max	إرجاع القيمة الأعلى من مجموعة من الأرقام أو صفيف.
دقيقه	إرجاع القيمة الأقل من مجموعة من الأرقام أو صفيف.
mod	إرجاع الباقي من قسمة رقمين.
mul	إرجاع الناتج من ضرب رقمين.
rand	إرجاع عدد صحيح عشوائي من نطاق محدد.
النطاق	إرجاع صفيف عدد صحيح يبدأ من عدد صحيح محدد.
sub	إرجاع الناتج من طرح الرقم الثاني من الرقم الأول.

دوال التاريخ

دالة التاريخ أو الوقت	مهمة
addDays	إضافة عدد من الأيام إلى الطابع الزمني.
addHours	إضافة عدد من الساعات إلى الطابع الزمني.
addMinutes	إضافة عدد من الدقائق إلى الطابع الزمني.
addSeconds	إضافة عدد من الثواني إلى الطابع الزمني.
addToTime	إضافة عدد من وحدات الوقت إلى الطابع الزمني. انظر كذلك getFutureTime.
convertFromUtc	تحويل طابع زمني من تنسيق التوقيت العالمي (UTC) إلى المنطقة الزمنية الهدف.
convertTimeZone	تحويل طابع زمني من المنطقة الزمنية المصدر إلى المنطقة الزمنية الهدف.
convertToUtc	تحويل طابع زمني من المنطقة الزمنية المصدر إلى تنسيق التوقيت العالمي (UTC).
dayOfMonth	إرجاع مكون أيام الشهر من الطابع زمني.
dayOfWeek	إرجاع مكون يوم الأسبوع من الطابع الزمني.
dayOfYear	إرجاع مكون أيام السنة من الطابع زمني.
formatDateTime	إرجاع الطابع الزمني كسلسلة بتنسيق اختياري.
getFutureTime	إرجاع الطابع الزمني الحالي بالإضافة إلى وحدات الوقت المحددة. انظر كذلك addToTime.
getPastTime	إرجاع الطابع الزمني الحالي مطروحاً منه الوحدات الزمنية المحددة. انظر كذلك subtractFromTime.
startOfDay	إرجاع بداية اليوم للحصول على طابع زمني.
startOfHour	إرجاع بداية الساعة للحصول على طابع زمني.
startOfMonth	إرجاع بداية الشهر للحصول على طابع زمني.
subtractFromTime	طرح عدد من وحدات الوقت من الطابع الزمني. انظر كذلك getPastTime.
القراد	إرجاع قيمة الخاصية ticks لطابع زمني محدد.
utcNow	إرجاع الطابع الزمني الحالي كسلسلة.

أمثلة تفصيلية للممارسة

تدفق نسخ مصنع Azure Data Factory المفصل مع المعلمات

ترشدك معلمة تدفق نسخ Azure Data Factory لتمرير البرنامج التعليمي إلى كيفية تمرير المعلمات بين التدفقات والنشاط وكذلك بين الأنشطة.

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

يرجى اتباع مخطط تدفق البيانات مع المعلمات للحصول على مثال شامل بشأن كيفية استخدام المعلمات في تدفق البيانات.

تدفق بيانات وصفية مفصل مع معلمات

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

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

للحصول على قائمة بمتغيرات النظام التي يمكنك استخدامها في التعبيرات، راجع متغيرات النظام.