Criar e eliminar rotas e pontos finais com Azure PowerShell

Este artigo mostra-lhe como criar uma rota e um ponto final no seu hub no Hub IoT do Azure e, em seguida, eliminar a rota e o ponto final. Saiba como utilizar Azure PowerShell para criar rotas e pontos finais para Hubs de Eventos do Azure, filas de Azure Service Bus e tópicos e Armazenamento do Azure.

Para saber mais sobre como funciona o encaminhamento no Hub IoT, consulte Utilizar o encaminhamento de mensagens Hub IoT para enviar mensagens do dispositivo para a cloud para diferentes pontos finais. Para percorrer a configuração de uma rota que envia mensagens para o armazenamento e, em seguida, testar num dispositivo simulado, veja Tutorial: Enviar dados do dispositivo para o Armazenamento do Microsoft Azure com Hub IoT encaminhamento de mensagens.

Pré-requisitos

Os procedimentos descritos no artigo utilizam os seguintes recursos:

• Azure PowerShell
• Um hub IoT
• Um serviço de ponto final no Azure

Azure PowerShell

Este artigo utiliza Azure PowerShell para trabalhar com Hub IoT e outros serviços do Azure. Para utilizar Azure PowerShell localmente, instale o módulo Azure PowerShell no seu computador. Em alternativa, para utilizar Azure PowerShell num browser, ative o Azure Cloud Shell.

Hub IoT

Para criar uma rota do hub IoT, precisa de um hub IoT que criou com Hub IoT do Azure. As mensagens do dispositivo e os registos de eventos têm origem no seu hub IoT.

Certifique-se de que tem o seguinte recurso do hub para utilizar quando criar a rota do hub IoT:

• Um hub IoT na sua subscrição do Azure. Se ainda não tiver um hub, pode seguir os passos para criar um hub IoT com o cmdlet New-AzIotHub PowerShell.

Serviço de ponto final

Para criar uma rota do hub IoT, precisa de, pelo menos, um outro serviço do Azure para utilizar como um ponto final para a rota. O ponto final recebe mensagens do dispositivo e registos de eventos. Pode escolher o serviço do Azure que utiliza para um ponto final se ligar à rota do hub IoT: Hubs de Eventos, filas ou tópicos do Service Bus ou Armazenamento do Azure.

Certifique-se de que tem um dos seguintes recursos para utilizar quando criar um ponto final na rota do hub IoT:

• Um recurso dos Hubs de Eventos (com contentor). Se precisar de criar um novo recurso dos Hubs de Eventos, veja Início Rápido: Criar um hub de eventos com Azure PowerShell.

• Um recurso de fila do Service Bus. Se precisar de criar uma nova fila do Service Bus, veja Utilizar Azure PowerShell para criar um espaço de nomes e uma fila do Service Bus.

• Um recurso de tópico do Service Bus. Se precisar de criar um novo tópico do Service Bus, veja a referência New-AzServiceBusTopic e a documentação Azure Service Bus mensagens.

• Um recurso de Armazenamento do Azure. Se precisar de criar uma nova conta de armazenamento no Azure, veja Criar uma conta de armazenamento.

Criar recursos e pontos finais

No Hub IoT, pode criar uma rota para enviar mensagens ou capturar eventos. Cada rota tem uma origem de dados e um ponto final. A origem de dados é onde as mensagens ou os registos de eventos têm origem. O ponto final é onde as mensagens ou os registos de eventos acabam. Pode escolher localizações para a origem de dados e o ponto final quando cria uma nova rota no seu hub IoT. Em seguida, utilize as consultas de encaminhamento para filtrar mensagens ou eventos antes de acederem ao ponto final.

Pode utilizar um hub de eventos, uma fila ou tópico do Service Bus ou uma conta de armazenamento para ser o ponto final da rota do hub IoT. O serviço que utiliza para criar o ponto final tem de existir primeiro na sua conta do Azure.

Nota

Se utilizar uma versão local do Azure PowerShell, inicie sessão para Azure PowerShell antes de começar.

Hubs de Eventos

Os comandos nos seguintes procedimentos utilizam estas referências:

• Az.IotHub
• Az.EventHub

Criar um hub de eventos

Para criar um novo recurso dos Hubs de Eventos que tenha uma regra de autorização:

1. Crie um novo espaço de nomes dos Hubs de Eventos. Para NamespaceName, utilize um valor exclusivo.

   New-AzEventHubNamespace -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Location MyLocation
   

2. Crie a sua nova entidade dos Hubs de Eventos. Para Name, utilize um valor exclusivo. Para NamespaceName, utilize o nome do espaço de nomes que criou no passo anterior.

   New-AzEventHub -Name MyEventHub -NamespaceName MyNamespace -ResourceGroupName MyResourceGroup
   

