إنشاء وحذف المسارات ونقاط النهاية باستخدام Azure CLI

توضح هذه المقالة كيفية إدارة مسارات Azure IoT Hub ونقاط النهاية باستخدام Azure CLI. تعرف على كيفية استخدام Azure CLI لإنشاء مسارات ونقاط نهاية لمراكز أحداث Azure وقوائم الانتظار ناقل خدمة Azure والموضوعات وتخزين Azure وCosmos DB.

لمعرفة المزيد حول كيفية عمل التوجيه في IoT Hub، راجع استخدام توجيه رسائل IoT Hub لإرسال رسائل من جهاز إلى سحابة إلى نقاط نهاية مختلفة. للتنقل عبر إعداد مسار يرسل رسائل إلى التخزين ثم الاختبار على جهاز محاكاة، راجع البرنامج التعليمي: إرسال بيانات الجهاز إلى Azure Storage باستخدام توجيه رسائل IoT Hub.

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

تستخدم الإجراءات الموضحة في المقالة الموارد التالية:

• The Azure CLI
• IoT hub
• خدمة نقطة نهاية في Azure

Azure CLI

تستخدم هذه المقالة Azure CLI للعمل مع IoT Hub وخدمات Azure الأخرى. يمكنك اختيار كيفية الوصول إلى Azure CLI:

• استخدم بيئة Bash في Azure Cloud Shell. لمزيد من المعلومات، راجع التشغيل السريع ل Bash في Azure Cloud Shell.

  

• إذا كنت تفضل تشغيل أوامر مرجع CLI محلياً قم بتثبيت CLI Azure. إذا كنت تعمل على نظام تشغيل Windows أو macOS، ففكر في تشغيل Azure CLI في حاوية Docker. لمزيد من المعلومات، راجع كيفية تشغيل Azure CLI في حاوية Docker.

  • إذا كنت تستخدم تثبيت محلي، يُرجى تسجيل الدخول إلى Azure CLI مستخدمًا أمر az login. لإنهاء عملية المصادقة، اتبع الخطوات المعروضة في جهازك. للحصول على خيارات أخرى لتسجيل دخول، راجع تسجيل الدخول باستخدام Azure CLI.

  • عندما يُطلب منك، قم بتثبيت ملحق Azure CLI عند الاستخدام لأول مرة. لمزيد من المعلومات بشأن الامتدادات، راجع استخدام امتدادات مع Azure CLI.

  • يُرجى تشغيل إصدار az للوصول إلى الإصدار والمكتبات التابعة التي تم تثبيتها. للتحديث لآخر إصدار، يُرجى تشغيل تحديث az.

IoT Hub

لديك مركز IoT في اشتراك Azure الخاص بك. إذا لم تكن لديك مركز بعد، فإنه يمكنك اتباع الخطوات الواردة في إنشاء مركز IoT.

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

تحتاج إلى خدمة Azure أخرى واحدة على الأقل لاستخدامها كنقطة نهاية للمسار. تتلقى نقطة النهاية رسائل الجهاز وسجلات الأحداث.

حدد خدمة Azure التي تريد استخدامها كنقطة نهاية لتلقي بيانات الحدث والجهاز الذي تم توجيهه: مركز أحداث أو قائمة انتظار خدمة أو موضوع أو حساب تخزين أو حاوية Cosmos DB. بالنسبة للخدمة التي تختار استخدامها، أكمل الخطوات لإنشاء خدمة نقطة نهاية.

مراكز الأحداث

1. قم بإنشاء مساحة اسم Event Hubs ومركز أحداث. لمزيد من المعلومات، راجع التشغيل السريع: إنشاء مركز أحداث باستخدام Azure CLI.

2. إنشاء قاعدة تخويل سيتم استخدامها لمنح IoT Hub الإذن لإرسال البيانات إلى مركز الأحداث.

   تلميح

   name قيمة RootManageSharedAccessKey المعلمة هي الاسم الافتراضي الذي يسمح بمطالبات الإدارة والإرسال والاستماع (الوصول). إذا كنت ترغب في تقييد المطالبات، فامنح المعلمة name اسمك الفريد الخاص وقم بتضمين العلامة --rights متبوعة بإحدى المطالبات. على سبيل المثال، --name my-name --rights Send

   az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
   

   لمزيد من المعلومات، راجع تخويل الوصول إلى Azure Event Hubs.

قائمة انتظار ناقل خدمة Microsoft Azure

