Criar e excluir rotas e pontos de extremidade usando a CLI do Azure

Este artigo mostra como gerenciar rotas e pontos de extremidade do Hub IoT do Azure usando a CLI do Azure. Saiba como usar a CLI do Azure para criar rotas e pontos de extremidade para Hubs de Eventos do Azure, filas e tópicos do Barramento de Serviço do Azure, Armazenamento do Azure e Cosmos DB.

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.

Pré-requisitos

Os procedimentos descritos no artigo usam os seguintes recursos:

• A CLI do Azure
• Um hub IoT
• Um serviço de ponto de extremidade no Azure

CLI do Azure

Este artigo usa a CLI do Azure para trabalhar com o Hub IoT e outros serviços do Azure. Você pode escolher como acessar a CLI do Azure:

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

IoT Hub

Tenha um hub IoT em sua assinatura do Azure. Se você ainda não tiver um hub, siga as etapas em Criar um hub IoT.

Serviço de ponto final

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.

Decida qual serviço do Azure você deseja usar como ponto de extremidade para receber dados de dispositivo e evento roteados: um hub de eventos, uma fila ou tópico de serviço, uma conta de armazenamento ou um contêiner do Cosmos DB. Para o serviço que você escolher usar, conclua as etapas para criar um serviço de ponto de extremidade.

Hubs de Eventos

1. Crie um namespace de Hubs de Eventos e um hub de eventos. Para obter mais informações, consulte Guia de início rápido: criar um hub de eventos usando a CLI do Azure.

2. Crie uma regra de autorização que será usada para dar permissão ao Hub IoT para enviar dados para o hub de eventos.

   Gorjeta

   O name valor RootManageSharedAccessKey do parâmetro é o nome padrão que permite declarações Manage, Send, Listen (access). Se você quiser restringir as declarações, dê ao name parâmetro seu próprio nome exclusivo e inclua o --rights sinalizador seguido por uma das declarações. Por exemplo, --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
   

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

Fila do Service Bus

1. Crie um espaço de nomes e uma fila do Service Bus. Para obter mais informações, consulte Usar a CLI do Azure para criar um namespace do Service Bus e uma fila.

2. Crie uma regra de autorização que dará permissão ao Hub IoT para enviar dados para a fila. Para name, use um valor exclusivo para sua regra de autorização.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   Para obter mais opções de regra de autorização, consulte az servicebus queue authorization-rule create.

Tópico do Service Bus

Crie um namespace, tópico e assinatura do Service Bus. Para obter mais informações, consulte Usar a CLI do Azure para criar um tópico do Service Bus e assinaturas para o tópico.

Armazenamento do Azure

1. Criar uma conta de armazenamento. Para obter mais informações, veja Criar uma conta de armazenamento.

2. Crie um contêiner em sua conta de armazenamento. Para obter mais informações, consulte Gerenciar contêineres de blob usando a CLI do Azure

Cosmos DB

Crie uma conta do Cosmos DB para a API SQL e um contêiner do Cosmos DB. Para obter mais informações, consulte Criar um Azure Cosmos DB para NoSQL.

Criar um ponto final

Todas as rotas do Hub IoT apontam para um ponto de extremidade, que receberá o dispositivo roteado e os dados do evento. Mais de uma rota pode apontar para o mesmo ponto de extremidade. Atualmente, o Hub IoT oferece suporte a pontos de extremidade para hubs de eventos, filas ou tópicos do Service Bus, armazenamento e Cosmos DB. Uma instância do serviço que você usa para seu ponto de extremidade deve existir em sua assinatura do Azure antes de criar o ponto de extremidade.

Nota

Este artigo usa o grupo de comandos az iot hub message-endpoint , que foi introduzido na versão 0.19.0 da extensão azure-iot para a CLI do Azure. As versões anteriores da extensão azure-iot usavam o grupo de comandos az iot hub routing-endpoint, que é semelhante e ainda é suportado, mas não suporta a criação de pontos de extremidade do Cosmos DB.

Use o seguinte comando para atualizar para a versão mais recente da extensão azure-iot:

az extension update --name azure-iot

Hubs de Eventos

Para criar um ponto de extremidade de Hubs de Eventos, use a regra de autorização que você criou nos pré-requisitos.

