كيفية إنشاء وظائف معرفة من قبل المستخدم في Azure Digital Twins

مقالة
01/17/2020

هام

تم إصدار إصدار جديد من خدمة Azure Digital Twins. في ضوء القدرات الموسعة للخدمة الجديدة، تم إيقاف خدمة Azure Digital Twins الأصلية (الموضحة في مجموعة الوثائق هذه).

لعرض وثائق الخدمة الجديدة، قم بزيارة وثائق Azure Digital Twins النشطة.

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

يتجول هذا الدليل في مثال يوضح كيفية اكتشاف أي قراءة تتجاوز درجة حرارة معينة من أحداث درجة الحرارة المستلمة والتنبيه إليها.

في الأمثلة أدناه ، YOUR_MANAGEMENT_API_URL يشير إلى عنوان URI لواجهات برمجة تطبيقات Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

الاسم	استبدال بـ
YOUR_INSTANCE_NAME	اسم مثيل Azure Digital Twins الخاص بك
YOUR_LOCATION	المنطقة التي تتم استضافة المثيل عليها

مرجع مكتبة العميل

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

إنشاء مطابق

المطابقات هي كائنات رسم بياني تحدد الوظائف المعرفة من قبل المستخدم التي يتم تشغيلها لرسالة قياس عن بعد معينة.

مقارنات حالة المطابقة الصالحة:
- Equals
- NotEquals
- Contains
أهداف حالة المطابقة الصالحة:
- Sensor
- SensorDevice
- SensorSpace

يتم تقييم مطابق المثال التالي إلى true في أي حدث قياس عن بعد للمستشعر مع "Temperature" قيمة نوع البيانات الخاصة به. يمكنك إنشاء مطابقات متعددة على وظيفة معرفة من قبل المستخدم عن طريق تقديم طلب HTTP POST مصادق عليه من أجل:

YOUR_MANAGEMENT_API_URL/matchers

مع جسم JSON:

{
  "id": "3626464-f39b-46c0-d9b0c-436aysj55",
  "name": "Temperature Matcher",
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "conditions": [
    {
      "id": "ag7gq35cfu3-e15a-4e9c-6437-sj6w68sy44s",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    }
  ]
}

القيمة	استبدال بـ
YOUR_SPACE_IDENTIFIER	منطقة الخادم التي تتم استضافة مثيلك عليها

إنشاء الوظيفة المحددة من قبل المستخدم

يتضمن إنشاء وظيفة معرفة من قبل المستخدم إجراء طلب HTTP متعدد الأجزاء إلى واجهات برمجة تطبيقات إدارة التوائم الرقمية في Azure.

ملاحظة

تتطلب الطلبات متعددة الأجزاء عادة ثلاث قطع:

رأس من نوع المحتوى :
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
التصرف في المحتوى:
- form-data; name="metadata"
محتوى الملف المراد تحميله

سيختلف نوع المحتوىوالتصرف في المحتوى وفقا لسيناريو الاستخدام.

