Criar e eliminar rotas e pontos finais com a CLI do Azure

Este artigo mostra-lhe como gerir Hub IoT do Azure rotas e pontos finais com a CLI do Azure. Saiba como utilizar a CLI do Azure para criar rotas e pontos finais para Hubs de Eventos do Azure, Azure Service Bus filas e tópicos, Armazenamento do Azure e Cosmos DB.

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:

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

CLI do Azure

Este artigo utiliza a CLI do Azure para trabalhar com Hub IoT e outros serviços do Azure. Pode escolher como aceder à CLI do Azure:

• Utilize o ambiente bash no Azure Cloud Shell. Para obter mais informações, veja Início Rápido do 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, veja Como executar a CLI do Azure num contentor 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 início de sessão, veja Iniciar sessão com a CLI do Azure.

  • Quando lhe for pedido, 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

Precisa de 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 a CLI do Azure.

Serviço de ponto final

Precisa de, pelo menos, outro serviço do Azure para utilizar como ponto final para a rota. O ponto final recebe mensagens do dispositivo e registos de eventos.

Decida que serviço do Azure pretende utilizar como ponto final para receber dados de eventos e dispositivos encaminhados: um hub de eventos, uma Fila de serviços ou um tópico, uma conta de armazenamento ou um contentor do Cosmos DB. Para o serviço que escolher utilizar, conclua os passos para criar um serviço de ponto final.

Hubs de Eventos

1. Crie um espaço de nomes dos Hubs de Eventos e um hub de eventos. Para obter mais informações, veja Início Rápido: Criar um hub de eventos com a CLI do Azure.

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

   Dica

   O name valor RootManageSharedAccessKey do parâmetro é o nome predefinido que permite gerir, enviar, escutar afirmações (acesso). Se quiser restringir as afirmações, atribua ao parâmetro o name seu próprio nome exclusivo e inclua o --rights sinalizador seguido de uma das afirmaçõ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, veja Autorizar o acesso ao 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, veja Utilizar a CLI do Azure para criar um espaço de nomes do Service Bus e uma fila.

2. Crie uma regra de autorização que dê permissão Hub IoT para enviar dados para a fila. Para name, utilize 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 regras de autorização, veja az servicebus queue authorization-rule create.

Tópico do Service Bus

Crie um espaço de nomes, tópico e subscrição do Service Bus. Para obter mais informações, veja Utilizar a CLI do Azure para criar um tópico e subscrições do Service Bus 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 contentor na sua conta de armazenamento. Para obter mais informações, veja Gerir contentores de blobs com a CLI do Azure

BD do Cosmos

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

Criar um ponto final

Todas as rotas Hub IoT apontam para um ponto final, que receberá os dados de eventos e dispositivos encaminhados. Mais do que uma rota pode apontar para o mesmo ponto final. Atualmente, Hub IoT suporta pontos finais para Hubs de eventos, filas ou tópicos do Service Bus, Armazenamento e Cosmos DB. Uma instância do serviço que utiliza para o ponto final tem de existir na sua subscrição do Azure antes de criar o ponto final.

Nota

Este artigo utiliza 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 utilizaram o grupo de comandos az iot hub routing-endpoint , que é semelhante e ainda é suportado, mas não suporta a criação de pontos finais do Cosmos DB.

Utilize 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 final dos Hubs de Eventos, utilize a regra de autorização que criou nos pré-requisitos.

1. Utilize o comando az eventhubs eventhub authorization-rule keys para listar a regra de autorização. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   eventhub_group	Grupo de recursos do hub de eventos.
   eventhub_namespace	Nome do espaço de nomes 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 copiou o exemplo nos pré-requisitos, este 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 ligação do hub de eventos da saída.

3. Utilize o comando az iot hub message-endpoint create eventhub para criar o ponto final personalizado. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde este ponto final está a ser criado.
   endpoint_name	Um nome exclusivo para o novo ponto final.
   eventhub_subscription	ID de subscrição do hub de eventos. Este argumento pode ser deixado de fora se o hub de eventos estiver na mesma subscrição que o hub IoT.
   eventhub_group	Grupo de recursos do hub de eventos. Este argumento pode 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 ligação que 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 final de fila do Service Bus, utilize a regra de autorização que criou nos pré-requisitos.

1. Utilize o comando az servicebus queue authorization-rule keys list para obter a cadeia de ligação da fila do Service Bus. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   queue_group	Grupo de recursos da fila do Service Bus.
   queue_namespace	Nome do espaço de nomes da fila do Service Bus.
   queue_name	Nome da fila.
   rule_name	O nome da regra de autorização da fila. Se copiou o exemplo nos pré-requisitos, este 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 ligação da fila do Service Bus da saída.

3. Utilize o comando az iot hub message-endpoint create servicebus-queue para criar o seu ponto final personalizado. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde este ponto final está a ser criado.
   endpoint_name	Um nome exclusivo para o novo ponto final.
   queue_connection_string	A cadeia de ligação que copiou da regra de autorização da fila do Service Bus.
   queue_subscription	ID da subscrição da fila do Service Bus. Este argumento pode ser deixado de fora se a fila estiver na mesma subscrição que o hub IoT.
   queue_group	Grupo de recursos da fila do Service Bus. Este 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. Utilize a lista az servicebus topic authorization-rule keys para obter a cadeia de ligação do tópico do Service Bus. O nome predefinido da regra de autorização fornecida com um novo espaço de nomes é RootManageSharedAccessKey. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   topic_group	Grupo de recursos do tópico Service Bus.
   topic_namespace	Nome do espaço de nomes 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 ligação do tópico do Service Bus a partir da saída.

