共用方式為


使用 Azure CLI 建立和刪除路由和端點

本文說明如何使用 Azure CLI 來管理 Azure IoT 中樞路由和端點。 深入了解如何使用 Azure CLI 來為 Azure 事件中樞、Azure 服務匯流排佇列、主題、 Azure 儲存體和 Cosmos DB 建立路由和端點。

若要深入了解路由如何在 IoT 中樞運作,請參閱使用 IoT 中樞訊息路由將裝置到雲端的訊息傳送至不同端點。 若要逐步解說如何設定路由以將訊息傳送至儲存體,並在模擬裝置上進行測試,請參閱教學課程: 使用 IoT 中樞訊息路由將裝置資料傳送至 Azure 儲存體

必要條件

本文描述的程序使用下列資源:

  • Azure CLI
  • IoT 中樞
  • Azure 中的端點服務

Azure CLI

本文透過 Azure CLI 來使用 IoT 中樞和其他 Azure 服務。 您可以選擇如何存取 Azure CLI:

IoT 中樞

在您的 Azure 訂用帳戶中建立 IoT 中樞。 如果您還沒有中樞,可遵循建立 IoT 中樞中的步驟。

端點服務

您至少需要一個其他 Azure 服務作為路由的端點。 端點會接收裝置訊息和事件記錄檔。

決定要用來作為端點的 Azure 服務,以接收路由的裝置和事件資料: 事件中樞、服務佇列或主題、儲存體帳戶或 Cosmos DB 容器。 針對您所選擇的服務,請完成建立端點服務的步驟。

  1. 建立事件中樞命名空間和事件中樞。 如需詳細資訊,請參閱快速入門:使用 Azure CLI 建立事件中樞

  2. 建立授權規則,以授予 IoT 中樞將數據傳送至事件中樞的使用權限。

    提示

    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 事件中樞

建立端點

所有 IoT 中樞路由都會指向端點,該端點將接收路由的裝置和事件資料。 多個路由可以指向相同的端點。 目前,IoT 中樞支援事件中樞、服務匯流排佇列或主題、儲存體和 Cosmos DB 的端點。 在建立端點之前,用於端點的服務執行個體必須存在於 Azure 訂閱中。

注意

本文使用在適用於 Azure CLI 的 azure-iot 延伸模組 0.19.0 版本中所引進的 az iot hub message-endpoint 命令群組。 舊版的 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 命令來列出您的授權規則。 提供預留位置參數下列的值:

    parameter value
    eventhub_group 事件中樞的資源群組。
    eventhub_namespace 事件中樞命名空間的名稱。
    eventhub_name 事件中樞的名稱。
    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 命令來建立您的自訂端點。 提供預留位置參數下列的值:

    parameter value
    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}
    

刪除端點

如果您想要從 IoT 中樞刪除一個端點,使用 az iot hub message-endpoint delete 命令。 使用此命令,您可以刪除單一端點、單一類型的所有端點,或從中樞中刪除所有端點。

例如,下列命令會刪除在 IoT 中樞中指向儲存體資源的所有端點:

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

建立 IoT 中樞路由

在 IoT 中樞中,您可以建立路由來傳送訊息或擷取事件。 每個路由都有一個資料來源和端點。 訊息或事件記錄檔源自於資料來源。 端點是訊息或事件記錄檔最後出現的位置。 當您在 IoT 中樞中建立新路由時,您可以選擇資料來源和端點的位置。 您可以選擇性地新增查詢至訊息路由,以在訊息或事件傳送至端點前進行篩選。

注意

本文使用在適用於 Azure CLI 的 azure-iot 延伸模組 0.19.0 版本中所引進的 az iot hub message-route 命令群組。 舊版的 azure-iot 延伸模組使用 az iot hub route 命令群組,其與目前版本類似且仍受支援。

使用下列命令,以更新為 azure-iot 延伸模組最新版本:

az extension update --name azure-iot
  1. 使用 az iot hub message-route create 命令,以使用該端點建立新 IoT 中樞路由。 提供預留位置參數下列的值:

    parameter value
    iothub_name 正在其中建立此路由的 IoT 中樞名稱。
    route_name 新路由的唯一名稱。
    endpoint_name 路由將向其傳送資料的端點名稱。
    data_source 路由的來源。 接受的值為: deviceconnectionstateeventsdevicejoblifecycleeventsdevicelifecycleeventsdevicemessagesdigitaltwinchangeeventsinvalidtwinchangeevents
    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 中樞路由

建立路由後,您可以更新路由的某些屬性。 您可以變更現有路由的來源、端點、條件或啟用狀態。

使用 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 中樞路由

使用 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-route 命令來查看 IoT 中樞後援路由的狀態。

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

使用 az iot hub message-route fallback set 命令來啟用或停用 IoT 中樞中後援路由的狀態。

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

下一步

在本操作說明文章中,您已了解如何建立事件中樞、服務匯流排佇列和主題,以及 Azure 儲存體的路由和端點。

若要深入了解訊息路由,請參閱教學課程:使用 IoT 中樞訊息路由將裝置資料傳送至 Azure 儲存體。 在本教學課程中,您會建立儲存體路由,並使用 IoT 中樞中的裝置加以測試。