1. Use o comando az eventhubs eventhub authorization-rule keys list para listar sua regra de autorização. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   eventhub_group	Grupo de recursos do hub de eventos.
   eventhub_namespace	Nome do namespace Hubs de Eventos.
   eventhub_name	Nome do hub de eventos.
   rule_name	O nome da regra de autorização para o hub de eventos. Se você copiou o exemplo nos pré-requisitos, esse nome é 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. Copie a cadeia de conexão do hub de eventos da saída.

3. Use o comando az iot hub message-endpoint create eventhub para criar seu ponto de extremidade personalizado. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   eventhub_subscription	ID de assinatura do hub de eventos. Esse argumento pode ser deixado de lado se o hub de eventos estiver na mesma assinatura que o hub IoT.
   eventhub_group	Grupo de recursos do hub de eventos. Esse argumento pode ser deixado de lado se o hub de eventos estiver no mesmo grupo de recursos que o hub IoT.
   eventhub_connection_string	A cadeia de conexão que você copiou da regra de autorização do hub de eventos.

   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}
   

Fila do Service Bus

Para criar um ponto de extremidade de fila do Service Bus, use a regra de autorização que você criou nos pré-requisitos.

1. Use o comando az servicebus queue authorization-rule keys list para obter sua cadeia de conexão de fila do Service Bus. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   queue_group	Grupo de recursos da fila do Service Bus.
   queue_namespace	Nome do namespace da fila do Service Bus.
   queue_name	Nome da fila.
   rule_name	O nome da regra de autorização para a fila. Se você copiou o exemplo nos pré-requisitos, esse nome é my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. Copie a cadeia de conexão da fila do Service Bus da saída.

3. Use o comando az iot hub message-endpoint create servicebus-queue para criar seu endpoint personalizado. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   queue_connection_string	A cadeia de conexão que você copiou da regra de autorização de fila do Service Bus.
   queue_subscription	ID de assinatura da fila do Service Bus. Esse argumento pode ser deixado de lado se a fila estiver na mesma assinatura que o hub IoT.
   queue_group	Grupo de recursos da fila do Service Bus. Esse argumento pode ser deixado de fora se a fila estiver no mesmo grupo de recursos que o hub IoT.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

Tópico do Service Bus

1. Use a lista az servicebus topic authorization-rule keys para obter sua cadeia de conexão de tópico do Service Bus. O nome padrão da regra de autorização que vem com um novo namespace é RootManageSharedAccessKey. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   topic_group	Grupo de recursos do tópico Service Bus.
   topic_namespace	Nome do namespace do tópico do Service Bus.
   topic_name	Nome do tópico.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. Copie a cadeia de conexão do tópico do Service Bus da saída.

3. Use o comando az iot hub message-endpoint create servicebus-topic para criar seu endpoint personalizado. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   topic_connection_string	A cadeia de conexão que você copiou da regra de autorização de tópico do Service Bus.
   topic_subscription	ID de assinatura do tópico Service Bus. Esse argumento pode ser deixado de lado se o tópico estiver na mesma assinatura que o hub IoT.
   topic_group	Grupo de recursos do tópico Service Bus. Esse argumento pode ser deixado de lado se o tópico estiver no mesmo grupo de recursos que o hub IoT.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

Armazenamento do Azure

1. Use o comando az storage account show-connection-string para obter a cadeia de conexão do seu recurso de Armazenamento do Azure para criar um ponto de extremidade. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   storage_group	Grupo de recursos da conta de armazenamento.
   storage_name	Nome da conta de armazenamento.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. Copie a cadeia de conexão da conta de armazenamento da saída.

3. Use o comando az iot hub message-endpoint create storage-container para criar um novo ponto de extremidade do Armazenamento do Azure. Para todos os outros parâmetros, use valores para seu cenário. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   storage_connection_string	A cadeia de conexão que você copiou do comando de conta de armazenamento.
   container_name	O nome do contêiner em sua conta de armazenamento para onde os dados serão enviados.
   storage_subscription	ID de assinatura do armazenamento do Service Bus. Esse argumento pode ser deixado de lado se o armazenamento estiver na mesma assinatura que o hub IoT.
   storage_group	Grupo de recursos do armazenamento do Service Bus. Esse argumento pode ser deixado de lado se o tópico estiver no mesmo grupo de recursos que o hub IoT.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. Use o comando az cosmosdb keys list para obter a cadeia de conexão da sua conta de banco de dados do Cosmos DB.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. Copie sua cadeia de conexão do Cosmos DB da saída.

