教程：使用 Azure CLI 配置 IoT 中心消息路由

消息路由能够将遥测数据从 IoT 设备发送到内置的与事件中心兼容的终结点或自定义终结点，例如，Blob 存储、服务总线队列、服务总线主题和事件中心。 若要配置自定义消息路由，请创建路由查询来自定义与特定条件匹配的路由。 设置完成后，引入的数据将通过 IoT 中心自动路由到终结点。 如果某条消息与任何定义的路由查询不匹配，它会被路由到默认终结点。

本教程包括 2 个部分，介绍如何通过 IoT 中心设置和使用这些自定义路由查询。 将消息从 IoT 设备路由到多个终结点中的一个，包括 Blob 存储和服务总线队列。 路由到服务总线队列的消息将由逻辑应用拾取，并通过电子邮件发送。 未定义自定义消息路由的消息将发送到默认终结点，然后由 Azure 流分析拾取，可在 Power BI 中直观查看。

若要完成本教程的第 1 和第 2 部分，请执行以下任务：

第 I 部分：创建资源并设置消息路由

第 II 部分：将消息发送到中心并查看路由的结果

• 对于本教程的第 1 部分：

  • 必须拥有 Azure 订阅。 如果没有 Azure 订阅，请在开始前创建一个试用版订阅。

• 对于本教程的第 2 部分：

  • 必须事先完成本教程的第 1 部分，并保留一些可用的资源。

  • 安装 Visual Studio。

  • 有权访问用于分析默认终结点的流分析的 Power BI 帐户。 （免费试用 Power BI。）

  • 提供一个用于发送通知电子邮件的工作或学校帐户。

  • 确保已在防火墙中打开端口 8883。 本教程中的示例使用 MQTT 协议，该协议通过端口 8883 进行通信。 在某些公司和教育网络环境中，此端口可能被阻止。 有关解决此问题的更多信息和方法，请参阅连接到 IoT 中心(MQTT)。

在配置消息路由之前，需创建 IoT 中心、存储帐户和服务总线队列。 可以参阅适用于本教程第 1 部分的四篇文章中的一篇来创建这些资源：Azure门户、Azure 资源管理器模板、Azure CLI 或 Azure PowerShell。

为所有资源使用相同的资源组和位置。 在本教程结束后，可以通过删除资源组一次性删除所有资源。

下面是将在以下部分中执行的步骤摘要：

1. 创建资源组。

2. 在 S1 层级中创建 IoT 中心。 将使用者组添加到 IoT 中心。 检索数据时，Azure 流分析使用使用者组。

   备注

   必须使用付费层中的 IoT 中心来完成本教程。 免费层只允许设置一个终结点，但本教程需要多个终结点。

3. 使用 Standard_LRS 副本创建标准 V1 存储帐户。

4. 创建服务总线命名空间和队列。

5. 为发送消息到中心的模拟设备创建设备标识。 保存测试阶段的密钥。 （如果创建资源管理器模板，则会在部署模板后执行此操作。）

在本教程的第二部分，我们将下载并运行一个 Visual Studio 应用程序，以将消息发送到 IoT 中心。 下载内容的某个文件夹中包含 Azure 资源管理器模板和参数文件，以及 Azure CLI 和 PowerShell 脚本。

若要查看已完成的脚本，请下载 Azure IoT C# 示例。 解压 main.zip 文件。 Azure CLI 脚本位于 /iot-hub/Tutorials/Routing/SimulatedDevice/resources/ 中，其文件名为 iothub_routing_cli.azcli。

将以下脚本复制粘贴到本地 Shell 中，然后按 Enter。 系统每次运行脚本中的一行。 该脚本的第一节将创建本教程所需的基本资源，包括存储帐户、IoT 中心、服务总线命名空间和服务总线队列。 在学习本教程余下内容的过程中，请复制每个脚本块并将其粘贴到本地 Shell，以运行该块。

有几个资源名称必须全局唯一，例如 IoT 中心名称和存储帐户名称。 为方便进行标识，这些资源名称的后面追加了名为 randomValue 的随机字母数字值。 randomValue 在脚本的顶部生成一次，并根据需要追加到整个脚本中的资源名称。 如果不想要使用随机后缀，可将其设置为空字符串或特定值。

# This command retrieves the subscription id of the current Azure account. 
# This field is used when setting up the routing queries.
subscriptionID=$(az account show --query id -o tsv)