يمكن تقديم طلبات متعددة الأجزاء برمجيا (من خلال C #) ، من خلال عميل REST ، أو أداة مثل Postman. قد يكون لأدوات عميل REST مستويات متفاوتة من الدعم للطلبات المعقدة متعددة الأجزاء. قد تختلف إعدادات التكوين أيضا قليلا من أداة إلى أخرى. تحقق من الأداة الأنسب لاحتياجاتك.

هام

عادة ما تتكون الطلبات متعددة الأجزاء المقدمة إلى واجهات برمجة تطبيقات Azure Digital Twins Management من جزأين:

بيانات تعريف النقطة (مثل نوع MIME المقترن) التي يتم الإعلان عنها بواسطة نوع المحتوى و/أو التصرف في المحتوى
محتويات Blob التي تتضمن محتويات غير منظمة لملف يتم تحميله

لا يلزم أي من الجزأين لطلبات PATCH . كلاهما مطلوب ل POST أو إنشاء عمليات.

تحتوي التعليمات البرمجية المصدرية للبدء السريع للإشغال على أمثلة كاملة ل C # توضح كيفية تقديم طلبات متعددة الأجزاء مقابل واجهات برمجة تطبيقات Azure Digital Twins Management.

بعد إنشاء المطابقات، قم بتحميل مقتطف الوظيفة باستخدام طلب HTTP POST متعدد الأجزاء المصادق عليه التالي إلى:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

استخدم النص التالي:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "name": "User Defined Function",
  "description": "The contents of this udf will be executed when matched against incoming telemetry.",
  "matchers": ["YOUR_MATCHER_IDENTIFIER"]
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="userDefinedFunction.js"
Content-Type: text/javascript

function process(telemetry, executionContext) {
  // Code goes here.
}

--USER_DEFINED_BOUNDARY--

القيمة	استبدال بـ
USER_DEFINED_BOUNDARY	اسم حد محتوى متعدد الأجزاء
YOUR_SPACE_IDENTIFIER	معرف المسافة
YOUR_MATCHER_IDENTIFIER	معرف المطابق الذي تريد استخدامه

تحقق من أن الرؤوس تتضمن: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".
تحقق من أن الجسم متعدد الأجزاء:
- يحتوي الجزء الأول على البيانات الوصفية المطلوبة للدالة المعرفة من قبل المستخدم.
- يحتوي الجزء الثاني على منطق حساب جافا سكريبت.
في القسم USER_DEFINED_BOUNDARY، استبدل قيمتي spaceId () والمطابقات (YOUR_MATCHER_IDENTIFIERYOUR_SPACE_IDENTIFIER) .
تحقق من توفير الدالة المعرفة من قبل المستخدم في جافا سكريبت ك Content-Type: text/javascript.

مثال على الدالات

اضبط قراءة القياس عن بعد للمستشعر مباشرة للمستشعر باستخدام نوع البيانات درجة الحرارة ، وهو sensor.DataType:

function process(telemetry, executionContext) {

  // Get sensor metadata
  var sensor = getSensorMetadata(telemetry.SensorId);

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Set the sensor reading as the current value for the sensor.
  setSensorValue(telemetry.SensorId, sensor.DataType, parseReading.SensorValue);
}

تعرض معلمة القياس عن بعد سمات SensorId و Message ، المقابلة لرسالة مرسلة بواسطة مستشعر. تعرض المعلمة executionContext السمات التالية:

var executionContext = new UdfExecutionContext
{
    EnqueuedTime = request.HubEnqueuedTime,
    ProcessorReceivedTime = request.ProcessorReceivedTime,
    UserDefinedFunctionId = request.UserDefinedFunctionId,
    CorrelationId = correlationId.ToString(),
};

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

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Example sensor telemetry reading range is greater than 0.5
  if(parseFloat(parseReading.SensorValue) > 0.5) {
    log(`Alert: Sensor with ID: ${telemetry.SensorId} detected an anomaly!`);
  }
}

تقوم التعليمة البرمجية التالية بتشغيل إعلام إذا ارتفع مستوى درجة الحرارة فوق الثابت المحدد مسبقا:

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Define threshold
  var threshold = 70;

  // Trigger notification 
  if(parseInt(parseReading) > threshold) {
    var alert = {
      message: 'Temperature reading has surpassed threshold',
      sensorId: telemetry.SensorId,
      reading: parseReading
    };

    sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(alert));
  }
}

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

قم بإنشاء تعيين الدور

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

الاستعلام عن واجهة برمجة تطبيقات النظام لجميع الأدوار للحصول على معرف الدور الذي تريد تعيينه للوظيفة المعرفة من قبل المستخدم. قم بذلك عن طريق تقديم طلب HTTP GET مصادق عليه من أجل:
```
YOUR_MANAGEMENT_API_URL/system/roles
```
احتفظ بمعرف الدور المطلوب. سيتم تمريره كسمة نص JSON roleId (YOUR_DESIRED_ROLE_IDENTIFIER) أدناه.
objectId (YOUR_USER_DEFINED_FUNCTION_ID) سيكون معرف الدالة المعرفة من قبل المستخدم الذي تم إنشاؤه مسبقا.
ابحث عن قيمة المسار (YOUR_ACCESS_CONTROL_PATH) عن طريق الاستعلام عن المسافات باستخدام fullpath.
انسخ القيمة المرتجعة spacePaths . ستستخدم ذلك أدناه. قم بتقديم طلب HTTP GET مصادق عليه من أجل:
```
YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
```
القيمة استبدال بـ

YOUR_SPACE_NAME اسم المساحة التي ترغب في استخدامها

القيمة	استبدال بـ
YOUR_SPACE_NAME	اسم المساحة التي ترغب في استخدامها

الصق القيمة التي تم إرجاعها spacePaths في المسار لإنشاء تعيين دور دالة معرف من قبل المستخدم عن طريق تقديم طلب HTTP POST مصادق عليه من أجل:

YOUR_MANAGEMENT_API_URL/roleassignments

مع جسم JSON:

{
  "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
  "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
  "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
  "path": "YOUR_ACCESS_CONTROL_PATH"
}

القيمة	استبدال بـ
YOUR_DESIRED_ROLE_IDENTIFIER	معرف الدور المطلوب
YOUR_USER_DEFINED_FUNCTION_ID	معرف الدالة المعرفة من قبل المستخدم التي تريد استخدامها
YOUR_USER_DEFINED_FUNCTION_TYPE_ID	المعرف الذي يحدد نوع الدالة المعرفة من قبل المستخدم (`UserDefinedFunctionId`)
YOUR_ACCESS_CONTROL_PATH	مسار التحكم في الوصول

تلميح

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

إرسال القياس عن بعد لتتم معالجته

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

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

الخطوات التالية

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

مشاركة عبر