3. Use o comando az iot hub message-endpoint create cosmosdb-container para criar seu endpoint personalizado. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   cosmosdb_connection_string	A cadeia de conexão que você copiou do comando de conta do Cosmos DB.
   container_name	O nome do contêiner em sua conta do Cosmos DB para onde os dados serão enviados.
   database_name	O nome do banco de dados em sua conta do Cosmos DB para onde os dados serão enviados.
   cosmosdb_subscription	ID de assinatura da conta de banco de dados do Cosmos DB. Esse argumento pode ser deixado de lado se o banco de dados estiver na mesma assinatura que o hub IoT.
   cosmosdb_group	Grupo de recursos da conta de banco de dados do Cosmos DB. Esse argumento pode ser deixado de fora se o banco de dados estiver no mesmo grupo de recursos que o hub IoT.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   Nota

   Se você estiver usando identidades gerenciadas em vez de cadeia de conexão, use o comando az cosmosdb sql role assignment create para autenticar sua identidade na conta do Cosmos DB.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

Excluir um ponto de extremidade

Se você quiser excluir um ponto de extremidade do seu hub IoT, use o comando az iot hub message-endpoint delete . Com esse comando, você pode excluir um único ponto de extremidade, excluir todos os pontos de extremidade de um único tipo ou excluir todos os pontos de extremidade de um hub.

Por exemplo, o comando a seguir exclui todos os pontos de extremidade em um hub IoT que apontam para recursos de armazenamento:

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

Criar uma rota do Hub IoT

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. Opcionalmente, você pode Adicionar consultas a rotas de mensagens para filtrar mensagens ou eventos antes que eles vão para o ponto de extremidade.

Nota

Este artigo usa o grupo de comandos az iot hub message-route , que foi introduzido na versão 0.19.0 da extensão azure-iot para a CLI do Azure. As versões anteriores da extensão azure-iot usavam o grupo de comandos az iot hub route , que é semelhante e ainda é suportado.

Use o seguinte comando para atualizar para a versão mais recente da extensão azure-iot:

az extension update --name azure-iot

1. Use o comando az iot hub message-route create para criar uma nova rota do Hub IoT usando esse ponto de extremidade. Forneça os seguintes valores para os parâmetros de espaço reservado:

   parâmetro	valor
   iothub_name	O nome do hub IoT onde essa rota está sendo criada.
   route_name	Um nome exclusivo para a nova rota.
   endpoint_name	O nome do ponto de extremidade para o qual a rota enviará dados.
   data_source	A origem da rota. Os valores aceites são: , , , devicemessagesdevicelifecycleevents, invaliddigitaltwinchangeevents, , ou twinchangeevents. devicejoblifecycleeventsdeviceconnectionstateevents

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. Para confirmar se a nova rota está em seu hub IoT, use o comando az iot hub message-route list para ver todas as rotas em seu hub IoT:

   az iot hub message-route list --hub-name {iothub_name}
   

   Você verá uma resposta na CLI do Azure semelhante a este exemplo:

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

Atualizar uma rota do Hub IoT

Você pode atualizar algumas propriedades de uma rota depois que ela for criada. Você pode alterar a origem, o ponto de extremidade, a condição ou o estado habilitado de uma rota existente.

Use o comando az iot hub message-route show para exibir os detalhes de uma rota.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

Use o comando az iot hub message-route update para atualizar as propriedades de uma rota. Por exemplo, o comando a seguir atualiza a origem da rota.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

Excluir uma rota do Hub IoT

Use o comando az iot hub message-route delete para excluir uma rota do seu hub IoT.

A exclusão de uma rota não exclui seu ponto de extremidade porque outras rotas podem apontar para o mesmo ponto de extremidade. Se quiser excluir um ponto de extremidade, você pode fazê-lo separadamente da exclusão de uma rota.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

Gerenciar a rota de fallback

A rota de fallback envia todas as mensagens da origem que não satisfazem as condições de devicemessages consulta em nenhuma das rotas existentes para o ponto de extremidade interno.

Use o comando az iot hub message-route fallback show para ver o status da rota de fallback em seu hub IoT.

az iot hub message-route fallback show --hub-name {iothub_name}

Use o comando az iot hub message-route fallback set para habilitar ou desabilitar a rota de fallback em seu hub IoT.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

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.