نشاط الويب في Azure Data Factory وAzure Synapse Analytics

مقالة
10/20/2023

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

تلميح

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

يمكن استخدام نشاط ويب لاستدعاء نقطة نهاية REST المخصصة من Azure Data Factory أو تدفق Synapse. يمكنك تمرير مجموعات البيانات والخدمات المرتبطة التي سيتم استهلاكها والوصول إليها عن طريق النشاط.

إشعار

يتم دعم نشاط الويب لاستدعاء عناوين URL التي يتم استضافتها في شبكة ظاهرية خاصة وكذلك من خلال الاستفادة من وقت تشغيل التكامل المستضاف ذاتيًا. ويجب أن يكون لوقت تشغيل التكامل مجال رؤية لنقطة نهاية عنوان URL.

إشعار

الحد الأقصى لحجم مخرجات حمولة الاستجابة المعتمدة هو 4 ميجابايت.

إنشاء نشاط ويب باستخدام واجهة المستخدم

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

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

بناء الجملة

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

خصائص النوع

الخاصية	‏‏الوصف	القيم المسموح بها	المطلوب
الاسم	اسم نشاط الويب	السلسلة‬	‏‏نعم‬
النوع	يتعين تعيينه إلى WebActivity.	السلسلة‬	‏‏نعم‬
الطريقة	أسلوب واجهة برمجة تطبيقات REST لنقطة النهاية الهدف.	السلسلة. الأنواع المدعومة: "GET"، "POST"، "PUT"، "PATCH"، "DELETE"	‏‏نعم‬
عنوان URL	نقطة النهاية الهدف والمسار	سلسلة (أو تعبير يستخدم resultType من النوع "سلسلة"). ستنتهي مهلة النشاط بعد دقيقة واحدة عند ظهور خطأ إذا لم يتلق استجابة من نقطة النهاية. يمكنك زيادة مهلة الاستجابة هذه حتى 10 دقائق عن طريق تحديث خاصية httpRequestTimeout	‏‏نعم‬
httpRequestTimeout	مدة مهلة الاستجابة	س س:د د:ث ث مع القيمة القصوى لتكون 00:10:00. إذا لم يتم تحديد الإعدادات الافتراضية بشكل صريح إلى 00:01:00	لا
رؤوس	العناوين التي يتم إرسالها إلى الطلب. على سبيل المثال، لتعيين اللغة والكتابة على الطلب: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	سلسلة (أو تعبير يستخدم resultType من النوع "سلسلة")	لا
النص الأساسي	يمثل الحمولة التي يتم إرسالها إلى نقطة النهاية.	سلسلة (أو تعبير يستخدم resultType من النوع "سلسلة"). راجع مخطط حمولة الطلب في قسم مخطط حمولة الطلب.	مطلوب لأساليب POST/PUT/PATCH. اختياري لأسلوب DELETE.
المصادقة	أسلوب المصادقة المستخدم لاستدعاء نقطة النهاية. الأنواع المدعومة هي "Basic، Client Certificate، System-assigned Managed Identity، User-assigned Managed Identity، Service Principal" لمزيد من المعلومات، راجع قسم المصادقة. استثني هذه الخاصية في حالة عدم طلب المصادقة.	سلسلة (أو تعبير يستخدم resultType من النوع "سلسلة")	لا
turnOffAsync	خيار لتعطيل استدعاء HTTP GET في حقل الموقع في عنوان الاستجابة لاستجابة HTTP 202. إذا تم تعيينه على "true"، فإنه يتوقف عن استدعاء HTTP GET على موقع http المحدد في عنوان الاستجابة. إذا تم تعيين خطأ، فسيستمر في استدعاء HTTP GET على الموقع المحدد في عناوين استجابة http.	القيم المسموح بها هي false (افتراضية) وtrue.	لا
disableCertValidation	يزيل التحقق من صحة الشهادة من جانب الخادم (غير مستحسن ما لم تكن متصلاً بخادم موثوق به لا يستخدم شهادة CA قياسية).	القيم المسموح بها هي false (افتراضية) وtrue.	لا
مجموعات البيانات	قائمة بمجموعات البيانات التي تم تمريرها إلى نقطة النهاية.	مصفوفة من مراجع مجموعة البيانات. يمكن أن تكون مصفوفة فارغة.	‏‏نعم‬
الخدمات المرتبطة	قائمة الخدمات المرتبطة التي تم تمريرها إلى نقطة النهاية.	مصفوفة مراجع الخدمة المرتبطة. يمكن أن تكون مصفوفة فارغة.	‏‏نعم‬
connectVia	يُستخدم وقت تشغيل التكامل للاتصال بمخزن البيانات. يمكنك استخدام وقت تشغيل تكامل Azure أو وقت تشغيل التكامل المستضاف ذاتياً (إذا كان مخزن البيانات الخاص بك في شبكة خاصة). إذا لم يتم تحديد هذه الخاصية، فإن الخدمة تستخدم وقت تشغيل تكامل Azure الافتراضي.	مرجع وقت تشغيل التكامل.	لا

