Compartilhar via

Criar e excluir rotas e pontos de extremidade usando o Azure Resource Manager

  • Artigo

Este artigo mostra como exportar o modelo Hub IoT do Azure, adicionar uma rota a ele e, em seguida, implantar o modelo novamente no Hub IoT usando a CLI do Azure ou o Azure PowerShell. Usar um modelo do Azure Resource Manager para criar rotas e pontos de extremidade. O Hub IoT dá suporte aos seguintes serviços do Azure como pontos de extremidade:

  • Contêineres de armazenamento
  • Hubs de Eventos
  • Filas do Barramento de Serviço
  • Tópicos do Barramento de Serviço
  • Cosmos DB

Os modelos do ARM são úteis quando você deseja definir recursos usando um arquivo JSON. Cada recurso do Azure tem um modelo que define os componentes usados nesse recurso. Você pode exportar todos os modelos de recursos do Azure.

Importante

Quando você usa um modelo do Resource Manager para implantar um recurso, o modelo substitui todo recurso existente do tipo que você está implantando.

Ao criar um hub IoT, não está em questão a substituição de um recurso implantado existente. Para criar um hub IoT, você pode usar um modelo básico que tem as propriedades necessárias em vez de exportar um modelo existente de um hub IoT que já está implantado.

No entanto, se você adicionar uma rota a um hub IoT existente, use um modelo exportado do hub IoT para garantir que todos os recursos e propriedades existentes permaneçam conectados depois de implantar o modelo atualizado. Os recursos que já estão implantados não serão substituídos. Por exemplo, um modelo do Resource Manager exportado que você implantou anteriormente pode conter informações de armazenamento para o hub IoT, se você o tiver conectado ao armazenamento.

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 percorrer as etapas para configurar 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

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

Modelo do Azure Resource Manager

Este artigo usa um modelo do Resource Manager no portal do Azure para trabalhar com o Hub IoT e outros serviços do Azure. Para saber mais sobre como usar modelos do Resource Manager, confira O que são modelos do Azure Resource Manager?

Criar uma rota

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 do Azure 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.

Exporte o modelo do Resource Manager do hub IoT

Primeiro, exporte o modelo do Resource Manager a partir do hub IoT. Ao exportar o modelo, você pode adicionar recursos de ponto de extremidade e rota, além de reimplantá-los sem perder as configurações existentes.

  1. No portal do Azure, vá para o hub IoT. No menu de recursos, em Automação, selecione Exportar modelo.

    Captura de tela que mostra o local da opção Exportar modelo no menu de um recurso do Hub IoT.

  2. Em Exportar modelo, na guia Modelo, conclua estas etapas:

    1. Exibir o arquivo JSON que é gerado no hub IoT.

    2. Desmarcar a caixa de seleção Incluir parâmetros.

    3. Selecionar Download para baixar uma cópia local do arquivo JSON.

    Captura de tela que mostra o local do botão Download no painel Exportar modelo.

    O modelo tem vários espaços reservados que você pode usar para adicionar recursos ou serviços ao hub IoT. Para este artigo, adicione valores somente às propriedades que estão em ou aninhadas em routing.

Adicione um ponto de extremidade ao modelo

Cada rota aponta para um endpoint, que é o destino final das mensagens ou logs de eventos. Crie um ponto de extremidade no hub IoT para que a rota possa referenciá-lo. Você pode usar um hub de eventos, uma fila ou um tópico do Barramento de Serviço, uma conta de armazenamento ou um contêiner do Cosmos DB para ser o 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.

O IoT Hub precisa de permissões de acesso para qualquer recurso de ponto de extremidade ao qual envie mensagens ou logs. Você pode fornecer acesso usando identidades gerenciadas e o Microsoft Entra ID ou usando cadeias de conexão. A Microsoft recomenda a autenticação com o Entra ID como a opção mais segura.