# Concatenate this number onto the resources that have to be globally unique.
# You can set this to "" or to a specific value if you don't want it to be random.
# This retrieves a random value.
randomValue=$RANDOM

# This command installs the IOT Extension for Azure CLI.
# You only need to install this the first time.
# You need it to create the device identity. 
az extension add --name azure-iot

# Set the values for the resource names that 
# don't have to be globally unique.
location=chinanorth
resourceGroup=ContosoResources
iotHubConsumerGroup=ContosoConsumers
containerName=contosoresults
iotDeviceName=Contoso-Test-Device

# Create the resource group to be used
# for all the resources for this tutorial.
az group create --name $resourceGroup \
    --location $location

# The IoT hub name must be globally unique, 
# so add a random value to the end.
iotHubName=ContosoTestHub$randomValue 
echo "IoT hub name = " $iotHubName

# Create the IoT hub.
az iot hub create --name $iotHubName \
    --resource-group $resourceGroup \
    --sku S1 --location $location

# Add a consumer group to the IoT hub for the 'events' endpoint.
az iot hub consumer-group create --hub-name $iotHubName \
    --name $iotHubConsumerGroup

# The storage account name must be globally unique, 
# so add a random value to the end.
storageAccountName=contosostorage$randomValue
echo "Storage account name = " $storageAccountName

# Create the storage account to be used as a routing destination.
az storage account create --name $storageAccountName \
    --resource-group $resourceGroup \
    --location $location \
    --sku Standard_LRS

# Get the primary storage account key. 
# You need this to create the container.
storageAccountKey=$(az storage account keys list \
    --resource-group $resourceGroup \
    --account-name $storageAccountName \
    --query "[0].value" | tr -d '"') 

# See the value of the storage account key.
echo "storage account key = " $storageAccountKey

# Create the container in the storage account. 
az storage container create --name $containerName \
    --account-name $storageAccountName \
    --account-key $storageAccountKey \
    --public-access off

# The Service Bus namespace must be globally unique, 
# so add a random value to the end.
sbNamespace=ContosoSBNamespace$randomValue
echo "Service Bus namespace = " $sbNamespace

# Create the Service Bus namespace.
az servicebus namespace create --resource-group $resourceGroup \
    --name $sbNamespace \
    --location $location

# The Service Bus queue name must be globally unique, 
# so add a random value to the end.
sbQueueName=ContosoSBQueue$randomValue
echo "Service Bus queue name = " $sbQueueName

# Create the Service Bus queue to be used as a routing destination.
az servicebus queue create --name $sbQueueName \
    --namespace-name $sbNamespace \
    --resource-group $resourceGroup

# Create the IoT device identity to be used for testing.
az iot hub device-identity create --device-id $iotDeviceName \
    --hub-name $iotHubName

# Retrieve the information about the device identity, then copy the primary key to
# Notepad. You need this to run the device simulation during the testing phase.
az iot hub device-identity show --device-id $iotDeviceName \
    --hub-name $iotHubName

设置基本资源后，可以配置消息路由。

根据模拟设备附加到消息的属性将消息路由到不同资源。 未自定义路由的消息将发送到默认终结点（消息/事件）。 在下一教程中，我们会将消息发送到 IoT 中心，看其如何路由到不同的目标。

第一步是设置终结点，以便将数据路由到其中。 第二步是设置使用该终结点的消息路由。 设置路由后，即可在门户中查看终结点和消息路由。

若要创建路由终结点，请使用 az iot hub routing-endpoint create。 若要为终结点创建消息路由，请使用 az iot hub route create。

首先设置存储帐户的终结点，然后设置路由。

以下是脚本使用的变量，必须进行设置：

storageConnectionString：此值是从前述脚本设置的存储帐户中检索的。 消息路由使用此值来访问存储帐户。

resourceGroup：需要在两个位置使用资源组 - 请将其设置为你的资源组。

endpoint subscriptionID：此字段设置为终结点的 Azure subscriptionID。

endpointType：此字段是终结点的类型。 此值必须设置为 azurestoragecontainer、eventhub、servicebusqueue 或 servicebustopic。 在本文中，请将其设置为 azurestoragecontainer。

iotHubName：此字段是执行路由的中心的名称。

containerName：此字段是存储帐户中要将数据写入到的容器的名称。

encoding：此字段为 avro 或 json。 这表示存储的数据的格式。

routeName：此字段是要设置的路由的名称。

endpointName：此字段是用于标识终结点的名称。

