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

يحتوي Visual Studio 2022 على دعم للملفات .http ، والتي يمكن استخدامها لإنشاء طلبات HTTP وتخزينها وإرسالها مباشرة من التطبيق. استخدام هذه الوظيفة من Visual Studio هو إحدى الطرق لصياغة طلبات HTTP وإرسالها إلى واجهات برمجة تطبيقات AZURE Digital Twins REST. توضح هذه المقالة كيفية إعداد .http ملف في Visual Studio يمكنه الواجهة مع واجهات برمجة تطبيقات Azure Digital Twins.

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

1. إعداد مشروع وملف .http Visual Studio، مع المتغيرات التي تمثل مثيل Azure Digital Twins.
2. استخدم Azure CLI للحصول على رمز مميز للحامل يمكنك استخدامه لتقديم طلبات واجهة برمجة التطبيقات في Visual Studio.
3. استخدم وثائق Azure Digital Twins REST API كمورد لصياغة الطلبات في .http الملف، وإرسالها إلى واجهات برمجة تطبيقات Azure Digital Twins.

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

لمزيد من المعلومات حول .http دعم الملفات في Visual Studio، راجع استخدام ملفات .http في Visual Studio 2022.

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

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

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

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

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

تنزيل Visual Studio 2022

بعد ذلك، قم بتنزيل Visual Studio 2022. تأكد من تضمين حمل عمل ASP.NET وتطوير الويب في التثبيت الخاص بك.

إعداد مشروع Visual Studio

في هذا القسم، يمكنك إعداد المشروع في Visual Studio الذي سيتم استخدامه لصياغة طلبات HTTP.

افتح Visual Studio على جهازك، وأنشئ مشروعا جديدا. استخدم قالب مشروع ASP.NET Core Empty.

اتبع الإرشادات الواردة في إنشاء ملف .http لإنشاء ملف جديد .http في مشروعك.

إضافة المتغيرات

بعد ذلك، أضف بعض المتغيرات في أعلى الملف الذي .http سيتم استخدامه للاتصال بمورد Azure Digital Twins.

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

مستوى البيانات

أضف المتغيرات التالية لطلبات مستوى البيانات. هناك عنصر نائب واحد لاسم المضيف لمثيل Azure Digital Twins (ينتهي في digitaltwins.azure.net).

@hostName=<host-name-of-your-Azure-Digital-Twins-instance>
@DPversion=2023-10-31

وحدة التحكم

أضف المتغيرات التالية لطلبات وحدة التحكم. تحتوي على عناصر نائبة لقيم الموارد الخاصة بك.

@instance=<name-of-your-Azure-Digital-Twins-instance>
@subscription=<ID-of-your-Azure-subscription>
@resourceGroup=<resource-group>
@CPversion=2023-01-31

إضافة الرمز المميز للحامل

الآن بعد أن قمت بإعداد مثيل Azure Digital Twins ومشروع Visual Studio، تحتاج إلى الحصول على رمز حامل يمكن أن تستخدمه طلبات HTTP للتخويل مقابل واجهات برمجة تطبيقات 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
   

   وحدة التحكم

   للحصول على رمز مميز لاستخدامه مع واجهات برمجة تطبيقات مستوى التحكم، استخدم القيمة التالية لسياق الرمز المميز: https://management.azure.com/.

   az account get-access-token --resource https://management.azure.com/
   

   إشعار

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

3. انسخ قيمة accessToken في النتيجة. هذه القيمة هي قيمة الرمز المميز التي ستقوم بلصقها في Visual Studio لتخويل طلباتك.

   

تلميح

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

إضافة رمز مميز إلى .http الملف

في ملفك .http في Visual Studio، أضف متغيرا آخر يحتوي على قيمة الرمز المميز الخاص بك.

مستوى البيانات

@token=<paste-data-plane-token>

يجب أن تبدو المتغيرات الخاصة بك الآن مثل هذا:

وحدة التحكم

@token=<paste-control-plane-token>

يجب أن تبدو المتغيرات الخاصة بك الآن مثل هذا:

إضافة طلبات

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

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

ستستخدم هذه المقالة DigitalTwins Update API من مستوى البيانات كمثال.

1. إضافة قالب طلب: انسخ طلب HTTP الموضح في الوثائق المرجعية.

   

   في Visual Studio، الصق الطلب في سطر جديد أسفل المتغيرات في الملف الخاص بك .http .

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

   إشعار

   بالنسبة لطلبات مستوى البيانات، digitaltwins-hostname هي أيضا معلمة. استبدل هذا {{hostName}} باستخدام قيمة متغير اسم المضيف.

   فيما يلي كيفية ظهور هذه الخطوة في طلب مثال:

   

3. إضافة تخويل: أضف السطر التالي (تماما كما هو مكتوب) أسفل الطلب مباشرة، لتحديد المصادقة مع متغير الرمز المميز للحامل.

   Authorization: Bearer {{token}}
   

   فيما يلي كيفية ظهور هذه الخطوة في طلب مثال:

   

4. إضافة عناوين إضافية: انظر إلى قسم عنوان الطلب في الوثائق المرجعية لمعرفة قيم الرأس التي يمكن أن تصاحب الطلب. قد تحتاج أيضا إلى تضمين رؤوس HTTP التقليدية مثل Content-Type. أضف كل رأس على سطره الخاص بالتنسيق HeaderName: Value. لمزيد من التفاصيل، راجع طلب الرؤوس.

   فيما يلي كيفية ظهور هذه الخطوة في طلب مثال:

   

5. إضافة نص: انظر إلى قسم نص الطلب في الوثائق المرجعية لمعرفة معلومات النص الأساسي التي قد يحتاجها الطلب. أضف نص الطلب بعد سطر فارغ. لمزيد من التفاصيل، راجع نص الطلب.

   فيما يلي كيفية ظهور هذه الخطوة في طلب مثال:

6. عندما يكون الطلب جاهزا، حدد Send request أعلى الطلب لإرساله.

   

يجلب Visual Studio جزءا مع تفاصيل الاستجابة. انظر إلى قسم الردود في الوثائق المرجعية لتفسير رمز الحالة وأي بيانات في نص الاستجابة.

إضافة طلبات إضافية

لإضافة المزيد من الطلبات إلى .http الملف، افصلها مع ### كمحدد.

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

لمزيد من التفاصيل حول إرسال الطلبات مع .http الملفات في Visual Studio، بما في ذلك تفاصيل بناء الجملة والسيناريوهات المتقدمة، راجع استخدام ملفات .http في Visual Studio 2022.

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