Criar e excluir rotas e pontos de extremidade usando o Azure PowerShell

Este artigo mostra como criar uma rota e um ponto de extremidade no Hub IoT do Azure e, em seguida, como exclui-los. Saiba como usar o Azure PowerShell para criar rotas e pontos de extremidade para Hubs de Eventos do Azure, filas e tópicos do Barramento de Serviço do Azure e Armazenamento do Azure.

Para saber mais sobre como funciona o encaminhamento no Hub IoT, confira Usar encaminhamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade. Para explicar a configuração de uma rota que envia mensagens para armazenar e testar em um dispositivo simulado, confira Tutorial: enviar dados do dispositivo para o Armazenamento do Azure usando o roteamento de mensagens do Hub IoT.

Pré-requisitos

Os procedimentos descritos no artigo usam os seguintes recursos:

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

Azure PowerShell

Este artigo usa o Azure PowerShell para trabalhar com o Hub IoT e outros serviços do Azure. Para usar o Azure PowerShell localmente, instale o módulo do Azure PowerShell em seu computador. Como alternativa, para usar o Azure PowerShell em um navegador da Web, habilite o Azure Cloud Shell.

Hub IoT

Para criar uma rota do Hub IoT, é necessário obter um Hub IoT que você criou usando o Hub IoT do Azure. As mensagens do dispositivo e os logs de eventos têm origem no hub IoT.

Verifique se você tem o seguinte recurso de hub para usar ao criar a rota do Hub IoT:

• Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, é possível seguir as etapas em Criar um hub IoT usando o cmdlet do PowerShell New-AzIotHub.

Serviço de ponto de extremidade

Para criar uma rota de hub IoT, você precisa de pelo menos um outro serviço do Azure para usar como um ponto de extremidade para a rota. O ponto de extremidade recebe mensagens do dispositivo e logs de eventos. Você pode escolher qual serviço do Azure usar para conectar um ponto de extremidade com sua rota do hub IoT: Hubs de Eventos, filas ou tópicos do Barramento de Serviço ou Armazenamento do Azure.

Verifique se você tem um dos seguintes recursos para usar ao criar um ponto de extremidade da rota do hub IoT:

• Um recurso dos Hubs de Eventos (com contêiner). Se você precisar criar um novo recurso dos Hubs de Eventos, confira Início Rápido: criar um hub de eventos usando o Azure PowerShell.

• Um recurso de fila do Barramento de Serviço. Se você precisar criar uma nova fila do Barramento de Serviço, confira Usar Azure PowerShell para criar um namespace e fila do Barramento de Serviço.

• Um recurso de tópico do Barramento de Serviço. Se você precisar criar um novo tópico do Barramento de Serviço, confira a referência New-AzServiceBusTopic e a documentação Mensagens do Barramento de Serviço do Azure.

• Um recurso do Armazenamento do Azure. Se você precisar criar um novo conta de armazenamento no Azure, confira Criar uma conta de armazenamento.

Criar recursos e pontos de extremidade

No Hub IoT, você pode criar uma rota para enviar mensagens ou capturar eventos. Cada rota tem uma fonte de dados e um ponto de extremidade. A fonte de dados é a origem das mensagens ou dos logs de eventos. O ponto de extremidade é o destino das mensagens ou dos logs de eventos. Você escolhe locais para a fonte de dados e o ponto de extremidade ao criar uma nova rota no Hub IoT. Em seguida, use consultas de roteamento para filtrar mensagens ou eventos, antes delas irem para o ponto de extremidade.

Você pode usar um hub de eventos, uma fila ou um tópico do Barramento de Serviço ou uma conta de armazenamento como ponto de extremidade para a rota do hub IoT. O serviço que você usa para criar seu ponto de extremidade deve existir primeiro em sua conta do Azure.

Observação

Se você usar uma versão local do Azure PowerShell, entre no Azure PowerShell antes de começar.

Hubs de Evento

Os comandos nos procedimentos a seguir usam estas referências:

• Az.IotHub
• Az.EventHub

Criar um Hub de Evento

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

1. Criar um novo namespace dos Hubs de Eventos. Para NamespaceName, use um valor exclusivo.

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

2. Crie a nova entidade dos Hubs de Eventos. Para Name, use um valor exclusivo. Para NamespaceName, use o nome do namespace criado na etapa anterior.

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

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

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

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

Criar um ponto de extremidade dos Hubs de Eventos

1. Obter a cadeia de conexão primária do hub de eventos. Copie a cadeia de conexão para usar mais tarde.

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

2. Crie um novo ponto de extremidade do Hub IoT para os Hubs de Eventos. Use a cadeia de conexão primária da etapa anterior. O valor para EndpointType deve ser EventHub. Para todos os outros parâmetros, use os valores para 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 de extremidade de encaminhamento, confira Add-AzIotHubRoutingEndpoint.

Fila do Barramento de Serviço

Os comandos nos procedimentos a seguir usam estas referências:

• Az.IotHub
• Az.ServiceBus

Criar um namespace e uma fila do Barramento de Serviço

Para criar um recurso de fila do Barramento de Serviço:

1. Crie um namespace do Barramento de Serviço. Para Name, use um valor exclusivo.

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

2. Criar uma nova fila do Barramento de Serviço. Para NamespaceName, use o nome do namespace criado na etapa anterior. Para o nome da fila, use um valor exclusivo.

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

Criar um ponto de extremidade da fila do Barramento de Serviço

Para criar um novo ponto de extremidade da fila do Barramento de Serviço:

