واجهات برمجة تطبيقات Azure Digital Twins ومجموعات تطوير البرامج (SDK)

تقدم هذه المقالة نظرة عامة على واجهات برمجة تطبيقات Azure Digital Twins المتوفرة، وأساليب التفاعل معها. يمكنك إما استخدام واجهات برمجة تطبيقات REST مباشرة مع Swaggers المقترنة بها، أو من خلال SDK.

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

• واجهات برمجة التطبيقات لمستوى التحكم هي واجهات برمجة تطبيقات Azure Resource Manager (ARM)، وتغطي عمليات إدارة الموارد مثل إنشاء المثيل وحذفه.
• واجهات برمجة تطبيقات مستوى البيانات هي واجهات برمجة تطبيقات Azure Digital Twins، وتستخدم لعمليات إدارة البيانات مثل إدارة النماذج والتوائم والرسم البياني.
• تستفيد SDKs من واجهات برمجة التطبيقات الحالية للسماح بسهولة تطوير التطبيقات المخصصة التي تستفيد من Azure Digital Twins.

نظرة عامة على مستوى التحكم

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

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

فيما يلي SDKs المتوفرة حاليا لواجهات برمجة تطبيقات وحدة التحكم Azure Digital Twins.

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

نظرة عامة على مستوى البيانات

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

• DigitalTwinModels- تحتوي فئة DigitalTwinModels على واجهات برمجة التطبيقات لإدارة النماذج في مثيل Azure Digital Twins. تتضمن أنشطة الإدارة تحميل النماذج التي تم تأليفها في DTDL والتحقق من صحتها واستردادها وحذفها.
• DigitalTwins- تحتوي فئة DigitalTwins على واجهات برمجة التطبيقات التي تتيح للمطورين إنشاء التوائم الرقمية وعلاقاتهم وتعديلها وحذفها في مثيل Azure Digital Twins.
• Query - تتيح فئة الاستعلام للمطورين العثور على مجموعات من التوائم الرقمية في الرسم البياني المزدوج عبر العلاقات.
• Event Routes - تحتوي فئة مسارات الأحداث على واجهات برمجة التطبيقات لتوجيه البيانات، من خلال النظام وإلى خدمات انتقال البيانات من الخادم.
• Import Jobs - تتيح لك واجهة برمجة تطبيقات استيراد المهام إدارة إجراء طويل الأمد وغير متزامن لاستيراد النماذج والتوائم والعلاقات بشكل مجمع.
• Delete Jobs - تتيح لك واجهة برمجة تطبيقات حذف المهام إدارة إجراء طويل الأمد وغير متزامن لحذف جميع النماذج والتوائم والعلاقات في مثيل.

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

فيما يلي SDKs المتوفرة حاليا لواجهات برمجة تطبيقات مستوى بيانات Azure Digital Twins.

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

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

واجهة برمجة تطبيقات استيراد المهام هي واجهة برمجة تطبيقات مستوى بيانات تسمح لك باستيراد مجموعة من النماذج والتوائم و/أو العلاقات في استدعاء واجهة برمجة تطبيقات واحد. يتم أيضا تضمين عمليات واجهة برمجة تطبيقات مهام الاستيراد مع أوامر CLI وSDKs مستوى البيانات. يتطلب استخدام واجهة برمجة تطبيقات استيراد المهام استخدام Azure Blob Storage.

التحقق من الأذونات

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

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

تحتاج إلى أذونات الكتابة في مثيل Azure Digital Twins لفئات إجراء البيانات التالية:

