Partilhar via

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

  • Artigo

Este artigo mostra como exportar seu modelo do Hub IoT do Azure, adicionar uma rota ao seu hub IoT e, em seguida, reimplantar o modelo para seu hub IoT usando a CLI do Azure ou o Azure PowerShell. Use 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:

  • Contentores de armazenamento
  • Hubs de Eventos
  • Filas do Service Bus
  • Tópicos do Service Bus
  • Cosmos DB

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

Importante

Quando você usa um modelo do Gerenciador de Recursos para implantar um recurso, o modelo substitui qualquer recurso existente do tipo que você está implantando.

Quando você cria um novo hub IoT, substituir um recurso implantado existente não é uma preocupação. Para criar um novo hub IoT, você pode usar um modelo básico que tenha as propriedades necessárias em vez de exportar um modelo existente de um hub IoT já 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 já implantados não serão substituídos. Por exemplo, um modelo exportado do Gerenciador de Recursos que você implantou anteriormente pode conter informações de armazenamento para seu hub IoT se você o tiver conectado ao armazenamento.

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

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

Modelo Azure Resource Manager

Este artigo usa um modelo do Azure 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, consulte 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 é 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.

Você pode usar um hub de eventos, uma fila ou tópico do Barramento de Serviço ou uma conta de armazenamento do Azure para ser o ponto de extremidade para sua rota de hub IoT. O serviço que você usa para criar seu ponto de extremidade deve primeiro existir em sua conta do Azure.

Exportar o modelo do Gerenciador de Recursos do seu hub IoT

Primeiro, exporte um modelo do Resource Manager do seu hub IoT. Ao exportar o modelo do seu hub IoT, você pode adicionar recursos de ponto de extremidade e roteamento e reimplantar sem perder a configuração existente.

  1. No portal do Azure, vá para seu 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. Exiba o arquivo JSON gerado para seu hub IoT.

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

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

    Captura de ecrã que mostra a localização do botão Transferir no painel Exportar modelo.

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

Adicionar um ponto de extremidade ao modelo

Cada rota aponta para um ponto de extremidade, que é onde as mensagens ou logs de eventos terminam. Crie um ponto de extremidade em seu hub IoT ao qual a rota possa se referir. Você pode usar um hub de eventos, uma fila ou tópico do Service Bus, uma conta de armazenamento do Azure ou um contêiner do Cosmos DB para ser o ponto de extremidade da rota do hub IoT. O serviço que você usa para criar seu ponto de extremidade deve primeiro existir em sua conta do Azure.

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

Adicione um ponto de extremidade de Hubs de Eventos ao seu modelo do Gerenciador de Recursos. Para obter mais informações, consulte Modelo do Azure Resource Manager RoutingEventHubProperties.

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

  2. Substitua a "endpoints": [] linha 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 Hubs de Eventos:

    Property valor
    endpointUri (Se o tipo de autenticação for identityBased; caso contrário, exclua.) 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, exclua.) 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.
    de identidade (Se o tipo de autenticação for identityBased.) Você pode usar uma identidade gerenciada atribuída pelo usuário ou uma identidade gerenciada atribuída pelo sistema se o Hub IoT tiver a identidade gerenciada atribuída pelo sistema habilitada.

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

    Para sistema atribuído: deixe o parâmetro identity 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, em seguida, acrescentar o caminho da entidade.
    nome 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 seu hub de eventos.
    resourceGroup O nome do grupo de recursos que contém o hub de eventos.

    Gorjeta

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

Adicionar uma rota ao modelo

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

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

    Atenção

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

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

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

    Property valor
    nome Forneça um valor exclusivo para nomear sua rota.
    origem Selecione a origem da mensagem ou dos logs de eventos para rotear para o ponto de extremidade. Para obter uma lista de opções de origem, consulte az iot hub route.
    condição Uma consulta para filtrar os dados de origem. Se nenhuma condição for necessária, diga true. Para obter mais informações, consulte Sintaxe da consulta de roteamento de mensagens do Hub IoT.
    endpointNomes O nome do ponto de extremidade existente para onde esses dados serão roteados. Atualmente, apenas um ponto de extremidade é permitido.
    isEnabled Defina como true para habilitar a rota ou false para desabilitar a rota.

  3. Salve seu arquivo JSON.

Implantar o modelo do Gerenciador de Recursos

Com seu novo ponto de extremidade e rota adicionados ao modelo do Gerenciador de Recursos, agora você pode implantar o arquivo JSON de volta ao seu 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, você precisa apenas do nome do arquivo de modelo (em vez do caminho do arquivo inteiro) para usar no template-file parâmetro.

Captura de ecrã que mostra a localização do botão no Azure Cloud Shell para carregar um ficheiro. 

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

Nota

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

Confirmar a implementação

Para confirmar se o modelo foi implantado com êxito no Azure, no portal do Azure, vá para o recurso do grupo de recursos. No menu de recursos em Configurações, selecione Implantações para ver 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, vá para seu recurso do Hub IoT. No painel Roteamento de mensagens, na guia Rotas, confirme se sua rota está listada.

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.