1. Recupere a cadeia de conexão primária do namespace do Barramento de Serviço. Copie a cadeia de conexão para usar mais tarde.

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

2. Crie um novo ponto de extremidade do Hub IoT para a fila do Barramento de Serviço. Use a cadeia de conexão primária da etapa anterior com ;EntityPath=MyServiceBusQueue adicionado ao fim. O valor para EndpointType deve ser ServiceBusQueue. Para todos os outros parâmetros, use os valores para seu cenário. Para EndpointName, use 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 de extremidade de roteamento, confira Add-AzIotHubRoutingEndpoint.

Tópico do Barramento de Serviço

Os comandos nos procedimentos a seguir usam estas referências:

• Az.IotHub
• Az.ServiceBus

Com os tópicos do Barramento de Serviço, os usuários podem assinar um ou mais tópicos. Para criar um tópico, você também cria um namespace e uma assinatura do Barramento de Serviço.

Criar um namespace, um tópico e uma assinatura do Barramento de Serviço

1. Crie um namespace do Barramento de Serviço. Para Name do namespace, use um valor exclusivo.

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

2. Criar um novo tópico do Barramento de Serviço. Para o nome do tópico, use um valor exclusivo.

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

3. Criar uma nova assinatura para o tópico. Para TopicName, use o nome do tópico criado na etapa anterior. Para o nome da assinatura, use um valor exclusivo.

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

Criar um ponto de extremidade de tópico do Barramento de Serviço

1. Recupere a cadeia de conexão primária do namespace do Barramento de Serviço. Copie a cadeia de conexão para usar mais tarde.

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

2. Crie um novo ponto de extremidade do Hub IoT para o tópico do Barramento de Serviço. Use a cadeia de conexão primária da etapa anterior com ;EntityPath=MyServiceBusTopic adicionado ao fim. O valor para EndpointType deve ser ServiceBusTopic. Para todos os outros parâmetros, use os valores para seu cenário. Para EndpointName, use 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 de extremidade de roteamento, confira Add-AzIotHubRoutingEndpoint.

Armazenamento do Azure

Os comandos nos procedimentos a seguir usam estas referências:

• Az.IotHub
• Az.Storage

Para criar um ponto de extremidade e uma rota do Armazenamento do Armazenamento do Microsoft Azure, você precisa de uma conta de armazenamento e um contêiner.

Criar um contêiner e uma conta de Armazenamento do Azure

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

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

2. Crie um novo contêiner na conta de armazenamento. Você precisa criar um contexto para a conta de armazenamento em uma variável e, em seguida, adicionar a variável ao parâmetro Context. Para saber mais sobre suas opções ao criar um contêiner, consulte Gerenciar contêineres de blob usando o PowerShell. Para Name, use um valor exclusivo para o nome do contêiner.

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

Criar um ponto de extremidade do Armazenamento do Azure

Para criar um ponto de extremidade para o Armazenamento do Azure, você precisa da chave de acesso para criar uma cadeia de conexão. A cadeia de conexão faz parte do comando do Hub IoT para criar um ponto de extremidade.

1. Recupere a chave de acesso da conta de armazenamento e depois a copie.

   Get-AzStorageAccountKey -ResourceGroupName MyResourceGroup -Name mystorageaccount
   

2. Crie uma cadeia de conexão primária para a conta de armazenamento com base no modelo a seguir. Substitua mystorageaccount (em dois lugares) pelo nome da conta de armazenamento. Substitua mykey pela chave da etapa anterior.

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

   Essa cadeia de conexão é necessária na etapa para criar o ponto de extremidade.

3. Crie o ponto de extremidade do Armazenamento do Azure com a cadeia de conexão que você criou. EndpointType deve ter o valor azurestorage. Para todos os outros parâmetros, use os valores para seu cenário. Para EndpointName, use 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 for solicitado o nome do contêiner, insira o nome do contêiner e selecione ENTER para criar o ponto de extremidade.

Criar uma rota do Hub IoT

Com o novo ponto de extremidade no hub IoT, você pode criar uma nova rota.

A rota de fallback padrão no Hub IoT coleta mensagens de DeviceMessages. Escolha uma opção diferente para sua rota personalizada, como DeviceConnectionStateEvents. Para obter mais informações sobre opções de origem, confira Add-AzIotHubRoute. O parâmetro Enabled é uma opção, portanto, você não precisa usar um valor com o parâmetro.

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

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

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

Atualizar uma rota do Hub IoT

Para fazer alterações em uma rota existente, use o comando a seguir. Por exemplo, tente alterar o nome da rota usando o comando.

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

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

Get-AzIotHubRoute -ResourceGroupName MyResourceGroup -Name MyIotHub

Excluir um ponto de extremidade

Para excluir um ponto de extremidade:

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

Excluir uma rota do Hub IoT

Para excluir uma rota do Hub IoT:

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

Dica

Excluir uma rota não exclui nenhum ponto de extremidade na conta do Azure. Você deve excluir um ponto de extremidade separadamente da exclusão de uma rota.

Próximas etapas

Neste artigo de instruções, você aprendeu como criar uma rota e um ponto de extremidade para Hubs de Eventos, filas ou tópicos do Barramento de Serviço e Armazenamento do Azure.

Para saber mais sobre o roteamento de mensagens, confira Tutorial: enviar dados do dispositivo para o armazenamento do Azure usando o roteamento de mensagens do Hub IoT. No tutorial, você cria uma rota de armazenamento e a testa com um dispositivo no hub IoT.