الوثائق المرجعية ل 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 ومعلومات نظرة عامة على واجهة برمجة التطبيقات

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

نماذج Swagger المدرجة في أسفل واجهة مستخدم Swagger

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

توسعت نماذج Swagger لقراءة محتويات النماذج

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

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

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

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

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

نقاط نهاية Swagger المعروضة في واجهة مستخدم Swagger

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

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

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

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

زر

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

Swagger Try it out result example

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

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

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

مثال استجابة Swagger JSON

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

إذن Swagger OAuth 2.0

ملاحظة

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

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

    تسجيل عنوان URL لإعادة توجيه Swagger في AAD

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    
    الاسم استبدال بـ مثال
    YOUR_SWAGGER_URL تم العثور على عنوان URL لوثائق Management REST API في المدخل https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger
  3. حدد خانة الاختيار ضمنية منح>الوصول إلى الرموز المميزة للسماح باستخدام تدفق المنح الضمني OAuth 2.0. حدد تكوين، ثم حفظ.

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

بعد إكمال تسجيل Azure Active Directory:

  1. حدد الزر Authorize في صفحة swagger.

    حدد زر تفويض Swagger

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

    حقل swagger client_id

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

    نموذج إعادة توجيه Swagger

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

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