3. Crie uma nova regra de autorização. Para Name, utilize o nome da sua entidade para EventHubName. Para o nome da regra de autorização, utilize um valor exclusivo.

   New-AzEventHubAuthorizationRule -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -EventHubName MyEventHub -Name MyAuthRule -Rights @('Manage', 'Send', 'Listen')
   

   Para obter mais informações sobre o acesso, veja Autorizar o acesso ao Hubs de Eventos do Azure.

Criar um ponto final dos Hubs de Eventos

1. Obtenha a cadeia de ligação primária do hub de eventos. Copie a cadeia de ligação para utilizar mais tarde.

   Get-AzEventHubKey -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -EventHubName MyEventHub -Name MyAuthRule
   

2. Crie um novo ponto final do hub IoT para os Hubs de Eventos. Utilize a cadeia de ligação primária do passo anterior. O valor de EndpointType tem de ser EventHub. Para todos os outros parâmetros, utilize os valores para o seu cenário.

   Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType EventHub -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "Endpoint=<my connection string>"
   

   Para ver todas as opções de ponto final de encaminhamento, veja Add-AzIotHubRoutingEndpoint.

Fila do Service Bus

Os comandos nos seguintes procedimentos utilizam estas referências:

• Az.IotHub
• Az.ServiceBus

Criar um espaço de nomes e uma fila do Service Bus

Para criar um novo recurso de fila do Service Bus :

1. Crie um novo espaço de nomes do Service Bus. Para Name, utilize um valor exclusivo.

   New-AzServiceBusNamespace -ResourceGroupName MyResourceGroup -Name MyNamespace -Location MyRegion
   

2. Crie uma nova fila do Service Bus. Para NamespaceName, utilize o nome do espaço de nomes que criou no passo anterior. Para o nome da sua fila, utilize um valor exclusivo.

   New-AzServiceBusQueue -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Name MyQueue
   

Criar um ponto final de fila do Service Bus

Para criar um novo ponto final de fila do Service Bus:

1. Obtenha a cadeia de ligação primária do espaço de nomes do Service Bus. Copie a cadeia de ligação para utilizar mais tarde.

   Get-AzServiceBusKey -ResourceGroupName MyResourceGroup -Namespace MyNamespace -Name RootManageSharedAccessKey
   

2. Crie um novo ponto final do hub IoT para a fila do Service Bus. Utilize a cadeia de ligação primária do passo anterior com ;EntityPath=MyServiceBusQueue adicionada ao fim. O valor de EndpointType tem de ser ServiceBusQueue. Para todos os outros parâmetros, utilize os valores para o seu cenário. Para EndpointName, utilize um valor exclusivo.

   Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType EventHub -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "Endpoint=my-connection-string;EntityPath=MyServiceBusQueue"
   

   Para obter uma lista de todas as opções de ponto final de encaminhamento, veja Add-AzIotHubRoutingEndpoint.

Tópico do Service Bus

Os comandos nos seguintes procedimentos utilizam estas referências:

• Az.IotHub
• Az.ServiceBus

Com os tópicos do Service Bus , os utilizadores podem subscrever um ou mais tópicos. Para criar um tópico, crie também um espaço de nomes e uma subscrição do Service Bus.

Criar um espaço de nomes, tópico e subscrição do Service Bus

1. Crie um novo espaço de nomes do Service Bus. Para Name o seu espaço de nomes, utilize um valor exclusivo.

   New-AzServiceBusNamespace -ResourceGroupName MyResourceGroup -Name MyNamespace -Location MyRegion
   

2. Crie um novo tópico do Service Bus. Para o nome do tópico, utilize um valor exclusivo.

   New-AzServiceBusTopic -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -Name MyTopic
   

3. Crie uma nova subscrição para o seu tópico. Para TopicName, utilize o nome do tópico que criou no passo anterior. Para o nome da sua subscrição, utilize um valor exclusivo.

   New-AzServiceBusSubscription -ResourceGroupName MyResourceGroup -NamespaceName MyNamespace -TopicName MyTopic -Name MySubscription
   

Criar um ponto final de tópico do Service Bus

1. Obtenha a cadeia de ligação primária do espaço de nomes do Service Bus. Copie a cadeia de ligação para utilizar mais tarde.

   Get-AzServiceBusKey -ResourceGroupName MyResourceGroup -Namespace MyNamespace -Name RootManageSharedAccessKey
   

2. Crie um novo ponto final do hub IoT para o seu tópico do Service Bus. Utilize a cadeia de ligação primária do passo anterior com ;EntityPath=MyServiceBusTopic adicionada ao fim. O valor para EndpointType tem de ser ServiceBusTopic. Para todos os outros parâmetros, utilize os valores para o seu cenário. Para EndpointName, utilize um valor exclusivo.

   Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType ServiceBusTopic -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "Endpoint=<my connection string>;EntityPath=MyServiceBusTopic"
   

   Para obter uma lista de todas as opções de ponto final de encaminhamento, veja Add-AzIotHubRoutingEndpoint.

