مشاركة عبر

كيفية استخدام واجهات برمجة تطبيقات إدارة التوائم الرقمية من Azure

  • مقالة

هام

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

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

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

ملخص واجهة برمجة التطبيقات

تعرض القائمة التالية مكونات واجهات برمجة تطبيقات Digital Twins.

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

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

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

  • /resources: تساعدك واجهات برمجة التطبيقات هذه على إعداد الموارد، مثل مركز إنترنت الأشياء، لمثيل Digital Twins الخاص بك.

  • /الأنواع: تسمح لك واجهات برمجة التطبيقات هذه بإقران الأنواع الموسعة بكائنات Digital Twins، لإضافة خصائص محددة إلى تلك الكائنات. تسمح هذه الأنواع بسهولة تصفية الكائنات وتجميعها في واجهة المستخدم والوظائف المخصصة التي تعالج بيانات القياس عن بعد. أمثلة على الأنواع الموسعة هي DeviceType و SensorType و SensorDataType و SpaceType و SpaceSubType و SpaceBlobType وSpaceResourceType وما إلى ذلك.

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

  • /propertyKeys: يمكنك استخدام واجهات برمجة التطبيقات هذه لإنشاء خصائص مخصصة للمساحاتوالأجهزةوالمستخدمين وأجهزة الاستشعار. يتم إنشاء هذه الخصائص كأزواج مفاتيح/قيم. يمكنك تحديد نوع البيانات لهذه الخصائص عن طريق تعيين PrimitiveDataType الخاص بها. على سبيل المثال، يمكنك تعريف خاصية باسم BasicTemperatureDeltaProcessingRefreshTime من نوع uint لأجهزة الاستشعار الخاصة بك، ثم تعيين قيمة لهذه الخاصية لكل من أجهزة الاستشعار الخاصة بك. يمكنك أيضا إضافة قيود لهذه القيم أثناء إنشاء الخاصية، مثل نطاقات الحد الأدنى والحد الأقصى ، بالإضافة إلى القيم المسموح بها ك ValidationData.

  • /المطابقات: تسمح لك واجهات برمجة التطبيقات هذه بتحديد الشروط التي تريد تقييمها من بيانات جهازك الواردة. راجع هذه المقالة لمزيد من المعلومات.

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

  • /endpoints: تسمح لك واجهات برمجة التطبيقات هذه بإنشاء نقاط نهاية حتى يتمكن حل Digital Twins من التواصل مع خدمات Azure الأخرى لتخزين البيانات والتحليلات. اقرأ هذه المقالة لمزيد من المعلومات.

  • /keyStores: تتيح لك واجهات برمجة التطبيقات هذه إدارة مخازن مفاتيح الأمان للمساحات الخاصة بك. يمكن لهذه المتاجر الاحتفاظ بمجموعة من مفاتيح الأمان ، وتسمح لك باسترداد أحدث المفاتيح الصالحة بسهولة.

  • /users: تسمح لك واجهات برمجة التطبيقات هذه بربط المستخدمين بمساحاتك، وتحديد موقع هؤلاء الأفراد عند الحاجة.

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

  • /roleAssignments: تسمح لك واجهات برمجة التطبيقات هذه بربط الأدوار بكيانات مثل معرف المستخدم ومعرف الوظيفة المعرف من قبل المستخدم وما إلى ذلك. يتضمن كل تعيين دور معرف الكيان المراد إقرانه، ونوع الكيان، ومعرف الدور المراد إقرانه، ومعرف المستأجر، ومسار يحدد الحد الأعلى للمورد الذي يمكن للكيان الوصول إليه باستخدام هذا الاقتران. اقرأ هذه المقالة لمزيد من المعلومات.

التنقل في واجهة برمجة التطبيقات

