Azure Digital Twins Swagger reference documentation

  • مقالة
  • قراءة خلال 3 دقائق

هام

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

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

يتضمن كل مثيل Azure Digital Twins متوفر وثائق مرجعية Swagger يتم إنشاؤها تلقائيا.

يوحد Swagger ، أو OpenAPI ، معلومات واجهة برمجة التطبيقات المعقدة في مورد مرجعي تفاعلي وغير لغوي. يوفر Swagger مادة مرجعية مهمة حول حمولات JSON وأساليب HTTP ونقاط النهاية المحددة لاستخدامها لتنفيذ العمليات مقابل واجهة برمجة التطبيقات.

ملخص Swagger

يوفر Swagger ملخصا تفاعليا لواجهة برمجة التطبيقات الخاصة بك، والذي يتضمن:

  • واجهة برمجة التطبيقات ومعلومات نموذج الكائن.
  • نقاط نهاية واجهة برمجة تطبيقات REST التي تحدد حمولات الطلب المطلوبة والرؤوس والمعلمات ومسارات السياق وأساليب HTTP.
  • اختبار وظائف واجهة برمجة التطبيقات.
  • مثال على معلومات الاستجابة المستخدمة للتحقق من صحة استجابات HTTP وتأكيدها.
  • معلومات رمز الخطأ.

Swagger هي أداة ملائمة للمساعدة في تطوير واختبار المكالمات التي يتم إجراؤها إلى واجهات برمجة تطبيقات Azure Digital Twins Management.

تلميح

يتم توفير معاينة تسلل Swagger لإظهار مجموعة ميزات واجهة برمجة التطبيقات. يتم استضافته في docs.westcentralus.azuresmartspaces.net/management/swagger.

يمكنك الوصول إلى وثائق Swagger الخاصة بواجهة برمجة تطبيقات الإدارة التي تم إنشاؤها على:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
الاسم استبدال بـ
YOUR_INSTANCE_NAME اسم مثيل Azure Digital Twins الخاص بك
YOUR_LOCATION منطقة الخادم التي تتم استضافة مثيلك عليها

المواد المرجعية

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

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

Swagger summary and API overview information

يتم أيضا سرد نماذج كائنات واجهة برمجة تطبيقات الإدارة.

Swagger models listed at bottom of Swagger UI

يمكنك تحديد كل نموذج كائن مدرج للحصول على ملخص أكثر تفصيلا للسمات الرئيسية.

Swagger models expanded to read the contents of models

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

ملخص نقطة النهاية

يوفر Swagger أيضا نظرة عامة شاملة على جميع نقاط النهاية التي تشكل واجهات برمجة تطبيقات الإدارة.

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

  • المعلمات المطلوبة.
  • أنواع بيانات المعلمات المطلوبة.
  • طريقة HTTP للوصول إلى المورد.

Swagger endpoints displayed in Swagger UI

حدد كل مورد لعرض محتوياته الإضافية للحصول على نظرة عامة أكثر تفصيلا.

استخدام Swagger لاختبار نقاط النهاية

واحدة من الوظائف القوية التي يوفرها Swagger هي القدرة على اختبار نقطة نهاية واجهة برمجة التطبيقات مباشرة من خلال واجهة مستخدم الوثائق.

بعد تحديد نقطة نهاية معينة، سيتم عرض الزر تجربتها .

Swagger Try it out button

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

Swagger Try it out result example

بعد تنفيذ الاختبار، يمكنك التحقق من صحة بيانات الاستجابة.

بيانات استجابة Swagger

تتضمن كل نقطة نهاية مدرجة أيضا بيانات نص الاستجابة للتحقق من صحة التطوير والاختبارات. تتضمن هذه الأمثلة رموز الحالة و JSON لطلبات HTTP الناجحة.

Swagger JSON response example

تتضمن الأمثلة أيضا رموز خطأ للمساعدة في تصحيح الأخطاء أو تحسين اختبارات الرسوب.

تفويض Swagger OAuth 2.0

ملاحظة

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

  1. اتبع الخطوات الواردة في " التشغيل السريع" لإنشاء تطبيق Azure Active Directory وتكوينه. بدلا من ذلك، يمكنك إعادة استخدام تسجيل تطبيق موجود.

  2. أضف عنوان URI لإعادة التوجيه التالي إلى تسجيل تطبيق Azure Active Directory:

    Register Swagger redirect url in AAD

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    الاسم استبدال بـ مثال
    YOUR_SWAGGER_URL عنوان URL لوثائق واجهة برمجة تطبيقات REST للإدارة موجود في البوابة الإلكترونية https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

  3. حدد خانة الاختيار الرموز المميزةل Implicit grantAccess> للسماح باستخدام تدفق المنحة الضمنية OAuth 2.0. حدد تكوين، ثم حفظ.

  4. انسخ معرف العميل الخاص بتطبيق Azure Active Directory.

بعد الانتهاء من تسجيل Azure Active Directory:

  1. حدد الزر تفويض في صفحة التفاخر.

    Select the Swagger authorize button

  2. الصق معرف التطبيق في حقل client_id .

    Swagger client_id field

  3. سيتم بعد ذلك إعادة توجيهك إلى طريقة النجاح التالية.

    Swagger redirect modal

لمعرفة المزيد حول طلبات الاختبار التفاعلي المحمية بواسطة OAuth 2.0، اقرأ الوثائق الرسمية.

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