Share via

كيفية إرسال الطلبات إلى واجهات برمجة تطبيقات Azure Digital Twins باستخدام Postman

  • مقالة

إن Postman أداة اختبار REST تقدم وظائف طلب HTTP الرئيسية في حاسوب مكتبي وواجهة المستخدم الرسومية القائمة على المكونات الإضافية. يمكنك استخدامه لصياغة طلبات HTTP وإرسالها إلى واجهات برمجة تطبيقات AZURE Digital Twins REST. توضح هذه المقالة كيفية تكوين عميل Postman REST للتفاعل مع واجهات برمجة تطبيقات Azure Digital Twins. هذه المعلومات خاصة بخدمة Azure Digital Twins.

تحتوي هذه المقالة على معلومات حول الخطوات التالية:

  1. استخدم Azure CLI للحصول على رمز حامل ستستخدمه لتقديم طلبات واجهة برمجة التطبيقات في Postman.
  2. إعداد مجموعة Postman وتكوين عميل Postman REST لاستخدام الرمز المميز للحامل للمصادقة. عند إعداد المجموعة، يمكنك اختيار أي من هذين الخيارين:
    1. استيراد مجموعة مسبقة الصنع من طلبات Azure Digital Twins API.
    2. إنشاء مجموعتك الخاصة من البداية.
  3. أضف طلبات إلى مجموعتك المكونة وأرسلها إلى واجهات برمجة تطبيقات Azure Digital Twins.

يحتوي Azure Digital Twins على مجموعتين من واجهات برمجة التطبيقات التي يمكنك العمل معها: مستوى البيانات ولوحة التحكم. لمزيد من التفاصيل حول الفرق بين مجموعات واجهة برمجة التطبيقات هذه، راجع واجهات برمجة تطبيقات Azure Digital Twins وSDKs. تحتوي هذه المقالة على معلومات لكل من مجموعتي API.

المتطلبات الأساسية

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

إعداد مثيل Azure Digital Twins

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

بعد إعداد المثيل الخاص بك، دون اسم مضيف المثيل. يمكنك العثور على اسم المضيف في بوابة Azure.

تنزيل Postman

بعد ذلك، قم بتنزيل إصدار سطح المكتب من عميل Postman.

الحصول على الرمز المميز للحامل

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

هناك عدة طرق ممكنة للحصول على هذا الرمز المميز. تستخدم هذه المقالة Azure CLI لتسجيل الدخول إلى حساب Azure الخاص بك والحصول على رمز مميز.

إذا كان لديك Azure CLI مثبت محليا، يمكنك بدء موجه أوامر على جهازك لتشغيل الأوامر التالية. وإلا، يمكنك فتح نافذة Azure Cloud Shell في المتصفح وتشغيل الأوامر هناك.

  1. أولا، تأكد من تسجيل الدخول إلى Azure باستخدام بيانات الاعتماد المناسبة، عن طريق تشغيل هذا الأمر:

    az login

  2. بعد ذلك، استخدم الأمر az account get-access-token للحصول على رمز حامل مع الوصول إلى خدمة Azure Digital Twins. في هذا الأمر، ستمرر معرف المورد لنقطة نهاية خدمة Azure Digital Twins، من أجل الحصول على رمز وصول يمكنه الوصول إلى موارد Azure Digital Twins.

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

    للحصول على رمز مميز لاستخدامه مع واجهات برمجة تطبيقات مستوى البيانات، استخدم القيمة الثابتة التالية لسياق الرمز المميز: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. هذه القيمة هي معرف المورد لنقطة نهاية خدمة Azure Digital Twins.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    إشعار

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

  3. انسخ قيمة accessToken في النتيجة، واحفظها لاستخدامها في القسم التالي. هذه القيمة هي قيمة الرمز المميز التي ستقدمها إلى Postman لتخويل طلباتك.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

تلميح

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

بعد ذلك، ستقوم بإعداد Postman لاستخدام هذا الرمز المميز لتقديم طلبات واجهة برمجة التطبيقات إلى Azure Digital Twins.

حول مجموعات Postman

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

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

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

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

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

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

  1. من نافذة Postman الرئيسية، حدد الزر استيراد . Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. في نافذة Import التالية، حدد Link وأدخل عنوان URL التالي: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. ثم حدد استيراد للتأكيد.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