تدعم واجهات برمجة تطبيقات Digital Twins التصفية والتنقل عبر الرسم البياني المكاني باستخدام المعلمات التالية:

  • spaceId: ستقوم واجهة برمجة التطبيقات بتصفية النتائج حسب معرف المساحة المحدد. بالإضافة إلى ذلك، فإن العلامة المنطقية useParentSpace قابلة للتطبيق على واجهات برمجة التطبيقات /spaces ، مما يشير إلى أن معرف المسافة المحدد يشير إلى المساحة الأصلية بدلا من المساحة الحالية.

  • minLevel و maxLevel: تعتبر مساحات الجذر في المستوى 1. المسافات ذات المساحة الأصلية في المستوى n هي في المستوى n + 1. مع تعيين هذه القيم، يمكنك تصفية النتائج على مستويات محددة. هذه قيم شاملة عند تعيينها. تعتبر الأجهزة وأجهزة الاستشعار والأشياء الأخرى في نفس مستوى أقرب مساحة لها. للحصول على كل الكائنات عند مستوى معين، قم بتعيين كل من minLevel و maxLevel إلى نفس القيمة.

  • minRelative و maxRelative: عند إعطاء هذه المرشحات ، يكون المستوى المقابل مرتبطا بمستوى معرف المساحة المحدد:

    • المستوى النسبي 0 هو نفس مستوى معرف المسافة المحدد.
    • يمثل المستوى النسبي 1 مسافات على نفس مستوى أطفال معرف المسافة المحدد. يمثل المستوى النسبي n مسافات أقل من المساحة المحددة بواسطة n مستويات.
    • يمثل المستوى النسبي -1 مسافات على نفس مستوى المساحة الأصلية للمساحة المحددة.

  • العبور: يسمح لك بالعبور في أي من الاتجاهين من معرف مسافة معين ، كما هو محدد في القيم التالية.

    • لا شيء: يتم تصفية هذه القيمة الافتراضية إلى معرف المساحة المحدد.
    • لأسفل: يتم التصفية بواسطة معرف المساحة المحدد وفروعه.
    • لأعلى: يتم ترشيح هذا بواسطة معرف المساحة المحدد وأسلافه.
    • الامتداد: يقوم هذا بتصفية جزء أفقي من الرسم البياني المكاني، على نفس مستوى معرف المسافة المحدد. هذا يحتاج إما minRelative أو maxRelative ليتم تعيين true.

أمثلة

تعرض القائمة التالية بعض الأمثلة على التنقل عبر واجهات برمجة التطبيقات / devices. لاحظ أن العنصر النائب 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 وهو المنطقة التي يتم فيها استضافة المثيل الخاص بك.

  • YOUR_MANAGEMENT_API_URL/devices?maxLevel=1 إرجاع جميع الأجهزة المتصلة بمساحات الجذر.
  • YOUR_MANAGEMENT_API_URL/devices?minLevel=2&maxLevel=4 إرجاع جميع الأجهزة المتصلة بمساحات المستويات 2 أو 3 أو 4.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId إرجاع جميع الأجهزة المتصلة مباشرة ب mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down إرجاع كافة الأجهزة المتصلة ب mySpaceId أو أحد فروعه.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true إرجاع جميع الأجهزة المرفقة بأحفاد mySpaceId، باستثناء mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&minLevel=1&minRelative=true&maxLevel=1&maxRelative=true إرجاع جميع الأجهزة المتصلة بالأطفال المباشرين ل mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Up&maxLevel=-1&maxRelative=true إرجاع جميع الأجهزة المتصلة بأحد أسلاف mySpaceId.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Down&maxLevel=5 ترجع هذه الدالة كافة الأجهزة المتصلة بأحفاد mySpaceId الموجودة في مستوى أصغر من 5 أو مساوية له.
  • YOUR_MANAGEMENT_API_URL/devices?spaceId=mySpaceId&traverse=Span&minLevel=0&minRelative=true&maxLevel=0&maxRelative=true إرجاع كافة الأجهزة المتصلة بمسافات في نفس مستوى mySpaceId.

دعم OData

تدعم معظم واجهات برمجة التطبيقات التي تعرض المجموعات، مثل استدعاء GET على/spaces، المجموعة الفرعية التالية من خيارات استعلام نظام OData العامة:

  • $filter
  • $orderby
  • $top
  • $skip - إذا كنت تنوي عرض المجموعة بأكملها ، فيجب عليك طلبها كمجموعة كاملة في مكالمة واحدة ، ثم إجراء ترحيل الصفحات في التطبيق الخاص بك.

ملاحظة

بعض خيارات OData (مثل خيارات الاستعلام $count$expand$search) غير مدعومة حاليا.

أمثلة

توضح القائمة التالية العديد من الاستعلامات باستخدام بناء جملة OData صالح:

  • YOUR_MANAGEMENT_API_URL/devices?$top=3&$orderby=Name desc
  • YOUR_MANAGEMENT_API_URL/keystores?$filter=endswith(Description,'space')
  • YOUR_MANAGEMENT_API_URL/devices?$filter=TypeId eq 2
  • YOUR_MANAGEMENT_API_URL/resources?$filter=StatusId ne 1
  • YOUR_MANAGEMENT_API_URL/users?$top=4&$filter=endswith(LastName,'k')&$orderby=LastName
  • YOUR_MANAGEMENT_API_URL/spaces?$orderby=Name desc&$top=3&$filter=substringof('Floor',Name)

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

لمعرفة بعض أنماط استعلام واجهة برمجة التطبيقات الشائعة، اقرأ كيفية الاستعلام عن واجهات برمجة تطبيقات Azure Digital Twins للمهام الشائعة.

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

لمراجعة بناء جملة OData وعوامل تشغيل المقارنة المتوفرة، اقرأ عوامل تشغيل مقارنة OData في Azure Cognitive Search.