1. إنشاء مساحة اسم وقائمة انتظار لـService Bus. لمزيد من المعلومات، راجع استخدام Azure CLI لإنشاء مساحة اسم ناقل خدمة Microsoft Azure وقائمة انتظار.

2. إنشاء قاعدة تخويل تمنح IoT Hub الإذن لإرسال البيانات إلى قائمة الانتظار. بالنسبة إلى name، استخدم قيمة فريدة لقاعدة التخويل الخاصة بك.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   لمزيد من خيارات قاعدة التخويل، راجع az servicebus queue authorization-rule create.

موضوع ناقل خدمة Microsoft Azure

إنشاء مساحة اسم وموضوع واشتراك لناقل خدمة Microsoft Azure. لمزيد من المعلومات، راجع استخدام Azure CLI لإنشاء موضوع ناقل خدمة Microsoft Azure والاشتراكات في الموضوع.

تخزين Azure

1. قم بإنشاء حساب تخزين. لمزيد من المعلومات، راجع إنشاء حساب تخزين.

2. إنشاء حاوية في حساب التخزين الخاص بك. لمزيد من المعلومات، راجع إدارة حاويات الكائن الثنائي كبير الحجم باستخدام Azure CLI

Cosmos DB

إنشاء حساب Cosmos DB لواجهة برمجة تطبيقات SQL وحاوية Cosmos DB. لمزيد من المعلومات، راجع إنشاء Azure Cosmos DB ل NoSQL.

إنشاء نقطة النهاية

تشير جميع مسارات IoT Hub إلى نقطة نهاية، والتي ستتلقى بيانات الجهاز والحدث التي تم توجيهها. يمكن أن يشير أكثر من مسار واحد إلى نفس نقطة النهاية. حاليا، يدعم IoT Hub نقاط النهاية لمراكز الأحداث وقوائم انتظار أو مواضيع ناقل خدمة Microsoft Azure والتخزين و Cosmos DB. يجب أن يوجد مثيل للخدمة التي تستخدمها لنقطة النهاية الخاصة بك في اشتراك Azure قبل إنشاء نقطة النهاية.

إشعار

تستخدم هذه المقالة مجموعة أوامر az iot hub message-endpoint ، والتي تم تقديمها في الإصدار 0.19.0 من ملحق azure-iot ل Azure CLI. استخدمت الإصدارات السابقة من ملحق azure-iot مجموعة أوامر az iot hub routing-endpoint ، وهي متشابهة ولا تزال مدعومة ولكنها لا تدعم إنشاء نقاط نهاية Cosmos DB.

استخدم الأمر التالي للتحديث إلى أحدث إصدار من ملحق azure-iot:

az extension update --name azure-iot

مراكز الأحداث

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

1. استخدم الأمر az eventhubs eventhub authorization-rule keys list لسرد قاعدة التخويل الخاصة بك. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   eventhub_group	مجموعة الموارد لمركز الأحداث.
   eventhub_namespace	اسم مساحة اسم "مراكز الأحداث".
   eventhub_name	اسم Event Hub.
   rule_name	اسم قاعدة التخويل لمركز الحدث. إذا قمت بنسخ المثال في المتطلبات الأساسية، فإن هذا الاسم هو RootManageSharedAccessKey.

   az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}
   

2. انسخ مركز الأحداث سلسلة الاتصال من الإخراج.

3. استخدم الأمر az iot hub message-endpoint create eventhub لإنشاء نقطة النهاية المخصصة. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء نقطة النهاية هذه.
   endpoint_name	اسم فريد لنقطة النهاية الجديدة.
   eventhub_subscription	معرف الاشتراك لمركز الحدث. يمكن ترك هذه الوسيطة إذا كان مركز الأحداث في نفس الاشتراك مثل مركز IoT.
   eventhub_group	مجموعة الموارد لمركز الأحداث. يمكن ترك هذه الوسيطة إذا كان مركز الحدث في نفس مجموعة الموارد مثل مركز IoT.
   eventhub_connection_string	سلسلة الاتصال التي نسختها من قاعدة تخويل مركز الحدث.

   az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}
   

قائمة انتظار ناقل خدمة Microsoft Azure

لإنشاء نقطة نهاية قائمة انتظار ناقل خدمة Microsoft Azure، استخدم قاعدة التخويل التي قمت بإنشائها في المتطلبات الأساسية.

