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

Esse artigo mostra como gerenciar as 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 Microsoft Azure e Cosmos DB.

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:

• 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, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Hub IoT

Tenha um hub IoT em sua assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

Serviço de ponto de extremidade

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 roteados de evento e dispositivo: um hub de eventos, uma fila ou um 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 Evento

1. Criar um namespace de Hubs de Eventos e um hub de eventos. Para obter mais informações, confira 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 conceder permissão ao Hub IoT para enviar dados para o hub de eventos.

   Dica

   O valor name do parâmetro RootManageSharedAccessKey é o nome padrão que permite gerenciar, enviar, ouvir declarações (acesso). Se desejar restringir as declarações, dê ao parâmetro name seu próprio nome exclusivo e inclua o sinalizador --rights seguido de 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 o acesso aos Hubs de Eventos do Azure.

Fila do Barramento de Serviço

1. Criar um namespace do Barramento de Serviço e da fila. Para obter mais informações, confira Usar a CLI do Azure para criar um namespace e uma fila do Barramento de Serviço.

2. Crie uma regra de autorização que irá conceder permissão ao Hub IoT para enviar dados para a fila. Para name, use um valor exclusivo para a 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, confira az servicebus queue authorization-rule create.

Tópico do Barramento de Serviço

Crie um namespace, um tópico e uma assinatura para o Barramento de Serviço. Para obter mais informações, confira Usar a CLI do Azure para criar um tópico do Barramento de Serviço e assinaturas para o tópico.

Armazenamento do Azure

1. Criar uma conta de armazenamento. Para obter mais informações, consulte 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 do SQL e um contêiner do Cosmos DB. Para saber mais, confira Criar uma conta do Azure Cosmos DB for NoSQL.

Criar um ponto de extremidade

Todas as rotas do Hub IoT apontam para um ponto de extremidade, que receberá os dados roteados de dispositivo e evento. Mais de uma rota pode apontar para o mesmo ponto de extremidade. Atualmente, o Hub IoT dá suporte a pontos de extremidade para hubs de eventos, filas ou tópicos do Barramento de Serviço, 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 você criar o ponto de extremidade.

Observação

Esse 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 tem suporte, mas não dá suporte à criação de pontos de extremidade do Cosmos DB.

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

az extension update --name azure-iot

Hubs de Evento

Para criar um ponto de extremidade dos 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 valores a seguir para os parâmetros de espaço reservado:

   parâmetro	value
   eventhub_group	Grupo de recursos do hub de eventos.
   eventhub_namespace	Nome do namespace dos 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 será 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 sua cadeia de conexão do hub de eventos a partir da saída.

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

   parâmetro	value
   iothub_name	O nome do hub IoT em que esse ponto de extremidade está sendo criado.
   endpoint_name	Um nome exclusivo para o novo ponto de extremidade.
   eventhub_subscription	ID da assinatura do hub de eventos. Esse argumento poderá ser deixado de fora se o hub de eventos estiver na mesma assinatura que o Hub IoT.
   eventhub_group	Grupo de recursos do hub de eventos. Esse argumento poderá ser deixado de fora 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 Barramento de Serviço

Para criar um ponto de extremidade da fila do Barramento de Serviço, 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 da fila do Barramento de Serviço. Forneça os valores a seguir para os parâmetros de espaço reservado:

   parâmetro	value
   queue_group	Grupo de recursos da fila do Barramento de Serviço.
   queue_namespace	Nome do namespace da fila do Barramento de Serviço.
   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 será 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 sua cadeia de conexão da fila do Barramento de Serviço a partir da saída.

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

   parâmetro	value
   iothub_name	O nome do hub IoT em que 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 da fila do Barramento de Serviço.
   queue_subscription	ID da assinatura da fila do Barramento de Serviço. Esse argumento poderá ser deixado de fora se a fila estiver na mesma assinatura que o Hub IoT.
   queue_group	Grupo de recursos da fila do Barramento de Serviço. Esse argumento poderá 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 Barramento de Serviço

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

   parâmetro	value
   topic_group	Grupo de recursos do tópico do Barramento de Serviço.
   topic_namespace	Nome do namespace do tópico do Barramento de Serviço.
   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 sua cadeia de conexão do tópico do Barramento de Serviço a partir da saída.

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

   parâmetro	value
   iothub_name	O nome do hub IoT em que 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 do tópico do Barramento de Serviço.
   topic_subscription	ID da assinatura do tópico do Barramento de Serviço. Esse argumento poderá ser deixado de fora se o tópico estiver na mesma assinatura que o Hub IoT.
   topic_group	Grupo de recursos do tópico do Barramento de Serviço. Esse argumento poderá ser deixado de fora 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 Microsoft Azure para criar um ponto de extremidade. Forneça os valores a seguir para os parâmetros de espaço reservado:

   parâmetro	value
   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 sua cadeia de conexão da conta de armazenamento a partir 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 Microsoft Azure. Para todos os outros parâmetros, use os valores para seu cenário. Forneça os valores a seguir para os parâmetros de espaço reservado:

   parâmetro	value
   iothub_name	O nome do hub IoT em que 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 da 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 da assinatura de armazenamento do Barramento de Serviço. Esse argumento poderá ser deixado de fora se o armazenamento estiver na mesma assinatura que o Hub IoT.
   storage_group	Grupo de recursos do armazenamento do Barramento de Serviço. Esse argumento poderá ser deixado de fora 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 a partir da saída.

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

   parâmetro	value
   iothub_name	O nome do hub IoT em que 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 da 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 da assinatura da conta de banco de dados do Cosmos DB. Esse argumento poderá ser deixado de fora 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 poderá 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
   

   Observação

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

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

Observação

Esse 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 tem suporte.

Use o comando a seguir 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 valores a seguir para os parâmetros de espaço reservado:

   parâmetro	value
   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 aceitos são deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid ou twinchangeevents.

   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á no seu hub IoT, use o comando az iot hub message-route list para ver todas as rotas no seu hub IoT:

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

   Você deve 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 origem, ponto de extremidade, condição ou estado de 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 a partir do hub IoT.

Excluir uma rota não exclui seu ponto de extremidade porque outras rotas podem apontar para o mesmo ponto de extremidade. Se você quiser excluir um ponto de extremidade, poderá fazer isso 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 devicemessages que não atendem às condições de 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 no 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 no seu hub IoT.

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

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.