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

Este artigo mostra como criar uma rota e um ponto de extremidade em seu hub no Hub IoT do Azure e, em seguida, excluir sua rota e ponto de extremidade. 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 o roteamento funciona no Hub IoT, consulte Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade. Para percorrer a configuração de uma rota que envia mensagens para o armazenamento e, em seguida, testar em um dispositivo simulado, consulte Tutorial: Enviar dados do dispositivo para o Armazenamento do Azure usando o roteamento de mensagens do Hub IoT.

Nota

Atualmente, o PowerShell não oferece suporte a tipos de autenticação de identidade gerenciada para a criação de pontos de extremidade. Se você não puder usar a autenticação SAS em seu cenário, use uma das outras ferramentas de gerenciamento para criar pontos de extremidade.

Além disso, o PowerShell atualmente não oferece suporte à criação de pontos de extremidade do Cosmos DB.

Pré-requisitos

Analise os pré-requisitos para este artigo com base no tipo de ponto de extremidade para o qual você deseja rotear as mensagens.

Hubs de Eventos

• Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta do Azure gratuita antes de começar.

• Um hub IoT. Se você não tiver um hub, poderá seguir as etapas para criar um hub IoT.

• Azure PowerShell. 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.

• Um recurso de Hubs de Eventos (com contêiner). Se você precisar criar um novo recurso de Hubs de Eventos, consulte Guia de início rápido: criar um hub de eventos.

• (Recomendado) Uma identidade gerenciada com permissões de controle de acesso baseadas em função para o namespace Hubs de Eventos. Para obter mais informações, consulte Autenticar uma identidade gerenciada com a ID do Microsoft Entra para acessar recursos de Hubs de Eventos.

Fila do Service Bus

• Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta do Azure gratuita antes de começar.

• Um hub IoT. Se você não tiver um hub, poderá seguir as etapas para criar um hub IoT.

• Azure PowerShell. 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.

• Um recurso de fila do Service Bus. Se você precisar criar uma nova fila do Service Bus, consulte Guia de início rápido: criar um namespace do Service Bus e uma fila.

• (Recomendado) Uma identidade gerenciada com permissões de controle de acesso baseadas em função para o namespace ou fila do Service Bus. Para obter mais informações, consulte Autenticar uma identidade gerenciada com a ID do Microsoft Entra para acessar os recursos do Barramento de Serviço do Azure

Tópico do Service Bus

• Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta do Azure gratuita antes de começar.

• Um hub IoT. Se você não tiver um hub, poderá seguir as etapas para criar um hub IoT.

• Azure PowerShell. 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.

• Um recurso de tópico do Service Bus. Se você precisar criar um novo tópico do Service Bus, consulte Guia de início rápido: criar um namespace do Service Bus com tópico e assinatura usando um modelo do Gerenciador de Recursos.

• (Recomendado) Uma identidade gerenciada com permissões de controle de acesso baseadas em função para o namespace ou tópico do Service Bus. Para obter mais informações, consulte Autenticar uma identidade gerenciada com a ID do Microsoft Entra para acessar os recursos do Barramento de Serviço do Azure

Armazenamento do Azure

• Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta do Azure gratuita antes de começar.

• Um hub IoT. Se você não tiver um hub, poderá seguir as etapas para criar um hub IoT.

• Azure PowerShell. 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.

• Um recurso de Armazenamento do Azure. Se você precisar criar uma nova conta de Armazenamento do Azure, consulte Criar uma conta de armazenamento.

• (Recomendado) Uma identidade gerenciada com permissões de controle de acesso baseadas em função para a conta de armazenamento. Para obter mais informações, veja Atribuir uma função do Azure para acesso aos dados de blobs.

Criar pontos finais

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 é onde as mensagens ou logs de eventos se originam. O ponto de extremidade é onde as mensagens ou logs de eventos terminam. Você escolhe locais para a fonte de dados e o ponto de extremidade quando cria uma nova rota em seu hub IoT. Em seguida, use consultas de roteamento para filtrar mensagens ou eventos antes que eles vão para o ponto de extremidade.

O serviço que você usa para criar seu ponto de extremidade deve primeiro existir em sua conta do Azure.

Nota

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

Hubs de Eventos

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

• Az.IotHub
• Az.EventHub

1. Obtenha a cadeia de conexão principal do seu 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 Hubs de Eventos. Use sua cadeia de conexão principal da etapa anterior. O valor para EndpointType deve ser EventHub. Para todos os outros parâmetros, use 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 de extremidade de roteamento, consulte Add-AzIotHubRoutingEndpoint.

Fila do Service Bus

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

• Az.IotHub
• Az.ServiceBus

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

1. Recupere a cadeia de conexão primária do seu namespace do Service Bus. 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 sua fila do Service Bus. Use sua cadeia de conexão principal da etapa anterior com ;EntityPath=MyServiceBusQueue adicionado ao final. O valor para EndpointType deve ser ServiceBusQueue. Para todos os outros parâmetros, use os valores para o 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, consulte Add-AzIotHubRoutingEndpoint.

Tópico do Service Bus

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

• Az.IotHub
• Az.ServiceBus

1. Recupere a cadeia de conexão primária do seu namespace do Service Bus. 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 seu tópico do Service Bus. Use sua cadeia de conexão principal da etapa anterior com ;EntityPath=MyServiceBusTopic adicionado ao final. O valor para EndpointType deve ser ServiceBusTopic. Para todos os outros parâmetros, use os valores para o 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, consulte Add-AzIotHubRoutingEndpoint.

Armazenamento do Azure

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

• Az.IotHub
• Az.Storage

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

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

   Get-AzStorageAccountKey -ResourceGroupName MyResourceGroup -Name mystorageaccount
   

2. Construa uma cadeia de conexão primária para sua conta de armazenamento com base no modelo a seguir. Substitua mystorageaccount (em dois locais) pelo nome da sua 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 seu ponto de extremidade do Armazenamento do Azure com a cadeia de conexão que você construiu. EndpointType deve ter o valor azurestorage. Para todos os outros parâmetros, use os valores para o 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, digite o nome do contêiner e selecione Enter para criar o ponto de extremidade.

Criar uma rota do Hub IoT

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

A rota de fallback padrão no Hub IoT coleta mensagens do DeviceMessages. Escolha uma opção diferente para sua rota personalizada, como DeviceConnectionStateEvents. Para obter mais informações sobre opções de origem, consulte Add-AzIotHubRoute. O Enabled parâmetro é 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 sua rota usando o comando.

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

Use o Get-AzIotHubRoute comando para confirmar a alteração na sua 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

Gorjeta

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

Próximos passos

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

Para saber mais sobre o roteamento de mensagens, consulte Tutorial: Enviar dados de 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 em seu hub IoT.