Armazenamento do Azure

Os comandos nos seguintes procedimentos utilizam estas referências:

• Az.IotHub
• Az.Storage

Para criar um ponto final e uma rota do Armazenamento do Azure, precisa de uma conta de Armazenamento e de um contentor.

Criar uma conta de Armazenamento do Azure e um contentor

1. Crie uma nova conta de Armazenamento do Azure. O valor de Name para a sua conta de armazenamento só pode conter letras minúsculas e números. Para SkuName obter opções, veja SkuName.

   New-AzStorageAccount -ResourceGroupName MyResourceGroup -Name mystorageaccount -Location westus -SkuName Standard_GRS
   

2. Crie um novo contentor na sua conta de armazenamento. Tem de criar um contexto para a sua conta de armazenamento numa variável e, em seguida, adicionar a variável ao Context parâmetro. Para saber mais sobre as suas opções ao criar um contentor, veja Gerir contentores de blobs com o PowerShell. Para Name, utilize um valor exclusivo para o nome do contentor.

   $ctx = New-AzStorageContext -StorageAccountName mystorageaccount -UseConnectedAccount `
   New-AzStorageContainer -Name ContainerName -Context $ctx
   

Criar um ponto final do Armazenamento do Azure

Para criar um ponto final no Armazenamento do Azure, precisa da sua chave de acesso para construir uma cadeia de ligação. A cadeia de ligação faz, em seguida, parte do comando Hub IoT para criar um ponto final.

1. Obtenha a chave de acesso da sua conta de armazenamento e, em seguida, copie-a.

   Get-AzStorageAccountKey -ResourceGroupName MyResourceGroup -Name mystorageaccount
   

2. Construa uma cadeia de ligação primária para a sua conta de armazenamento com base no modelo seguinte. Substitua mystorageaccount (em dois locais) pelo nome da sua conta de armazenamento. Substitua mykey pela chave do passo anterior.

   "DefaultEndpointsProtocol=https;BlobEndpoint=https://mystorageaccount.blob.core.windows.net;AccountName=mystorageaccount;AccountKey=mykey"
   

   Esta cadeia de ligação é necessária no passo para criar o ponto final.

3. Crie o ponto final do Armazenamento do Azure com a cadeia de ligação que construiu. EndpointType tem de ter o valor azurestorage. Para todos os outros parâmetros, utilize os valores para o seu cenário. Para EndpointName, utilize um valor exclusivo.

   Add-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -EndpointType azurestorage -EndpointResourceGroup MyResourceGroup -EndpointSubscriptionId xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -ConnectionString "my connection string"
   

4. Quando lhe for pedido o nome do contentor, introduza o nome do contentor e, em seguida, selecione Enter para criar o ponto final.

Criar uma rota de Hub IoT

Com o novo ponto final no hub IoT, pode criar uma nova rota.

A rota de contingência predefinida no Hub IoT recolhe mensagens de DeviceMessages. Escolha uma opção diferente para a rota personalizada, como DeviceConnectionStateEvents. Para obter mais informações sobre as opções de origem, veja Add-AzIotHubRoute. O Enabled parâmetro é um comutador, pelo que não precisa de utilizar um valor com o parâmetro .

Add-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute -Source DeviceLifecycleEvents -EndpointName MyEndpoint -Enabled

O PowerShell apresenta uma confirmação semelhante a este exemplo:

RouteName     : MyIotHub 
DataSource    : DeviceLifecycleEvents
EndpointNames : MyEndpoint
Condition     : true
IsEnabled     : True

Atualizar uma rota de Hub IoT

Para efetuar alterações a uma rota existente, utilize o seguinte comando. Por exemplo, experimente alterar o nome da rota com o comando .

Set-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute

Utilize o Get-AzIotHubRoute comando para confirmar a alteração na rota:

Get-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub

Eliminar um ponto final

Para eliminar um ponto final:

Remove-AzIotHubRoutingEndpoint -ResourceGroupName MyResourceGroup -Name MyIotHub -EndpointName MyEndpoint -PassThru

Eliminar uma rota de Hub IoT

Para eliminar uma rota de Hub IoT:

Remove-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub -RouteName MyRoute -PassThru

Dica

Eliminar uma rota não elimina pontos finais na sua conta do Azure. Tem de eliminar um ponto final separadamente da eliminação de uma rota.

Passos seguintes

Neste artigo de procedimentos, aprendeu a criar uma rota e ponto final para Hubs de Eventos, filas e tópicos do Service Bus e Armazenamento do Azure.

Para saber mais sobre o encaminhamento de mensagens, veja Tutorial: Enviar dados do dispositivo para o Armazenamento do Azure com Hub IoT encaminhamento de mensagens. No tutorial, vai criar uma rota de armazenamento e testá-la com um dispositivo no seu hub IoT.