الوثائق المرجعية ل Azure Digital Twins Swagger
هام
تم إصدار إصدار جديد من خدمة Azure Digital Twins. في ضوء الإمكانات الموسعة للخدمة الجديدة، تم إيقاف خدمة Azure Digital Twins الأصلية (الموضحة في مجموعة الوثائق هذه).
لعرض وثائق الخدمة الجديدة، تفضل بزيارة وثائق Azure Digital Twins النشطة.
يتضمن كل مثيل Azure Digital Twins تم توفيره وثائقه المرجعية الخاصة ب Swagger التي تم إنشاؤها تلقائيا.
يوحد Swagger أو OpenAPI معلومات واجهة برمجة التطبيقات المعقدة في مورد مرجعي تفاعلي وغير محدد اللغة. يوفر Swagger مواد مرجعية هامة حول حمولات JSON وأساليب HTTP ونقاط النهاية المحددة لاستخدامها لتنفيذ العمليات مقابل واجهة برمجة التطبيقات.
ملخص Swagger
يوفر Swagger ملخصا تفاعليا لواجهة برمجة التطبيقات الخاصة بك، والذي يتضمن:
- معلومات واجهة برمجة التطبيقات ونموذج الكائن.
- نقاط نهاية REST API التي تحدد حمولات الطلب المطلوبة والرؤوس والمعلمات ومسارات السياق وأساليب HTTP.
- اختبار وظائف واجهة برمجة التطبيقات.
- مثال على معلومات الاستجابة المستخدمة للتحقق من صحة استجابات HTTP وتأكيدها.
- معلومات رمز الخطأ.
Swagger هو أداة مريحة للمساعدة في تطوير واختبار المكالمات التي تم إجراؤها إلى واجهات برمجة تطبيقات Azure Digital Twins Management.
تلميح
يتم توفير معاينة التسلل Swagger لإظهار مجموعة ميزات واجهة برمجة التطبيقات. تتم استضافته في docs.westcentralus.azuresmartspaces.net/management/swagger.
يمكنك الوصول إلى وثائق Management API Swagger التي تم إنشاؤها على:
https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
| الاسم | استبدال بـ |
|---|---|
| YOUR_INSTANCE_NAME | اسم مثيل Azure Digital Twins |
| YOUR_LOCATION | منطقة الخادم التي تتم استضافة المثيل عليها |
مادة مرجعية
توفر المواد المرجعية Swagger التي تم إنشاؤها تلقائيا نظرة عامة سريعة على المفاهيم الهامة، ونقاط نهاية واجهة برمجة تطبيقات الإدارة المتاحة، ووصفا لكل نموذج عنصر للمساعدة في التطوير والاختبار.
يصف ملخص موجز واجهة برمجة التطبيقات.
يتم أيضا سرد نماذج عناصر واجهة برمجة تطبيقات الإدارة.
يمكنك تحديد كل نموذج عنصر مدرج للحصول على ملخص أكثر تفصيلا للسمات الرئيسية.
نماذج كائن Swagger التي تم إنشاؤها ملائمة لقراءة جميع كائنات Azure Digital Twins وواجهات برمجة التطبيقات المتوفرة. يمكن للمطورين استخدام هذا المورد عند إنشاء حلول على Azure Digital Twins.
ملخص نقطة النهاية
يوفر Swagger أيضا نظرة عامة شاملة على جميع نقاط النهاية التي تشكل واجهات برمجة تطبيقات الإدارة.
تتضمن كل نقطة نهاية مدرجة أيضا معلومات الطلب المطلوبة، مثل:
- المعلمات المطلوبة.
- أنواع بيانات المعلمات المطلوبة.
- أسلوب HTTP للوصول إلى المورد.
حدد كل مورد لعرض محتوياته الإضافية للحصول على نظرة عامة أكثر تفصيلا.
استخدام Swagger لاختبار نقاط النهاية
إحدى الوظائف القوية التي يوفرها Swagger هي القدرة على اختبار نقطة نهاية واجهة برمجة التطبيقات مباشرة من خلال واجهة مستخدم الوثائق.
بعد تحديد نقطة نهاية معينة، سيتم عرض الزر Try it out .
قم بتوسيع هذا القسم لإظهار حقول الإدخال لكل معلمة مطلوبة واختيارية. أدخل القيم الصحيحة، وحدد Execute.
بعد تنفيذ الاختبار، يمكنك التحقق من صحة بيانات الاستجابة.
بيانات استجابة Swagger
تتضمن كل نقطة نهاية مدرجة أيضا بيانات نص الاستجابة للتحقق من صحة التطوير والاختبارات. تتضمن هذه الأمثلة رموز الحالة وJSON لطلبات HTTP الناجحة.
تتضمن الأمثلة أيضا رموز الخطأ للمساعدة في تصحيح الأخطاء أو تحسين الاختبارات الفاشلة.
إذن Swagger OAuth 2.0
ملاحظة
- سيكون لمدير المستخدم الذي أنشأ مورد Azure Digital Twins تعيين دور مسؤول الفضاء وسيكون قادرا على إنشاء تعيينات أدوار إضافية للمستخدمين الآخرين. يمكن تفويض هؤلاء المستخدمين وأدوارهم باستدعاء واجهات برمجة التطبيقات.
اتبع الخطوات الواردة في Quickstart لإنشاء وتكوين تطبيق Azure Active Directory. بدلا من ذلك، يمكنك إعادة استخدام تسجيل تطبيق موجود.
أضف عنوان URI لإعادة التوجيه التالي إلى تسجيل تطبيق Azure Active Directory:
https://YOUR_SWAGGER_URL/ui/oauth2-redirect-htmlالاسم استبدال بـ مثال YOUR_SWAGGER_URL تم العثور على عنوان URL لوثائق Management REST API في المدخل https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swaggerحدد خانة الاختيار ضمنية منح>الوصول إلى الرموز المميزة للسماح باستخدام تدفق المنح الضمني OAuth 2.0. حدد تكوين، ثم حفظ.
انسخ معرف العميل لتطبيق Azure Active Directory.
بعد إكمال تسجيل Azure Active Directory:
حدد الزر Authorize في صفحة swagger.
الصق معرف التطبيق في حقل client_id .
سيتم إعادة توجيهك بعد ذلك إلى مشروط النجاح التالي.
لمعرفة المزيد حول طلبات الاختبار التفاعلي المحمية بواسطة OAuth 2.0، اقرأ الوثائق الرسمية.
الخطوات التالية
لقراءة المزيد حول نماذج عناصر Azure Digital Twins والرسم البياني للذكاء المكاني، اقرأ فهم نماذج كائن Azure Digital Twins.
لمعرفة كيفية المصادقة باستخدام واجهة برمجة تطبيقات الإدارة، اقرأ المصادقة باستخدام واجهات برمجة التطبيقات.