إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
تتناول هذه المقالة خطوات إعداد مثيل Azure Digital Twins جديد، بما في ذلك إنشاء المثيل وإعداد المصادقة. بعد إكمال هذه المقالة، سيكون لديك مثيل Azure Digital Twins جاهز لبدء البرمجة مقابله.
يتكون الإعداد الكامل لمثيل Azure Digital Twins الجديد من جزأين:
- إنشاء المثيل.
- إعداد أذونات وصول المستخدم: يحتاج مستخدمو Azure إلى أن يكون لديهم دور مالك بيانات Azure Digital Twins على مثيل Azure Digital Twins ليكونوا قادرين على إدارته وبياناته. في هذه الخطوة، تقوم بصفتك مالك/مسؤول اشتراك Azure بتعيين هذا الدور للشخص الذي يدير مثيل Azure Digital Twins. قد يكون هذا الشخص هو نفسه أو شخصا آخر في مؤسستك.
هام
لإكمال هذه المقالة الكاملة وإعداد مثيل قابل للاستخدام، تحتاج إلى أذونات لإدارة كل من الموارد ووصول المستخدم على اشتراك Azure. يمكن لأي شخص قادر على إنشاء موارد على الاشتراك إكمال الخطوة الأولى، ولكن الخطوة الثانية تتطلب أذونات إدارة وصول المستخدم (أو تعاون شخص ما مع هذه الأذونات). يمكنك قراءة المزيد حول الأذونات المطلوبة في قسم المتطلبات الأساسية: الأذونات المطلوبة لخطوة إذن وصول المستخدم.
المتطلبات الأساسية
استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع بدء استخدام Azure Cloud Shell.
إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.
إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات تسجيل الدخول الأخرى، راجع المصادقة على Azure باستخدام Azure CLI.
عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات حول الملحقات، راجع استخدام الملحقات وإدارتها باستخدام Azure CLI.
يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.
إعداد جلسة عمل CLI
لبدء العمل مع Azure Digital Twins في CLI، أول شيء يجب القيام به هو تسجيل الدخول وتعيين سياق CLI إلى اشتراكك في هذه الجلسة. قم بتشغيل هذه الأوامر في نافذة CLI:
az login
az account set --subscription "<your-Azure-subscription-ID>"
تلميح
يمكنك أيضا استخدام اسم اشتراكك بدلا من المعرف في الأمر السابق.
إذا كنت تستخدم هذا الاشتراك مع Azure Digital Twins للمرة الأولى، فقم بتشغيل الأمر التالي للتسجيل في مساحة اسم Azure Digital Twins. (إذا لم تكن متأكدا، فلا بأس من تشغيله مرة أخرى حتى إذا قمت بتشغيله في وقت ما في الماضي.)
az provider register --namespace 'Microsoft.DigitalTwins'
بعد ذلك، أضف ملحق Microsoft Azure IoT ل Azure CLI، لتمكين الأوامر للتفاعل مع Azure Digital Twins وخدمات IoT الأخرى. شغل هذا الأمر للتأكد من أن لديك أحدث إصدار من الملحق:
az extension add --upgrade --name azure-iot
أنت الآن جاهز للعمل مع Azure Digital Twins في Azure CLI.
يمكنك التحقق من هذه الحالة عن طريق التشغيل az dt --help في أي وقت لمشاهدة قائمة بأوامر Azure Digital Twins ذات المستوى الأعلى المتوفرة.
إنشاء مثيل Azure Digital Twins
في هذا القسم، يمكنك إنشاء مثيل جديد من Azure Digital Twins باستخدام أمر CLI. تحتاج إلى توفير:
- مجموعة موارد حيث يتم نشر المثيل. إذا لم يكن لديك بالفعل مجموعة موارد موجودة في الاعتبار، يمكنك إنشاء واحدة الآن باستخدام هذا الأمر:
az group create --location <region> --name <name-for-your-resource-group> - منطقة للنشر. لمعرفة المناطق التي تدعم Azure Digital Twins، تفضل بزيارة منتجات Azure المتوفرة حسب المنطقة.
- اسم للمثيل الخاص بك. إذا كان اشتراكك يحتوي على مثيل Azure Digital Twins آخر في المنطقة التي تستخدم الاسم المحدد بالفعل، فستتم مطالبتك باختيار اسم مختلف.
استخدم هذه القيم في الأمر az dt التالي لإنشاء المثيل:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
هناك العديد من المعلمات الاختيارية التي يمكن إضافتها إلى الأمر لتحديد أشياء أخرى حول المورد أثناء الإنشاء، بما في ذلك إنشاء هوية مدارة للمثيل أو تمكين/تعطيل الوصول إلى الشبكة العامة. للحصول على قائمة كاملة بالمعلمات المدعومة، راجع الوثائق المرجعية az dt create .
إنشاء المثيل بهوية مدارة
عند تمكين هوية مدارة على مثيل Azure Digital Twins، يتم إنشاء هوية لها في معرف Microsoft Entra. ويمكن بعد ذلك استخدام هذه الهوية للمصادقة على خدمات أخرى. يمكنك تمكين هوية مدارة لمثيل Azure Digital Twins أثناء إنشاء المثيل أو في وقت لاحق على مثيل موجود.
استخدم أمر CLI التالي لنوع الهوية المدارة الذي اخترته.
أمر الهوية المعين من قبل النظام
لإنشاء مثيل Azure Digital Twins مع تمكين الهوية المعينة من قبل النظام، يمكنك إضافة معلمة --mi-system-assignedaz dt create إلى الأمر المستخدم لإنشاء المثيل. (لمزيد من المعلومات حول أمر الإنشاء، راجع وثائقه المرجعية أو الإرشادات العامة لإعداد مثيل Azure Digital Twins).
لإنشاء مثيل بهوية معينة من قبل النظام، أضف المعلمة --mi-system-assigned مثل هذا:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
أمر الهوية المعينة من قبل المستخدم
لإنشاء مثيل بهوية معينة من قبل المستخدم، قم بتوفير معرف هوية مستخدم حالية معينة باستخدام المعلمة --mi-user-assigned ، مثل هذا:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
التحقق من النجاح وجمع القيم المهمة
إذا تم إنشاء المثيل بنجاح، فإن النتيجة في CLI تبدو مثل هذا، إخراج معلومات حول المورد الذي قمت بإنشائه:
لاحظ اسم المضيف والاسم ومجموعة الموارد لمثيل Azure Digital Twins من الإخراج. هذه القيم كلها مهمة وقد تحتاج إلى استخدامها أثناء متابعة العمل مع مثيل Azure Digital Twins لإعداد المصادقة وموارد Azure ذات الصلة. إذا كان المستخدمون الآخرون يقومون بالبرمجة مقابل المثيل، يجب مشاركة هذه القيم معهم.
تلميح
يمكنك مشاهدة هذه الخصائص، جنبا إلى جنب مع جميع خصائص المثيل الخاص بك، في أي وقت عن طريق تشغيل az dt show --dt-name <your-Azure-Digital-Twins-instance>.
لديك الآن مثيل Azure Digital Twins جاهز للبدء. بعد ذلك، يمكنك منح أذونات مستخدم Azure المناسبة لإدارته.
قم بإعداد أذونات وصول المستخدم
يستخدم Azure Digital Twins معرف Microsoft Entra للتحكم في الوصول المستند إلى الدور (RBAC). وهذا يعني أنه قبل أن يتمكن المستخدم من إجراء مكالمات مستوى البيانات إلى مثيل Azure Digital Twins الخاص بك، يجب تعيين دور لهذا المستخدم بأذونات مناسبة له.
بالنسبة إلى Azure Digital Twins، هذا الدور هو مالك بيانات Azure Digital Twins. يمكنك قراءة المزيد حول الأدوار والأمان في الأمان لحلول Azure Digital Twins.
إشعار
يختلف هذا الدور عن دور مالك معرف Microsoft Entra، والذي يمكن تعيينه أيضا في نطاق مثيل Azure Digital Twins. هذان دوران متميزان للإدارة، ولا يمنح المالك حق الوصول إلى ميزات مستوى البيانات التي يتم منحها مع مالك بيانات Azure Digital Twins.
يوضح لك هذا القسم كيفية إنشاء تعيين دور لمستخدم في مثيل Azure Digital Twins، باستخدام البريد الإلكتروني لهذا المستخدم في مستأجر Microsoft Entra على اشتراك Azure الخاص بك. استنادا إلى دورك في مؤسستك، يمكنك إعداد هذا الإذن لنفسك، أو إعداده نيابة عن شخص آخر يدير مثيل Azure Digital Twins.
المتطلبات الأساسية: متطلبات الإذن
لكي تتمكن من إكمال جميع الخطوات التالية، يجب أن يكون لديك دور في اشتراكك لديه الأذونات التالية:
- إنشاء موارد Azure وإدارتها
- إدارة وصول المستخدم إلى موارد Azure (بما في ذلك منح الأذونات وتفويضها)
الأدوار الشائعة التي تفي بهذا المطلب هي المالكأو مسؤول الحسابأو مجموعة من مدير وصول المستخدمو المساهم. للحصول على شرح كامل للأدوار والأذونات، بما في ذلك الأذونات المضمنة مع الأدوار الأخرى، تفضل بزيارة أدوار Azure وأدوار Microsoft Entra وأدوار مسؤول الاشتراك الكلاسيكي في وثائق Azure RBAC.
لعرض دورك في اشتراكك، تفضل بزيارة صفحة الاشتراكات في مدخل Microsoft Azure (يمكنك استخدام هذا الارتباط أو البحث عن الاشتراكات باستخدام شريط البحث في المدخل). ابحث عن اسم الاشتراك الذي تستخدمه، واعرض دورك له في عمود دوري :
إذا وجدت أن القيمة هي Contributor أو دور آخر لا يحتوي على الأذونات المطلوبة الموضحة مسبقا، يمكنك الاتصال بالمستخدم على اشتراكك الذي لديه هذه الأذونات (مثل مالك الاشتراك أو مسؤول الحساب) والمتابعة بإحدى الطرق التالية:
- اطلب أن يكملوا خطوات تعيين الدور نيابة عنك.
- اطلب منهم رفع دورك في الاشتراك بحيث يكون لديك الأذونات للمتابعة بنفسك. يمكن أن يعتمد ما إذا كان هذا الطلب مناسبا على مؤسستك ودورك داخلها.
تعيين الدور
لمنح المستخدم إذنا لإدارة مثيل Azure Digital Twins، يجب تعيين دور مالك بيانات Azure Digital Twins داخل المثيل.
استخدم الأمر التالي لتعيين الدور. يجب على المستخدم الذي لديه أذونات كافية في اشتراك Azure تشغيل الأمر . يتطلب منك الأمر تمرير اسم المستخدم الأساسي على حساب Microsoft Entra للمستخدم الذي يجب تعيين الدور له. في معظم الحالات، تتطابق هذه القيمة مع البريد الإلكتروني للمستخدم على حساب Microsoft Entra.
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"
نتيجة هذا الأمر هي معلومات مخرجة حول تعيين الدور الذي تم إنشاؤه للمستخدم.
إشعار
إذا أرجع هذا الأمر خطأ يفيد بأن CLI لا يمكنه العثور على المستخدم أو كيان الخدمة في قاعدة بيانات الرسم البياني، فعين الدور باستخدام معرف الكائن الخاص بالمستخدم بدلا من ذلك. قد يحدث هذا للمستخدمين على حسابات Microsoft الشخصية (MSAs).
استخدم صفحة مدخل Microsoft Azure لمستخدمي Microsoft Entra لتحديد حساب المستخدم وفتح تفاصيله. انسخ معرف الكائن الخاص بالمستخدم:
ثم كرر أمر قائمة تعيين الدور باستخدام معرف الكائن الخاص بالمستخدم للمعلمة assignee في الأمر السابق.
تحقق من نجاح الإجراء
إحدى الطرق للتحقق من أنك قمت بإعداد تعيين الدور بنجاح هي عرض تعيينات الدور لمثيل Azure Digital Twins في مدخل Microsoft Azure.
انتقل إلى مثيل Azure Digital Twins في مدخل Microsoft Azure. للوصول إلى هناك، يمكنك البحث عنه في صفحة مثيلات Azure Digital Twins أو البحث في اسمه في شريط البحث في المدخل.
بعد ذلك، اعرض جميع أدوارها المعينة ضمن > دور التحكم في الوصول (IAM). يجب أن يظهر تعيين الدور في القائمة.
لديك الآن مثيل Azure Digital Twins جاهز للبدء، وأذونات معينة لإدارته.
تمكين/تعطيل الهوية المدارة للمثيل
يوضح لك هذا القسم كيفية إضافة هوية مدارة إلى مثيل Azure Digital Twins الموجود بالفعل. يمكنك أيضا تعطيل الهوية المدارة على مثيل يحتوي عليه بالفعل.
استخدم أوامر CLI التالية لنوع الهوية المدارة الذي اخترته.
أوامر الهوية المعينة من قبل النظام
الأمر لتمكين هوية معينة من قبل النظام لمثيل موجود هو نفس az dt create الأمر المستخدم لإنشاء مثيل جديد بهوية معينة من قبل النظام. بدلا من توفير اسم جديد لمثيل لإنشائه، يمكنك توفير اسم مثيل موجود بالفعل. ثم تأكد من إضافة المعلمة --mi-system-assigned .
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
لتعطيل الهوية المعينة من قبل النظام على مثيل حيث تم تمكينها حاليا، استخدم الأمر التالي لتعيين --mi-system-assigned إلى false.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
أوامر الهوية المعينة من قبل المستخدم
لتمكين هوية معينة من قبل المستخدم على مثيل موجود، قم بتوفير معرف هوية مستخدم حالية معينة في الأمر التالي:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
لتعطيل هوية معينة من قبل المستخدم على مثيل حيث تم تمكينها حاليا، قم بتوفير معرف الهوية في الأمر التالي:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
اعتبارات تعطيل الهويات المدارة
من المهم مراعاة التأثيرات التي يمكن أن تحدثها أي تغييرات في الهوية أو أدوارها على الموارد التي تستخدمها. إذا كنت تستخدم الهويات المدارة مع نقاط نهاية Azure Digital Twins أو لمحفوظات البيانات وتم تعطيل الهوية، أو تمت إزالة دور ضروري منها، يمكن أن يصبح الاتصال بنقطة النهاية أو محفوظات البيانات غير قابل للوصول ويتم تعطيل تدفق الأحداث.
لمتابعة استخدام نقطة نهاية تم إعدادها باستخدام هوية مدارة تم تعطيلها الآن، تحتاج إلى حذف نقطة النهاية وإعادة إنشائها بنوع مصادقة مختلف. قد يستغرق الأمر ما يصل إلى ساعة حتى تستأنف الأحداث التسليم إلى نقطة النهاية بعد هذا التغيير.
الخطوات التالية
اختبر استدعاءات REST API الفردية على المثيل الخاص بك باستخدام أوامر Azure Digital Twins CLI:
أو، راجع كيفية توصيل تطبيق عميل بالمثيل الخاص بك باستخدام رمز المصادقة: