共用方式為

使用 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 路由的來源。 接受的值為: deviceconnectionstateevents、devicejoblifecycleevents、devicelifecycleevents、devicemessages、digitaltwinchangeevents、invalid 或 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 中樞路由

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

使用 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 中樞中的裝置加以測試。