1. استخدم الأمر az servicebus queue authorization-rule keys list للحصول على قائمة انتظار ناقل الخدمة سلسلة الاتصال. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   queue_group	مجموعة الموارد لقائمة انتظار ناقل خدمة Microsoft Azure.
   queue_namespace	اسم مساحة اسم قائمة انتظار ناقل خدمة Microsoft Azure.
   queue_name	اسم قائمة الانتظار.
   rule_name	اسم قاعدة التخويل لقائمة الانتظار. إذا قمت بنسخ المثال في المتطلبات الأساسية، فإن هذا الاسم هو my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. انسخ قائمة انتظار ناقل خدمة Microsoft Azure سلسلة الاتصال من الإخراج.

3. استخدم الأمر az iot hub message-endpoint create servicebus-queue لإنشاء نقطة النهاية المخصصة. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء نقطة النهاية هذه.
   endpoint_name	اسم فريد لنقطة النهاية الجديدة.
   queue_connection_string	سلسلة الاتصال التي نسختها من قاعدة تخويل قائمة انتظار ناقل خدمة Microsoft Azure.
   queue_subscription	معرف الاشتراك لقائمة انتظار ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كانت قائمة الانتظار في نفس الاشتراك مثل مركز IoT.
   queue_group	مجموعة الموارد لقائمة انتظار ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كانت قائمة الانتظار في نفس مجموعة الموارد مثل مركز IoT.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

موضوع ناقل خدمة Microsoft Azure

1. استخدم قائمة مفاتيح قاعدة تخويل موضوع az servicebus للحصول على موضوع ناقل الخدمة سلسلة الاتصال. الاسم الافتراضي لقاعدة التخويل التي تأتي مع مساحة اسم جديدة هو RootManageSharedAccessKey. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   topic_group	مجموعة الموارد لموضوع ناقل خدمة Microsoft Azure.
   topic_namespace	اسم مساحة اسم موضوع ناقل خدمة Microsoft Azure.
   topic_name	اسم الموضوع.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. انسخ موضوع ناقل خدمة Microsoft Azure سلسلة الاتصال من الإخراج.

3. استخدم الأمر az iot hub message-endpoint create servicebus-topic لإنشاء نقطة النهاية المخصصة. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء نقطة النهاية هذه.
   endpoint_name	اسم فريد لنقطة النهاية الجديدة.
   topic_connection_string	سلسلة الاتصال التي نسختها من قاعدة تخويل موضوع ناقل خدمة Microsoft Azure.
   topic_subscription	معرف الاشتراك لموضوع ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كان الموضوع في نفس الاشتراك مثل مركز IoT.
   topic_group	مجموعة الموارد لموضوع ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كان الموضوع في نفس مجموعة الموارد مثل مركز IoT.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

تخزين Azure

1. استخدم الأمر az storage account show-connection-string للحصول على سلسلة الاتصال من مورد Azure Storage لإنشاء نقطة نهاية. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   storage_group	مجموعة الموارد لحساب التخزين.
   storage_name	اسم حساب التخزين.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. انسخ حساب التخزين سلسلة الاتصال من الإخراج.

3. استخدم الأمر az iot hub message-endpoint create storage-container لإنشاء نقطة نهاية Azure Storage جديدة. بالنسبة لجميع المعلمات الأخرى، استخدم القيم للسيناريو الخاص بك. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء نقطة النهاية هذه.
   endpoint_name	اسم فريد لنقطة النهاية الجديدة.
   storage_connection_string	سلسلة الاتصال التي نسختها من أمر حساب التخزين.
   container_name	اسم الحاوية في حساب التخزين الخاص بك حيث سيتم إرسال البيانات.
   storage_subscription	معرف الاشتراك لتخزين ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كان التخزين في نفس الاشتراك مثل مركز IoT.
   storage_group	مجموعة الموارد لتخزين ناقل خدمة Microsoft Azure. يمكن ترك هذه الوسيطة إذا كان الموضوع في نفس مجموعة الموارد مثل مركز IoT.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. استخدم الأمر az cosmosdb keys list للحصول على سلسلة الاتصال من حساب قاعدة بيانات Cosmos DB.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. انسخ سلسلة الاتصال Cosmos DB من الإخراج.