3. Utilize o comando az iot hub message-endpoint create servicebus-topic para criar o seu ponto final personalizado. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde este ponto final está a ser criado.
   endpoint_name	Um nome exclusivo para o novo ponto final.
   topic_connection_string	A cadeia de ligação que copiou da regra de autorização do tópico do Service Bus.
   topic_subscription	ID da subscrição do tópico Service Bus. Este argumento pode ser deixado de fora se o tópico estiver na mesma subscrição que o hub IoT.
   topic_group	Grupo de recursos do tópico Service Bus. Este argumento pode 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. Utilize o comando az storage account show-connection-string para obter a cadeia de ligação do recurso de Armazenamento do Azure para criar um ponto final. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	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 ligação da conta de armazenamento da saída.

3. Utilize o comando az iot hub message-endpoint create storage-container para criar um novo ponto final do Armazenamento do Azure. Para todos os outros parâmetros, utilize valores para o seu cenário. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde este ponto final está a ser criado.
   endpoint_name	Um nome exclusivo para o novo ponto final.
   storage_connection_string	A cadeia de ligação que copiou do comando da conta de armazenamento.
   container_name	O nome do contentor na sua conta de armazenamento para onde os dados serão enviados.
   storage_subscription	ID da subscrição do armazenamento do Service Bus. Este argumento pode ser deixado de fora se o armazenamento estiver na mesma subscrição que o hub IoT.
   storage_group	Grupo de recursos do armazenamento do Service Bus. Este argumento pode 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}
   

BD do Cosmos

1. Utilize o comando az cosmosdb keys list para obter a cadeia de ligação da sua conta de base de dados do Cosmos DB.

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

2. Copie a cadeia de ligação do Cosmos DB a partir da saída.

3. Utilize o comando az iot hub message-endpoint create cosmosdb-container para criar o seu ponto final personalizado. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde este ponto final está a ser criado.
   endpoint_name	Um nome exclusivo para o novo ponto final.
   cosmosdb_connection_string	A cadeia de ligação que copiou do comando da conta do Cosmos DB.
   container_name	O nome do contentor na sua conta do Cosmos DB para onde os dados serão enviados.
   database_name	O nome da base de dados na sua conta do Cosmos DB para onde os dados serão enviados.
   cosmosdb_subscription	ID de subscrição da conta de base de dados do Cosmos DB. Este argumento pode ser deixado de fora se a base de dados estiver na mesma subscrição que o hub IoT.
   cosmosdb_group	Grupo de recursos da conta de base de dados do Cosmos DB. Este argumento pode ser deixado de fora se a base 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 estiver a utilizar identidades geridas em vez da cadeia de ligação, utilize o comando az cosmosdb sql role assignment create para autenticar a 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"
   

Eliminar um ponto final

Se quiser eliminar um ponto final do hub IoT, utilize o comando az iot hub message-endpoint delete . Com este comando, pode eliminar um único ponto final, eliminar todos os pontos finais de um único tipo ou eliminar todos os pontos finais de um hub.

Por exemplo, o comando seguinte elimina todos os pontos finais num 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 de Hub IoT

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. Opcionalmente, pode Adicionar consultas a rotas de mensagens para filtrar mensagens ou eventos antes de acederem ao ponto final.

Nota

Este artigo utiliza 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 utilizaram o grupo de comandos az iot hub route , que é semelhante e ainda é suportado.

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

az extension update --name azure-iot

1. Utilize o comando az iot hub message-route create para criar uma nova rota de Hub IoT com esse ponto final. Indique os seguintes valores para os parâmetros do marcador de posição:

   parameter	valor
   iothub_name	O nome do hub IoT onde esta rota está a ser criada.
   route_name	Um nome exclusivo para a nova rota.
   endpoint_name	O nome do ponto final para o qual a rota enviará dados.
   data_source	A origem da rota. Os valores aceites são: deviceconnectionstateevents, , devicejoblifecycleeventsdevicelifecycleevents, devicemessages, , digitaltwinchangeeventsou invalidtwinchangeevents.

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

2. Para confirmar que a nova rota está no hub IoT, utilize 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}
   

   Deverá 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 de Hub IoT

Pode atualizar algumas propriedades de uma rota depois de ser criada. Pode alterar o estado de origem, ponto final, condição ou ativado de uma rota existente.

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

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

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

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

Eliminar uma rota de Hub IoT

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

Eliminar uma rota não elimina o ponto final porque outras rotas podem apontar para o mesmo ponto final. Se quiser eliminar um ponto final, pode fazê-lo separadamente da eliminação de uma rota.

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

Gerir a rota de contingência

A rota de contingência envia todas as mensagens da devicemessages origem que não satisfazem as condições de consulta em nenhuma das rotas existentes para o ponto final incorporado.

Utilize o comando az iot hub message-route fallback show para ver o estado da rota de contingência no seu hub IoT.

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

Utilize o comando az iot hub message-route fallback set para ativar ou desativar a rota de contingência no seu hub IoT.

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

Passos seguintes

Neste artigo de procedimentos, aprendeu a criar uma rota e um 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 Microsoft 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.