共用方式為

使用 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 中樞。 如果您還沒有中樞，可以使用 Azure CLI 按照步驟建立 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 中樞內的裝置進行測試。