3. استخدم الأمر az iot hub message-endpoint create cosmosdb-container لإنشاء نقطة النهاية المخصصة. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء نقطة النهاية هذه.
   endpoint_name	اسم فريد لنقطة النهاية الجديدة.
   cosmosdb_connection_string	سلسلة الاتصال التي نسختها من أمر حساب Cosmos DB.
   container_name	اسم الحاوية في حساب Cosmos DB الخاص بك حيث سيتم إرسال البيانات.
   database_name	اسم قاعدة البيانات في حساب Cosmos DB الخاص بك حيث سيتم إرسال البيانات.
   cosmosdb_subscription	معرف الاشتراك لحساب قاعدة بيانات Cosmos DB. يمكن ترك هذه الوسيطة إذا كانت قاعدة البيانات في نفس الاشتراك مثل مركز IoT.
   cosmosdb_group	مجموعة الموارد لحساب قاعدة بيانات Cosmos DB. يمكن ترك هذه الوسيطة إذا كانت قاعدة البيانات في نفس مجموعة الموارد مثل مركز IoT.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   إشعار

   إذا كنت تستخدم الهويات المدارة بدلا من سلسلة الاتصال، فاستخدم الأمر az cosmosdb sql role assignment create لمصادقة هويتك إلى حساب Cosmos DB.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

حذف نقطة نهاية

إذا كنت ترغب في حذف نقطة نهاية من مركز IoT، فاستخدم الأمر az iot hub message-endpoint delete . باستخدام هذا الأمر، يمكنك حذف نقطة نهاية واحدة، أو حذف جميع نقاط النهاية من نوع واحد، أو حذف جميع نقاط النهاية من لوحة الوصل.

على سبيل المثال، يحذف الأمر التالي جميع نقاط النهاية في مركز IoT الذي يشير إلى موارد التخزين:

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

إنشاء مسار IoT Hub

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

إشعار

تستخدم هذه المقالة مجموعة أوامر az iot hub message-route ، والتي تم تقديمها في الإصدار 0.19.0 من ملحق azure-iot ل Azure CLI. استخدمت الإصدارات السابقة من ملحق azure-iot مجموعة أوامر توجيه مركز az iot، وهي متشابهة ولا تزال مدعومة.

استخدم الأمر التالي للتحديث إلى أحدث إصدار من ملحق azure-iot:

az extension update --name azure-iot

1. استخدم الأمر az iot hub message-route create لإنشاء مسار IoT Hub جديد باستخدام نقطة النهاية هذه. توفير القيم التالية لمعلمات العنصر النائب:

   المعلمة	قيمة
   iothub_name	اسم مركز IoT حيث يتم إنشاء هذا المسار.
   route_name	اسم فريد للمسار الجديد.
   endpoint_name	اسم نقطة النهاية التي سيرسل المسار البيانات إليها.
   data_source	مصدر المسار. القيم المقبولة هي: deviceconnectionstateeventsأو devicejoblifecycleeventsأو devicelifecycleeventsأو devicemessagesأو invaliddigitaltwinchangeeventsأو أو .twinchangeevents

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. للتأكد من أن المسار الجديد في مركز IoT الخاص بك، استخدم الأمر az iot hub message-route list لمشاهدة جميع المسارات في مركز IoT الخاص بك:

   az iot hub message-route list --hub-name {iothub_name}
   

   يجب أن تشاهد استجابة في Azure CLI مشابهة لهذا المثال:

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

تحديث مسار IoT Hub

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

استخدم الأمر az iot hub message-route show لعرض تفاصيل المسار.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

استخدم الأمر az iot hub message-route update لتحديث خصائص المسار. على سبيل المثال، يقوم الأمر التالي بتحديث مصدر المسار.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

حذف مسار IoT Hub

استخدم الأمر az iot hub message-route delete لحذف مسار من مركز IoT.

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

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

إدارة المسار الاحتياطي

يرسل المسار الاحتياطي جميع الرسائل من devicemessages المصدر التي لا تفي بشروط الاستعلام على أي من المسارات الموجودة إلى نقطة النهاية المضمنة.

استخدم الأمر az iot hub message-routeback show لمشاهدة حالة المسار الاحتياطي في مركز IoT.

az iot hub message-route fallback show --hub-name {iothub_name}

استخدم الأمر az iot hub message-routeback set لتمكين أو تعطيل المسار الاحتياطي في مركز IoT الخاص بك.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

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

في هذه المقالة الإرشادية، تعلمت كيفية إنشاء مسار ونقطة نهاية لمراكز الأحداث وقوائم انتظار وموضوعات ناقل الخدمة ومساحة تخزين Azure.

لمعرفة المزيد حول توجيه الرسائل، راجع البرنامج التعليمي: إرسال بيانات الجهاز إلى Azure Storage باستخدام توجيه رسائل IoT Hub. في البرنامج التعليمي، يمكنك إنشاء مسار تخزين واختباره باستخدام جهاز في مركز IoT الخاص بك.