• Microsoft.DigitalTwins/jobs/*
• أي عناصر رسم بياني تريد تضمينها في استدعاء الوظائف. قد يتضمن Microsoft.DigitalTwins/models/*ذلك وMicrosoft.DigitalTwins/digitaltwins/*/أو .Microsoft.DigitalTwins/digitaltwins/relationships/*

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

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

• Storage Blob Data Reader لحاوية كائن ثنائي كبير الحجم لإدخال Azure Storage
• Storage Blob Data Contributor لحاوية كائن ثنائي كبير الحجم لإخراج Azure Storage

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

تنسيق البيانات

تقبل واجهة برمجة التطبيقات إدخال معلومات الرسم البياني من ملف NDJSON ، والذي يجب تحميله إلى حاوية تخزين Azure blob. يبدأ الملف بقسم Header متبوعا بالأقسام الاختيارية Modelsو Twinsو.Relationships ليس عليك تضمين جميع أنواع بيانات الرسم البياني الثلاثة في الملف، ولكن يجب أن تتبع أي مقاطع موجودة هذا الترتيب. يمكن أن تتضمن التوائم والعلاقات التي تم إنشاؤها باستخدام واجهة برمجة التطبيقات هذه تهيئة خصائصها اختياريا.

فيما يلي نموذج لملف بيانات الإدخال لواجهة برمجة تطبيقات الاستيراد:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

بمجرد إنشاء الملف، قم بتحميله إلى كائن ثنائي كبير الحجم للكتلة في Azure Blob Storage باستخدام أسلوب التحميل المفضل لديك (بعض الخيارات هي الأمر AzCopy أو Azure CLI أو مدخل Microsoft Azure). يمكنك استخدام عنوان URL لتخزين كائن ثنائي كبير الحجم لملف NDJSON في نص استدعاء واجهة برمجة تطبيقات استيراد المهام.

تشغيل مهمة الاستيراد

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

في نص استدعاء API، يمكنك توفير عنوان URL لتخزين كائن ثنائي كبير الحجم لملف إدخال NDJSON. يمكنك أيضا توفير عنوان URL جديد لتخزين كائن ثنائي كبير الحجم للإشارة إلى المكان الذي تريد تخزين سجل الإخراج فيه بمجرد إنشاء الخدمة له.

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

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

عند اكتمال المهمة، يمكنك مشاهدة العدد الإجمالي للكيانات التي تم استيعابها باستخدام مقياس BulkOperationEntityCount.

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

الحدود والاعتبارات

ضع الاعتبارات التالية في الاعتبار أثناء العمل مع واجهة برمجة تطبيقات استيراد المهام:

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

الحذف المجمع باستخدام واجهة برمجة تطبيقات حذف المهام

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

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

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

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

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

الحدود والاعتبارات الأخرى

ضع الاعتبارات التالية في الاعتبار أثناء العمل مع واجهة برمجة تطبيقات Delete Jobs:

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

ملاحظات الاستخدام والمصادقة

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

ملاحظات واجهة برمجة التطبيقات

فيما يلي بعض المعلومات العامة لاستدعاء واجهات برمجة تطبيقات Azure Digital Twins مباشرة.

• يمكنك استخدام أداة اختبار HTTP REST لإجراء مكالمات مباشرة إلى واجهات برمجة تطبيقات Azure Digital Twins. لمزيد من المعلومات حول هذه العملية، راجع استدعاء واجهات برمجة تطبيقات Azure Digital Twins.
• لا يدعم Azure Digital Twins حاليا مشاركة الموارد عبر المنشأ (CORS). لمزيد من المعلومات حول استراتيجيات التأثير والدقة، راجع مشاركة الموارد عبر المنشأ (CORS) ل Azure Digital Twins.

فيما يلي بعض المعلومات حول المصادقة لطلبات واجهة برمجة التطبيقات.

• إحدى الطرق لإنشاء رمز حامل لطلبات Azure Digital Twins API هي باستخدام الأمر az account get-access-token CLI. للحصول على إرشادات مفصلة، راجع إضافة رمز مميز للحامل.
• تتطلب الطلبات إلى واجهات برمجة تطبيقات Azure Digital Twins مستخدما أو كيان خدمة يشكل جزءا من نفس مستأجر معرف Microsoft Entra حيث يوجد مثيل Azure Digital Twins. لمنع المسح الضار لنقاط نهاية Azure Digital Twins، يتم إرجاع الطلبات التي تحتوي على رموز الوصول المميزة من خارج المستأجر الأصلي رسالة خطأ "لم يتم العثور على 404 مجال فرعي". يتم إرجاع هذا الخطأ حتى إذا تم منح المستخدم أو كيان الخدمة مالك بيانات Azure Digital Twins أو دور قارئ بيانات Azure Digital Twins من خلال تعاون Microsoft Entra B2B . للحصول على معلومات حول كيفية تحقيق الوصول عبر عدة مستأجرين، راجع كتابة رمز مصادقة التطبيق.

ملاحظات SDK

SDK الأساسي ل Azure Digital Twins هو Azure.Core. راجع وثائق مساحة اسم Azure للرجوع إليها في البنية الأساسية SDK وأنواعها.

فيما يلي بعض المعلومات حول المصادقة باستخدام SDKs.

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

فيما يلي بعض المعلومات حول الوظائف والبيانات التي تم إرجاعها.

• يتم عرض جميع استدعاءات واجهة برمجة التطبيقات للخدمة كوظائف عضو في DigitalTwinsClient الفئة.
• توجد جميع وظائف الخدمة في إصدارات متزامنة وغير متزامنة.
• تطرح جميع وظائف الخدمة استثناء لأي حالة إرجاع تبلغ 400 أو أعلى. تأكد من التفاف المكالمات في try مقطع، ثم التقاط على الأقل RequestFailedExceptions. لمزيد من المعلومات حول هذا النوع من الاستثناء، راجع الوثائق المرجعية الخاصة به.
• ترجع Response<T> معظم أساليب الخدمة أو (Task<Response<T>> للمكالمات غير المتزامنة)، حيث T تكون فئة كائن الإرجاع لاستدعاء الخدمة. تغلف فئة الاستجابة إرجاع الخدمة وتقدم قيم الإرجاع في حقلهاValue.
• ترجع Pageable<T> أساليب الخدمة ذات النتائج المصفحة أو AsyncPageable<T> كنتائج. لمزيد من المعلومات حول Pageable<T> الفئة، راجع الوثائق المرجعية الخاصة بها؛ لمزيد من المعلومات حول AsyncPageable<T>، راجع وثائقها المرجعية.
• يمكنك تكرار النتائج المصفحة باستخدام تكرار await foreach حلقي. لمزيد من المعلومات حول هذه العملية، راجع التكرار باستخدام قوائم التعداد غير المتزامنة في C# 8.
• ترجع أساليب الخدمة كائنات مكتوبة بقوة كلما أمكن ذلك. ومع ذلك، نظرا لأن Azure Digital Twins يستند إلى نماذج تم تكوينها بشكل مخصص من قبل المستخدم في وقت التشغيل (عبر نماذج DTDL التي تم تحميلها إلى الخدمة)، فإن العديد من واجهات برمجة التطبيقات للخدمة تأخذ بيانات مزدوجة وتعيدها بتنسيق JSON.

مساعدو التسلسل في .NET (C#) SDK

مساعدو التسلسل هي وظائف مساعدة متوفرة داخل .NET (C#) SDK لإنشاء أو إلغاء تسلسل البيانات المزدوجة بسرعة للوصول إلى المعلومات الأساسية. نظرا لأن أساليب SDK الأساسية ترجع البيانات المزدوجة ك JSON بشكل افتراضي، فقد يكون من المفيد استخدام فئات المساعد هذه لتقسيم البيانات المزدوجة بشكل أكبر.

فئات المساعد المتاحة هي:

• BasicDigitalTwin: يمثل بشكل عام البيانات الأساسية لتوأم رقمي
• BasicDigitalTwinComponent: يمثل بشكل عام مكونا في Contents خصائص BasicDigitalTwin
• BasicRelationship: يمثل بشكل عام البيانات الأساسية للعلاقة
• DigitalTwinsJsonPropertyName: يحتوي على ثوابت السلسلة للاستخدام في تسلسل JSON وإلغاء تسلسل أنواع التوائم الرقمية المخصصة

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

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

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

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

راجع كيفية تقديم طلبات مباشرة إلى واجهات برمجة تطبيقات Azure Digital Twins:

• استدعاء واجهات برمجة تطبيقات Azure Digital Twins

أو، تدرب على استخدام .NET SDK عن طريق إنشاء تطبيق عميل باستخدام هذا البرنامج التعليمي:

• ترميز تطبيق العميل