يمكن الآن رؤية المجموعة التي تم استيرادها حديثًا من عرض ساعي البريد الرئيسي في علامة تبويب المجموعات.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

تلميح

لاستيراد المجموعة الكاملة من استدعاءات واجهة برمجة التطبيقات لإصدار معين من واجهات برمجة تطبيقات Azure Digital Twins (بما في ذلك وحدة التحكم أو مستوى البيانات)، يمكنك أيضا استيراد ملفات Swagger كمجموعات. للحصول على ارتباطات إلى ملفات Swagger لمستوى التحكم وواجهات برمجة تطبيقات مستوى البيانات، راجع واجهات برمجة تطبيقات Azure Digital Twins وSDKs.

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

تكوين التخويل

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

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

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

  1. في مربع الحوار تحرير لمجموعتك، تأكد من أنك على علامة التبويب التخويل .

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. تعيين النوع إلى OAuth 2.0 ولصق رمز الوصول المميز في مربع رمز الوصول المميز. يجب استخدام الرمز المميز الصحيح لنوع واجهة برمجة التطبيقات التي تستخدمها، حيث توجد رموز مميزة مختلفة لواجهات برمجة تطبيقات مستوى البيانات مقابل واجهات برمجة التطبيقات لمستوى التحكم. حدد حفظ.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    تلميح

    يمكنك اختيار تشغيل مشاركة الرمز المميز إذا كنت تريد تخزين الرمز المميز مع الطلب على سحابة Postman، ومن المحتمل أن تشارك الرمز المميز الخاص بك مع الآخرين.

التكوين الآخر

يمكنك مساعدة المجموعة في الاتصال بسهولة بموارد Azure Digital Twins عن طريق تعيين بعض المتغيرات المقدمة مع المجموعة. عندما تتطلب العديد من الطلبات في مجموعة نفس القيمة (مثل اسم المضيف لمثيل Azure Digital Twins)، يمكنك تخزين القيمة في متغير ينطبق على كل طلب في المجموعة. تأتي مجموعة Azure Digital Twins مع متغيرات تم إنشاؤها مسبقا يمكنك تعيينها على مستوى المجموعة.

  1. لا يزال في مربع حوار التحرير لمجموعتك، انتقل إلى علامة التبويب المتغيرات .

  2. استخدم الجدول التالي لتعيين قيم المتغيرات في المجموعة:

    المتغير مجموعة واجهة برمجة التطبيقات ‏‏الوصف
    digitaltwins-hostname خطة البيانات اسم المضيف لمثيل Azure Digital Twins. يمكنك العثور على هذه القيمة في صفحة النظرة العامة للمثيل الخاص بك في المدخل.
    subscriptionId وحدة التحكم معرّف اشتراك Azure.
    digitalTwinInstance وحدة التحكم اسم مثيل Azure Digital Twins.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. إذا كانت مجموعتك تحتوي على متغيرات إضافية، فاملأ هذه القيم واحفظها أيضا.

  4. حدد حفظ.

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

استكشاف الطلبات

بعد ذلك، استكشف الطلبات داخل مجموعة Azure Digital Twins API. يمكنك توسيع المجموعة لعرض الطلبات التي تم إنشاؤها مسبقا (تم فرزها حسب فئة العملية).

تتطلب الطلبات المختلفة معلومات مختلفة حول المثيل الخاص بك وبياناته. لمشاهدة جميع المعلومات المطلوبة لصياغة طلب معين، ابحث عن تفاصيل الطلب في الوثائق المرجعية ل Azure Digital Twins REST API.

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

  1. حدده من القائمة لعرض تفاصيله القابلة للتعديل.

  2. تم تكوين معظم الطلبات في مجموعة العينة مسبقا للتشغيل دون إجراء أي تغييرات أخرى.

  3. تظهر لقطة الشاشة التالية DigitalTwinModels Add API. في علامة التبويب Body ، يمكنك مشاهدة حمولة JSON التي تحدد النموذج الجديد لإضافته:

  4. املأ قيم المتغيرات المدرجة في علامة التبويب Params ضمن Path Variables.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. لتشغيل الطلب، استخدم الزر إرسال .

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