Adicione um novo ponto de extremidade dos Hubs de Eventos ao modelo do Resource Manager. Para obter mais informações, confira o artigo RoutingEventHubProperties do Azure Resource Manager.

  1. No arquivo JSON, localize a propriedade "endpoints": [] aninhada em "routing".

  2. Substitua a linha "endpoints": [] pelo seguinte JSON:

    "endpoints": {
    "serviceBusQueues": [],
    "serviceBusTopics": [],
    "eventHubs": [
        {
            "endpointUri": "",
            "entityPath": "",
            "authenticationType": "identityBased",
            "identity": {
                "userAssignedIdentity": ""
            },
            "name": "",
            "id": "",
            "subscriptionId": "",
            "resourceGroup": ""
        }
    ],
    "storageContainers": [],
    "cosmosDBSqlContainers": []
},

  3. Atualize o JSON com as seguintes informações sobre o recurso dos Hubs de Eventos:

    Propriedade Valor
    endpointUri (Se o tipo de autenticação for identityBased; caso contrário, delete.) O nome do host do namespace dos Hubs de Eventos no formato sb://<eventhubs_namespace_name>.servicebus.windows.net
    entityPath (Se o tipo de autenticação for identityBased; caso contrário, delete.) O nome do seu hub de eventos.
    authenticationType identityBased ou keyBased. A Microsoft recomenda a autenticação baseada em identidade como a opção mais segura.
    identidade (Se o tipo de autenticação for identityBased.) Você pode usar uma identidade gerenciada atribuída pelo usuário ou habilitar a identidade gerenciada atribuída pelo sistema no Hub IoT para utilizá-la.

    Para identidades atribuídas pelo usuário: a ID externa da identidade gerenciada com permissões de acesso ao hub de eventos no formato /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>.

    Para identidades atribuídas pelo sistema: deixe o parâmetro de identidade como uma lista vazia. Por exemplo, "identity": {},
    connectionString (Se o tipo de autenticação for keyBased.) A cadeia de conexão primária de uma das políticas de acesso compartilhado do hub de eventos no formato <connection_string>;EntityPath=<event_hub_name>.. Você pode recuperar o valor da cadeia de conexão do portal do Azure e acrescentar o caminho da entidade.
    name Forneça um valor exclusivo para nomear seu ponto de extremidade.
    ID Deixe como uma cadeia de caracteres vazia. O serviço do Azure fornece um valor quando você cria o ponto de extremidade.
    subscriptionId A ID da assinatura que contém o hub de eventos.
    resourceGroup O nome do grupo de recursos que contém o hub de eventos.

    Dica

    Para o gerenciamento de segredos, você pode Criar um arquivo de parâmetros ou Usar o Azure Key Vault para passar valores de parâmetro seguros durante a implantação.

Adicionar uma rota ao modelo

Adicione uma definição de rota ao modelo do Resource Manager. Para obter mais informações, confira o artigo RouteProperties do Azure Resource Manager.

  1. No arquivo JSON, localize a propriedade "routes": [], aninhada em "routing"e adicione uma nova rota.

    Cuidado

    Se você substituir os valores existentes para "routes" pelos valores de rota usados nos exemplos de código a seguir, as rotas existentes serão removidas quando você implantar. Para preservar as rotas existentes, adicione o novo objeto de rota à lista "routes".

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

  2. Atualize o JSON com as seguintes informações sobre o recurso do Cosmos DB:

    Propriedade Valor
    name Forneça um valor exclusivo para nomear sua rota.
    source Selecione a origem das mensagens ou logs de evento para rotear para o ponto de extremidade. Para uma lista de opções de origem, confira az iot hub route.
    condition Uma consulta para filtrar os dados de origem. Se nenhuma condição for necessária, insira true. Para saber mais, confira sintaxe de consultado roteamento de mensagens do Hub IoT.
    endpointNames O nome do ponto de extremidade existente onde esses dados serão roteados. No momento, apenas um ponto de extremidade é permitido.
    isEnabled Defina como true para habilitar a rota ou false para desabilitá-la.

  3. Salve o arquivo JSON.

Implantar o modelo do Resource Manager

Com o novo ponto de extremidade e a rota adicionada ao modelo do ARM, agora você pode implantar o arquivo JSON novamente no hub IoT.

Implantação local

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

Implantação do Azure Cloud Shell

Como o Azure Cloud Shell é executado em um navegador da Web, você pode carregar o arquivo de modelo antes de executar o comando de implantação. Com o arquivo carregado, é necessário apenas o nome do arquivo de modelo (em vez de todo o caminho do arquivo) para usar no parâmetro template-file.

Captura de tela que mostra o local do botão no Azure Cloud Shell para carregar um arquivo. 

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

Observação

Se a implantação falhar, use a opção -verbose para obter informações sobre os recursos que você está criando. Use a opção -debug para obter mais informações de depuração.

Confirmar implantação

Para confirmar se o modelo foi implantado com êxito no Azure, no portal do Azure, acesse o recurso do grupo de recursos. No menu de recursos em Configurações, selecione Implantações para exibir o modelo em uma lista de suas implantações.

Captura de tela que mostra uma lista de implantações para um recurso no portal do Azure, com um modelo de teste realçado.

Para exibir sua nova rota no portal do Azure, acesse o recurso do Hub IoT. No painel Roteamento de mensagens, na guia Rotas, confirme se a rota está listada.

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.