إشعار

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

يعرض الجدول التالي متطلبات محتوى JSON:

نوع القيمة	نص الطلب	هيئة الاستجابة
كائن JSON	مدعوم	مدعوم
مصفوفة JSON	دعم (في الوقت الحالي، لا تعمل صفائف JSON نتيجة لخطأ. التصحيح قيد التقدم.)	غير مدعوم
قيمة JSON	مدعوم	غير مدعوم
نوع غير JSON	غير مدعوم	غير مدعوم

المصادقة

فيما يلي أنواع المصادقة المعتمدة في نشاط الويب.

بلا

لا تقم بتضمين خاصية "المصادقة" إذا لم تكن المصادقة مطلوبة.

أساسي

حدد اسم المستخدم وكلمة المرور لاستخدامها مع المصادقة الأساسية.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

شهادة العميل

حدد محتويات ترميز base64 ملف PFX وكلمة المرور.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

يجب أن تكون الشهادة شهادة x509. للتحويل إلى ملف PFX، يمكنك استخدام الأداة المفضلة لديك. بالنسبة لترميز base-64، يمكنك استخدام القصاصة البرمجية PowerShell التالية.

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

الهوية المُدارة

حدد عنوان uri للمورد حيث يُطلب الرمز المميز للوصول باستخدام الهوية المُدارة لـ Data Factory أو مثيل مساحة عمل Synapse. استخدم https://management.azure.com/ لاستدعاء واجهة برمجة تطبيقات Azure Resource Management. لمزيد من المعلومات حول كيفية عمل الهويات المُدارة، راجع صفحة نظرة عامة عن الهويات المُدارة لموارد Azure.

"authentication": {
	"type": "MSI",
	"resource": "https://management.azure.com/"
}

إشعار

إذا تم تكوين Data Factory أو مساحة عمل Synapse باستخدام مستودع Git، فيتعين عليك تخزين بيانات الاعتماد الخاصة بك في Azure Key Vault لاستخدام المصادقة الأساسية أو مصادقة شهادة العميل. لا تُخزن الخدمة كلمات المرور في Git.

طلب مخطط الحمولة

عند استخدام الأسلوب POST/PUT، تمثل الخاصية النص الأساسي الحمولة التي يتم إرسالها إلى نقطة النهاية. يمكنك تمرير الخدمات المرتبطة ومجموعات البيانات كجزء من الحمولة. فيما يلي مخطط للحمولة:

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

مثال

في هذا المثال، يستدعي نشاط ويب في التدفق نقطة نهاية REST. يقوم بتمرير خدمة Azure SQL المرتبطة ومجموعة بيانات Azure SQL إلى نقطة النهاية. وتستخدم نقطة نهاية REST سلسلة اتصال Azure SQL للاتصال بخادم SQL المنطقي وإرجاع اسم مثيل خادم SQL.

تعريف المسار

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

قيم معلمة التدفق

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

التعليمة البرمجية لنقطة نهاية خدمة ويب


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

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

نشاط الويب في Azure Data Factory وAzure Synapse Analytics

إنشاء نشاط ويب باستخدام واجهة المستخدم

بناء الجملة

خصائص النوع

المصادقة

بلا

أساسي

شهادة العميل

الهوية المُدارة

طلب مخطط الحمولة

مثال

تعريف المسار

قيم معلمة التدفق

التعليمة البرمجية لنقطة نهاية خدمة ويب

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

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