إدارة نقاط النهاية والمسارات في Azure Digital Twins

مقالة
04/27/2022
قراءة خلال 16 دقائق

ترشدك هذه المقالة خلال عملية إنشاء نقاط النهاية والمسارات باستخدام مدخل Azure وواجهات برمجة تطبيقات REST و.NET (C#) SDK وAzure Digital Twins CLI.

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

المتطلبات الأساسية

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

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

حدد المثيل الخاص بك من النتائج لرؤية هذه التفاصيل في نظرة عامة على المثيل الخاص بك:

Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted.

اتبع الإرشادات أدناه إذا كنت تنوي استخدام Azure CLI أثناء اتباع هذا الدليل.

إعداد البيئة الخاصة بك لـ Azure CLI

استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع تشغيل سريع لـ Azure Cloud Shell - Bash.
إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.
- إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، التزم بالخطوات المعروضة في وحدتك الطرفية. للحصول على خيارات إضافية لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.
- عند مطالبتك، يوصى بتثبيت امتدادات Azure CLI عند الاستخدام الأول. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.
- يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

قم بإنشاء نقطة نهاية لـ Azure Digital Twins

هذه الخدمات هي الأنواع المدعومة من نقاط النهاية التي يمكنك إنشاؤها للمثيل الخاص بك:

ملاحظة

بالنسبة لنقاط نهاية شبكة الأحداث، يتم دعم موضوعات شبكة الأحداث فقط. لا يتم دعم مجالات شبكة الأحداث كنقاط نهاية.

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

يشرح هذا القسم كيفية إنشاء نقطة نهاية باستخدام مدخل Azure أو Azure CLI. يمكنك أيضا إدارة نقاط النهاية باستخدام واجهات برمجة تطبيقات مستوى التحكم في DigitalTwinsEndpoint.

المتطلب السابق: إنشاء موارد نقطة النهاية

لربط نقطة نهاية ب Azure Digital Twins، يجب أن يكون موضوع شبكة الأحداث أو مركز الأحداث أو موضوع ناقل الخدمة الذي تستخدمه لنقطة النهاية موجودا بالفعل.

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

نوع نقطة النهاية	الموارد المطلوبة (مرتبطة بتعليمات الإنشاء)
نقطة نهاية شبكة الحدث	موضوع شبكة الحدث *يجب أن يكون مخطط الحدث مخطط شبكة الحدث أو مخطط أحداث Cloud الإصدار 1.0
نقطة نهاية مراكز الأحداث	مساحة اسم "مراكز الأحداث" مركز الفعاليات (اختياري) قاعدة التفويض للمصادقة المستندة إلى المفتاح
نقطة نهاية ناقل الخدمة	مساحة اسم Service Bus موضوع ناقل الخدمة (اختياري) قاعدة التفويض للمصادقة المستندة إلى المفتاح

أنشئ نقطة النهاية

بمجرد إنشاء موارد نقطة النهاية، يمكنك استخدامها لنقطة نهاية Azure Digital Twins.

المدخل
CLI

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

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

هام

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

بعد إنشاء نقطة النهاية، يمكنك التحقق من إنشاء نقطة النهاية بنجاح عن طريق التحقق من أيقونة الإعلام في شريط مدخل Azure العلوي:

Screenshot of the notification to verify the creation of an endpoint in the Azure portal.

في حالة فشل إنشاء نقطة النهاية، لاحظ رسالة الخطأ وأعد المحاولة بعد بضع دقائق.

يمكنك أيضا عرض نقطة النهاية التي تم إنشاؤها مرة أخرى على صفحة نقاط النهاية لمثيل Azure Digital Twins.

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

توضح الأمثلة التالية كيفية إنشاء نقاط نهاية باستخدام الأمر az dt endpoint create for the Azure Digital Twins CLI. استبدل العناصر النائبة في الأوامر بتفاصيل مواردك الخاصة.

لإنشاء نقطة نهاية شبكة الأحداث:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

لإنشاء نقطة نهاية مراكز الأحداث (مصادقة تستند إلى المفاتيح):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

لإنشاء نقطة نهاية موضوع ناقل الخدمة (المصادقة المستندة إلى المفتاح):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

بعد تشغيل هذه الأوامر بنجاح، ستتوفر شبكة الأحداث أو مركز الأحداث أو موضوع ناقل الخدمة كنقطة نهاية في Azure Digital Twins، تحت الاسم الذي قمت بتوفيره مع الوسيطة --endpoint-name . ستستخدم عادة هذا الاسم كهدف لمسار الحدث، والذي ستقوم بإنشائه لاحقا في هذه المقالة.

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

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

يوجد الأمر CLI لإنشاء هذا النوع من نقاط النهاية أدناه. ستحتاج إلى القيم التالية لتوصيلها بالعناصر النائبة في الأمر:

معرف مورد Azure لمثيل Azure Digital Twins الخاص بك
اسم نقطة النهاية
نوع نقطة نهاية
مساحة اسم مورد نقطة النهاية
اسم مركز الحدث أو موضوع ناقل الخدمة
موقع مثيل Azure Digital Twins

az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\"}, \"location\":\"<instance-location>\" }' --is-full-object

إنشاء نقطة نهاية بأحرف ميتة

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

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

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

إعداد موارد التخزين

قبل تعيين موقع الحرف الميت، يجب أن يكون لديك حساب تخزين مع حاوية تم إعدادها في حساب Azure الخاص بك.

ستوفر عنوان URI لهذه الحاوية عند إنشاء نقطة النهاية لاحقا. سيتم توفير موقع الحرف الميت إلى نقطة النهاية كعنوان URI للحاوية مع رمز SAS. يحتاج هذا الرمز المميز إلى write إذن للحاوية الوجهة داخل حساب التخزين. سيكون الحرف الميت المشكل بالكامل SAS URI بتنسيق: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

اتبع الخطوات أدناه لإعداد موارد التخزين هذه في حساب Azure الخاص بك، للتحضير لإعداد اتصال نقطة النهاية في القسم التالي.

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

إنشاء رمز SAS مميز

بعد ذلك ، قم بإنشاء رمز SAS مميز لحساب التخزين الخاص بك يمكن لنقطة النهاية استخدامه للوصول إليه.

المدخل
CLI

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

يمكنك استرداد مفاتيح حساب التخزين باستخدام الأمر التالي ونسخ قيمة أي من المفاتيح:
```
az storage account keys list --account-name <storage-account-name>
```
حدد تاريخ انتهاء الصلاحية وقم بإنشاء رمز SAS المميز لحساب التخزين الخاص بك باستخدام الأمر التالي:
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
إخراج هذا الأمر هو الرمز المميز SAS. انسخ قيمة الرمز المميز SAS لاستخدامها لاحقا.

ملاحظة

يتضمن هذا الأمر خدمات "blob" و "file" و "queue" و "table" ؛ نوع مورد "object" ؛ ويسمح أذونات "write".

لمزيد من المعلومات حول az storage account generate-sas الأمر ومعلماته، راجع مرجع Azure CLI.

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

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

لإنشاء نقطة نهاية تم تمكين الأحرف الميتة، أضف معلمة الحرف الميت التالية إلى الأمر az dt endpoint create for the Azure Digital Twins CLI.

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

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

أضف هذه المعلمة إلى نهاية أوامر إنشاء نقطة النهاية من القسم إنشاء نقطة النهاية في وقت سابق لإنشاء نقطة نهاية من النوع الذي اخترته والذي تم تمكين الأحرف الميتة.

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

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

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

لإنشاء هذا النوع من نقاط النهاية، استخدم نفس الأمر CLI من وقت سابق لإنشاء نقطة نهاية مع مصادقة تستند إلى الهوية، مع حقل إضافي في حمولة JSON ل deadLetterUri.

فيما يلي القيم التي ستحتاج إلى توصيلها بالعناصر النائبة في الأمر:

معرف مورد Azure لمثيل Azure Digital Twins الخاص بك
اسم نقطة النهاية
نوع نقطة نهاية
مساحة اسم مورد نقطة النهاية
اسم مركز الحدث أو موضوع ناقل الخدمة
تفاصيل SAS URI بالحرف الميت: اسم حساب التخزين واسم الحاوية
موقع مثيل Azure Digital Twins

az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\", \"deadLetterUri\": \"https://<storage-account-name>.blob.core.windows.net/<container-name>\"}, \"location\":\"<instance-location>\" }' --is-full-object

مخطط تخزين الرسائل

بمجرد إعداد نقطة النهاية ذات الأحرف الميتة، سيتم تخزين الرسائل ذات الأحرف الميتة بالتنسيق التالي في حساب التخزين الخاص بك:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

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

في ما يلي مثال على رسالة بخط ميت لإشعار إنشاء مزدوج:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

إنشاء مسار الحدث

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

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

ملاحظة

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

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

يمكن أن يحتوي تعريف المسار على هذه العناصر:

اسم المسار الذي تريد استخدامه
اسم نقطة النهاية التي تريد استخدامها
عامل تصفية يحدد أي الأحداث يتم إرسالها إلى نقطة النهاية
- لتعطيل المسار بحيث لا يتم إرسال أي أحداث، استخدم قيمة عامل تصفية false
- لتمكين مسار لا يحتوي على تصفية محددة، استخدم قيمة عامل تصفية true
- للحصول على تفاصيل حول أي نوع آخر من الفلترات، راجع قسم تصفية الأحداث أدناه

إذا لم يكن هناك اسم مسار، فلن يتم توجيه أي رسائل خارج Azure Digital Twins. إذا كان هناك اسم مسار وكان عامل التصفية كذلك true، توجيه جميع الرسائل إلى نقطة النهاية. إذا كان هناك اسم مسار وتمت إضافة فلتر مختلف، تصفية الرسائل استنادا إلى الفلتر.

يمكن إنشاء مسارات الأحداث باستخدام مدخل Azure أو واجهات برمجة تطبيقات مستوى بيانات EventRoutes أو أوامر CLI لمسار az dt. بقية هذا القسم يسير خلال عملية الإنشاء.

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

من قائمة المثيل، حدد مسارات الأحداث. ثم من صفحة مسارات الأحداث التالية، حدد + إنشاء مسار حدث.

في الصفحة إنشاء مسار حدث يتم فتحه، اختر على الأقل:

اسم لمسارك في حقل الاسم
نقطة النهاية التي تريد استخدامها لإنشاء المسار

لتمكين المسار، يجب عليك أيضا إضافة عامل تصفية مسار حدث على الأقل true. (سيؤدي ترك القيمة الافتراضية للمسار false إلى إنشاء المسار، ولكن لن يتم إرسال أي أحداث إليه.) للقيام بذلك، قم بتبديل المفتاح الخاص بالمحرر المتقدم لتمكينه، واكتب true في المربع تصفية .

عند الانتهاء، حدد الزر حفظ لإنشاء مسار الحدث.

يوضح هذا القسم كيفية إنشاء مسار حدث باستخدام .NET (C#) SDK.

CreateOrReplaceEventRouteAsync هو استدعاء SDK المستخدم لإضافة مسار حدث. فيما يلي مثال على استخدامه:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

تلميح

تأتي جميع وظائف SDK في إصدارات متزامنة وغير متزامنة.

نموذج التعليمات البرمجية لمسار الحدث SDK

يوضح نموذج الأسلوب التالي كيفية إنشاء مسار حدث وإدراجها وحذفها باستخدام حزمة تطوير البرامج C#‎:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

أحداث التصفية

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

بعد تمكين الحد الأدنى من عامل التصفية ، ستتلقى نقاط النهاية أنواعا مختلفة من الأحداث من trueAzure Digital Twins:

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

يمكنك تقييد أنواع الأحداث التي يتم إرسالها عن طريق تحديد عامل تصفية أكثر تحديدًا.

ملاحظة

المرشحات حساسة لحالة الأحرف وتحتاج إلى مطابقة حالة الحمولة.

بالنسبة لمرشحات القياس عن بعد ، هذا يعني أن الغلاف يحتاج إلى مطابقة الغلاف في القياس عن بعد الذي يرسله الجهاز ، وليس بالضرورة الغلاف المحدد في نموذج التوأم.

المدخل
API

لإضافة عامل تصفية حدث أثناء إنشاء مسار حدث، استخدم القسم إضافة عامل تصفية مسار حدث في الصفحة إنشاء مسار حدث .

يمكنك إما الاختيار من بين بعض خيارات التصفية الأساسية الشائعة، أو استخدام خيارات التصفية المتقدمة لكتابة عوامل التصفية المخصصة الخاصة بك.

استخدم الفلاتر الأساسية

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

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the checkboxes of the events.

سيؤدي القيام بذلك إلى ملء مربع نص عامل التصفية تلقائيا بنص عامل التصفية الذي حددته:

Screenshot of creating an event route with a basic filter in the Azure portal, highlighting the autopopulated filter text after selecting the events.

استخدام الفلاتر المتقدمة

يمكنك أيضا استخدام خيار التصفية المتقدمة لكتابة الفلاتر المخصصة الخاصة بك.

لإنشاء مسار حدث باستخدام خيارات التصفية المتقدمة، بدِّل المفتاح الخاص بالمحرر المتقدم لتمكينه. يمكنك بعد ذلك كتابة عوامل تصفية الأحداث الخاصة بك في مربع عامل التصفية:

Screenshot of creating an event route with an advanced filter in the Azure portal.

يمكنك استخدام واجهات برمجة التطبيقات لكتابة فلاتر مخصصة. لإضافة عامل تصفية، يمكنك استخدام طلب PUT مع https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 النص الأساسي التالي:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

فلاتر المسارات المدعومة

فيما يلي عوامل تصفية المسار المدعومة.

اسم عامل التصفية	الوصف	تصفية مخطط النص	القيم المعتمدة
صحيح/ خطأ	يسمح بإنشاء مسار بدون تصفية، أو تعطيل مسار بحيث لا يتم إرسال أي أحداث	`<true/false>`	`true` = تم تمكين المسار بدون تصفية `false` = المسار معطل
النوع	نوع الحدث الذي يتدفق عبر مثيل التوأم الرقمي الخاص بك	`type = '<event-type>'`	فيما يلي قيم نوع الحدث المحتملة: `Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete` `Microsoft.DigitalTwins.Twin.Update` `Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete` `microsoft.iot.telemetry`
المصدر	اسم مثيل Azure Digital Twins	`source = '<host-name>'`	فيما يلي قيم اسم المضيف المحتملة: للإشعارات: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` للقياس عن بعد: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
الموضوع	وصف للحدث في سياق مصدر الحدث أعلاه	`subject = '<subject>'`	فيما يلي قيم الموضوع المحتملة: للإشعارات: الموضوع هو `<twin-ID>` أو تنسيق URI للموضوعات، والتي يتم تحديدها بشكل فريد بواسطة أجزاء أو معرفات متعددة: `<twin-ID>/relationships/<relationship-ID>` بالنسبة للقياس عن بعد: يكون الموضوع هو مسار المكون (إذا كان القياس عن بعد منبعثا من مكون مزدوج)، مثل `comp1.comp2`. إذا لم ينبعث القياس عن بعد من أحد المكونات، فسيكون حقل الموضوع الخاص به فارغا.
مخطط البيانات	معرف طراز DTDL	`dataschema = '<model-dtmi-ID>'`	للقياس عن بعد: مخطط البيانات هو معرف طراز التوأم أو المكون الذي يرسل القياس عن بعد. على سبيل المثال، `dtmi:example:com:floor4;2` بالنسبة للإشعارات (إنشاء/حذف): يمكن الوصول إلى مخطط البيانات في نص الإشعارات على العنوان `$body.$metadata.$model`التالي: . بالنسبة للإشعارات (التحديث): يمكن الوصول إلى مخطط البيانات في نص الإشعارات على العنوان التالي: `$body.modelId`
نوع المحتوى	نوع المحتوى لقيمة البيانات	`datacontenttype = '<content-type>'`	نوع المحتوى هو `application/json`
إصدار المواصفات	إصدار مخطط الحدث الذي تستخدمه	`specversion = '<version>'`	يجب أن يكون `1.0`الإصدار . تشير هذه القيمة إلى الإصدار 1.0 من مخطط CloudEvents
هيئة الإخطار	الإشارة إلى أي خاصية في `data` حقل الإشعار	`$body.<property>`	راجع إشعارات الأحداث للحصول على أمثلة للإشعارات. يمكن الرجوع إلى أي خاصية في الحقل `data` باستخدام `$body`

ملاحظة

لا يدعم Azure Digital Twins حاليا تصفية الأحداث استنادا إلى الحقول داخل صفيف. يتضمن ذلك التصفية على الخصائص داخل patch قسم من إشعار تغيير التوأم الرقمي.

يتم دعم أنواع البيانات التالية كقيم يتم إرجاعها من خلال مراجع للبيانات أعلاه:

نوع البيانات	مثال
سلسلة	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
عدد صحيح	`$body.errorCode > 200`
مزدوج	`$body.temperature <= 5.5`
قيمة منطقية	`$body.poweredOn = true`
خالٍ	`$body.prop != null`

يتم دعم العوامل التالية عند تحديد عوامل تصفية المسار:

العائلة	المشغلون	مثال
المنطقية	و، أو، ()	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
المقارنة	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

يتم دعم الوظائف التالية عند تحديد عوامل تصفية المسار:

الوظيفة	الوصف	مثال
STARTS_WITH(x,y)	ترجع هذه الدالة true إذا كانت القيمة `x` تبدأ بالسلسلة `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x,y)	ترجع هذه الدالة true إذا انتهت القيمة `x` بالسلسلة `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
تحتوي على (س، ص)	ترجع هذه الدالة true إذا كانت القيمة `x` تحتوي على السلسلة `y`.	`CONTAINS(subject, '<twin-ID>')`

عند تنفيذ أو تحديث عامل تصفية، قد يستغرق التغيير بضع دقائق لينعكس في تدفقات البيانات.

مراقبة مسارات الأحداث

يمكن عرض مقاييس التوجيه مثل العدد والكمون ومعدل الفشل في مدخل Azure.

من الصفحة الرئيسية للبوابة الإلكترونية، ابحث عن مثيل Azure Digital Twins لسحب تفاصيله. حدد خيار المقاييس من قائمة التنقل في مثيل Azure Digital Twins على اليمين لإظهار صفحة المقاييس .

Screenshot showing the metrics page for Azure Digital Twins.

من هنا، يمكنك عرض المقاييس الخاصة بالمثيل وإنشاء طرق عرض مخصصة.

لمزيد من المعلومات حول عرض مقاييس Azure Digital Twins، راجع المراقبة باستخدام المقاييس.

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

اقرأ عن الأنواع المختلفة من رسائل الأحداث التي يمكنك تلقيها:

إشعارات الأحداث

إدارة نقاط النهاية والمسارات في Azure Digital Twins

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

المتطلبات الأساسية

إعداد البيئة الخاصة بك لـ Azure CLI

قم بإنشاء نقطة نهاية لـ Azure Digital Twins

المتطلب السابق: إنشاء موارد نقطة النهاية

أنشئ نقطة النهاية

إنشاء نقطة نهاية بأحرف ميتة

إعداد موارد التخزين

إنشاء رمز SAS مميز

إنشاء نقطة نهاية بالأحرف الميتة

مخطط تخزين الرسائل

إنشاء مسار الحدث

أحداث التصفية

استخدم الفلاتر الأساسية

استخدام الفلاتر المتقدمة

فلاتر المسارات المدعومة

مراقبة مسارات الأحداث

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