إنشاء مجموعتك الخاصة

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

إنشاء مجموعة Postman

  1. لإنشاء مجموعة، حدد الزر جديد في نافذة Postman الرئيسية.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    اختر نوعا من المجموعات.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. يتم فتح علامة تبويب. املأ تفاصيل المجموعة الجديدة. حدد أيقونة تحرير بجوار الاسم الافتراضي للمجموعة (مجموعة جديدة) لاستبدالها بالاسم الذي تختاره.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

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

تكوين التخويل

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

  1. لا يزال في مربع حوار التحرير لمجموعتك الجديدة، انتقل إلى علامة التبويب التخويل .

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. قم بتعيين Type إلى OAuth 2.0، والصق رمز الوصول المميز في مربع Access Token، وحدد Save.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

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

يمكن رؤية المجموعة الجديدة من طريقة عرض Postman الرئيسية، في علامة التبويب المجموعات.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

إضافة طلب فردي

الآن بعد إعداد مجموعتك، يمكنك إضافة طلباتك الخاصة إلى واجهات برمجة تطبيقات Azure Digital Twin.

  1. لإنشاء طلب، استخدم الزر جديد مرة أخرى.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    اختر نوع الطلب.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

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

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

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

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

تعيين تفاصيل الطلب

لتقديم طلب Postman إلى أحد واجهات برمجة تطبيقات Azure Digital Twins، ستحتاج إلى عنوان URL لواجهة برمجة التطبيقات ومعلومات حول التفاصيل التي تتطلبها. يمكنك العثور على هذه المعلومات في الوثائق المرجعية ل Azure Digital Twins REST API.

لمتابعة استعلام مثال، ستستخدم هذه المقالة واجهة برمجة تطبيقات استعلام Azure Digital Twins للاستعلام عن جميع التوائم الرقمية في مثيل.

  1. احصل على عنوان URL للطلب واكتب من الوثائق المرجعية. بالنسبة لواجهة برمجة تطبيقات الاستعلام، هذا هو POSThttps://digitaltwins-host-name/query?api-version=2020-10-31 حاليا.

  2. في Postman، قم بتعيين نوع الطلب وأدخل عنوان URL للطلب، واملأ العناصر النائبة في عنوان URL كما هو مطلوب. استخدم اسم مضيف المثيل الخاص بك من قسم المتطلبات الأساسية.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. تحقق من أن المعلمات المعروضة للطلب في علامة التبويب Params تطابق تلك الموضحة في الوثائق المرجعية. بالنسبة لهذا الطلب في Postman، تم ملء المعلمة api-version تلقائيا عند إدخال عنوان URL للطلب في الخطوة السابقة. بالنسبة لواجهة برمجة تطبيقات الاستعلام، هذه هي المعلمة المطلوبة الوحيدة، لذلك يتم تنفيذ هذه الخطوة.

  4. في علامة التبويب Authorization ، قم بتعيين النوع إلى Inherit auth من الأصل. يشير هذا إلى أن هذا الطلب سيستخدم التخويل الذي قمت بإعداده مسبقا للمجموعة بأكملها.

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

  6. تحقق من أن النص الموضح للطلب في علامة التبويب Body يطابق الاحتياجات الموضحة في الوثائق المرجعية. بالنسبة لواجهة برمجة تطبيقات الاستعلام، يلزم وجود نص JSON لتوفير نص الاستعلام. فيما يلي مثال لهذا الطلب الذي يستعلم عن جميع التوائم الرقمية في المثيل:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    لمزيد من المعلومات حول صياغة استعلامات Azure Digital Twins، راجع الاستعلام عن الرسم البياني المزدوج.

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

  8. استخدم الزر إرسال لإرسال طلبك المكتمل. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

بعد إرسال الطلب، ستظهر تفاصيل الاستجابة في نافذة Postman أسفل الطلب. يمكنك عرض رمز حالة الاستجابة وأي نص أساسي.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

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

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

لمعرفة المزيد حول واجهات برمجة التطبيقات Digital Twins، اقرأ واجهات برمجة تطبيقات Azure Digital Twins وSDKs، أو اعرض الوثائق المرجعية لواجهات برمجة تطبيقات REST.