enabled：此字段默认为 true，表示应在创建消息路由后启用该路由。

condition：此字段是用于筛选发送到此终结点的消息的查询。 路由到存储的消息的查询条件是 level="storage"。

请复制此脚本，并将其粘贴到本地 Shell 窗口并运行。

##### ROUTING FOR STORAGE ##### 

endpointName="ContosoStorageEndpoint"
endpointType="azurestoragecontainer"
routeName="ContosoStorageRoute"
condition='level="storage"'

# Get the connection string for the storage account.
# Adding the "-o tsv" makes it be returned without the default double quotes around it.
storageConnectionString=$(az storage account show-connection-string \
  --name $storageAccountName --query connectionString -o tsv)

下一步是为存储帐户创建路由终结点。 还可以指定用于存储结果的容器。 前面在创建存储帐户时已创建该容器。

# Create the routing endpoint for storage.
az iot hub routing-endpoint create \
  --connection-string $storageConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --container $containerName \
  --resource-group $resourceGroup \
  --encoding avro

接下来，为存储终结点创建路由。 消息路由根据查询规范指定要将消息发送到何处。

# Create the route for the storage endpoint.
az iot hub route create \
  --name $routeName \
  --hub-name $iotHubName \
  --source devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

现在为服务总线队列设置路由。 若要检索服务总线队列的连接字符串，必须创建一个定义了正确权限的授权规则。 以下脚本为服务总线队列创建名为 sbauthrule 的授权规则，并将权限设置为 Listen Manage Send。 定义此授权规则后，可以使用它来检索队列的连接字符串。

# Create the authorization rule for the Service Bus queue.
az servicebus queue authorization-rule create \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --rights Listen Manage Send \
  --subscription $subscriptionID

现在，使用授权规则来检索服务总线队列的连接字符串。

# Get the Service Bus queue connection string.
# The "-o tsv" ensures it is returned without the default double-quotes.
sbqConnectionString=$(az servicebus queue authorization-rule keys list \
  --name "sbauthrule" \
  --namespace-name $sbNamespace \
  --queue-name $sbQueueName \
  --resource-group $resourceGroup \
  --subscription $subscriptionID \
  --query primaryConnectionString -o tsv)

# Show the Service Bus queue connection string.
echo "service bus queue connection string = " $sbqConnectionString

现在，为服务总线队列设置路由终结点和消息路由。 以下是脚本使用的必须在本地 Shell 会话中设置的变量：

endpointName：此字段是用于标识终结点的名称。

endpointType：此字段是终结点的类型。 此值必须设置为 azurestoragecontainer、eventhub、servicebusqueue 或 servicebustopic。 在本文中，请将其设置为 servicebusqueue。

routeName：此字段是要设置的路由的名称。

condition：此字段是用于筛选发送到此终结点的消息的查询。 路由到服务总线队列的消息的查询条件是 level="critical"。

下面是路由终结点的 Azure CLI，以及服务总线队列的消息路由。

endpointName="ContosoSBQueueEndpoint"
endpointType="ServiceBusQueue"
routeName="ContosoSBQueueRoute"
condition='level="critical"'

# Set up the routing endpoint for the Service Bus queue.
# This uses the Service Bus queue connection string.
az iot hub routing-endpoint create \
  --connection-string $sbqConnectionString \
  --endpoint-name $endpointName \
  --endpoint-resource-group $resourceGroup \
  --endpoint-subscription-id $subscriptionID \
  --endpoint-type $endpointType \
  --hub-name $iotHubName \
  --resource-group $resourceGroup 

# Set up the message route for the Service Bus queue endpoint.
az iot hub route create --name $routeName \
  --hub-name $iotHubName \
  --source-type devicemessages \
  --resource-group $resourceGroup \
  --endpoint-name $endpointName \
  --enabled \
  --condition $condition

设置终结点和消息路由以后，即可在门户中查看其配置。 登录 Azure 门户，转到“资源组”。 接下来选择你的资源组，然后选择中心（在本教程中，中心名称以 ContosoTestHub 开头）。 此时会看到“IoT 中心”窗格。

在适用于 IoT 中心的选项中，选择“消息路由”。 此时会显示已成功设置的路由。

在“消息路由”屏幕上选择“自定义终结点”，查看为路由定义的终结点。

设置资源并配置消息路由后，请继续学习下一篇教程，了解如何将消息发送到 IoT 中心，并查看其如何路由到不同的目标。