Pontos de extremidade do Hub IoT

O Hub IoT do Azure expõe vários pontos de extremidade para dar suporte aos dispositivos e serviços que interagem com ele.

Nomes de Hub IoT

Você pode encontrar o nome do host de um hub IoT no portal do Azure, no painel de trabalho Visão geral do hub IoT. Por padrão, o nome DNS de um Hub IoT parece com o seguinte exemplo:

{your iot hub name}.azure-devices.net

Pontos de extremidade do Hub IoT para desenvolvimento e gerenciamento

O Hub IoT do Azure é um serviço multilocatário que expõe suas funcionalidades a vários atores. O diagrama a seguir mostra os diversos pontos de extremidade que o Hub IoT expõe.

A lista a seguir descreve os pontos de extremidade:

• Provedor de recursos: uma interface do Azure Resource Manager. Essa interface permite que proprietários de assinatura do Azure criem e excluam Hubs IoT e atualizem as propriedades de Hub IoT. As propriedades do Hub IoT regem as políticas de acesso compartilhado no nível do hub, ao contrário do controle de acesso no nível do dispositivo e das opções funcionais para mensagens da nuvem para dispositivo e do dispositivo para nuvem. O provedor de recursos do Hub IoT também permite exportar identidades do dispositivo.

• Gerenciamento da identidade do dispositivo: um conjunto de pontos de extremidade HTTPS REST para o gerenciamento de identidades do dispositivo (criar, recuperar, atualizar e excluir). As identidades de dispositivo são usadas para controle de acesso e autenticação de dispositivo.

• Gerenciamento de dispositivo gêmeo: um conjunto de pontos de extremidade REST HTTPS voltado para o serviço para consultar e atualizar dispositivos gêmeos (atualizar marcas e propriedades).

• Gerenciamento de trabalhos: um conjunto de ponto de extremidade REST HTTPS voltado para o serviço para consultar e gerenciar trabalhos.

• Pontos de extremidade do dispositivo: um conjunto de pontos de extremidade para cada dispositivo no registro de identidade. Exceto quando observado, esses pontos de extremidade são expostos usando os protocolos MQTT v3.1.1, HTTPS 1.1 e AMQP 1.0. AMQP e MQTT também estão disponíveis em WebSockets na porta 443. Esses pontos de extremidade de dispositivo incluem:

  • Enviar mensagens do dispositivo para a nuvem

  • Receber mensagens da nuvem para o dispositivo

  • Iniciar uploads de arquivo

  • Recuperar e atualizar propriedades do dispositivo gêmeo (não há suporte para HTTPS)

  • Receber solicitações de método direto (não há suporte para HTTPS)

• Ponto de extremidade de serviço: um conjunto de pontos de extremidade para que o seu back-end da sua solução se comunique com os seus dispositivos. Com uma exceção, esses pontos de extremidade são expostos usando apenas os protocolos AMQP e AMQP sobre WebSockets. O ponto de extremidade de invocação de método direto é exposto pelo protocolo HTTPS.

  • Receber mensagens do dispositivo para a nuvem: esse ponto de extremidade é o ponto de extremidade interno discutido nos conceitos de roteamento de mensagens. Um serviço de back-end pode usá-lo para ler as mensagens do dispositivo para nuvem enviadas por seus dispositivos. Você pode criar pontos de extremidade personalizados em seu hub IoT, além desse ponto de extremidade interno.

  • Enviar mensagens da nuvem para o dispositivo e receber confirmações de entrega

  • Habilitar as notificações de upload de arquivos

  • Invocar método direto

O artigo SDKs do Hub IoT do Azure descreve as várias maneiras de acessar esses pontos de extremidade.

Todos os pontos de extremidade do Hub IoT usam o protocolo TLS e nenhum ponto de extremidade é exposto em canais sem criptografia/desprotegidos.

Pontos de extremidade personalizados para roteamento de mensagens

Você pode vincular os serviços existentes a suas assinaturas do Azure ao seu hub IoT para atuar como pontos de extremidade no roteamento de mensagens. Esses agem como pontos de extremidade de serviço e são usados como "coletores" para rotas de mensagens. Os dispositivos não podem gravar diretamente nesses pontos de extremidade. Para obter mais informações sobre roteamento de mensagens, confira Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para diferentes pontos de extremidade.

O Hub IoT dá suporte aos seguintes serviços do Azure como pontos de extremidade personalizados:

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

Para obter os limites de pontos de extremidade por hub, consulte Cotas e limitação.

Ponto de extremidade interno

Você pode usar SDKs e integração padrão dos Hubs de Eventos para receber mensagens de dispositivo para nuvem do ponto de extremidade interno (mensagens/eventos). Depois que qualquer rota é criada, os dados param de fluir para o ponto de extremidade interno, a menos que uma rota seja criada para o ponto de extremidade interno. Mesmo se nenhuma rota for criada, uma rota de fallback deverá ser habilitada para rotear mensagens para o ponto de extremidade integrado. O fallback será habilitado por padrão se você criar seu hub usando o portal ou a CLI.

Armazenamento do Microsoft Azure como um ponto de extremidade de roteamento

Há dois serviços de armazenamento para os quais o Hub IoT pode encaminhar mensagens: contas do Armazenamento de Blobs do Azure e do ADLS Gen2 (Azure Data Lake Storage Gen2). Ambas usam blobs para armazenamento. Para usar o Azure Data Lake Gen2, sua conta de armazenamento deve ter namespaces hierárquicos habilitados. Para obter mais informações, confira Criar uma conta de armazenamento para usá-la com o Azure Data Lake Storage.

O Hub IoT dá suporte à gravação de dados no Armazenamento do Azure no formato Apache Avro e JSON. O padrão é AVRO. Para usar a codificação JSON, defina a propriedade contentType como application/json e a propriedade contentEncoding como UTF-8 nas propriedades do sistema de mensagem. Esses dois valores não diferenciam maiúsculas de minúsculas. Se a codificação de conteúdo não estiver definida, o Hub IoT grava as mensagens no formato codificado de base 64.

O formato de codificação só pode ser definido quando o ponto de extremidade do armazenamento de blob estiver configurado; ele não pode ser editado para um ponto de extremidade existente.

O Hub IoT envia lotes de mensagens e grava dados no armazenamento sempre que o lote atinge um determinado tamanho ou após um determinado período de tempo decorrido. O Hub IoT segue a seguinte convenção de nomenclatura de arquivo padrão: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm} Você pode usar qualquer convenção de nomenclatura de arquivo, mas é necessário usar todos os tokens listados. O Hub IoT grava em um blob vazio se não houver nenhum dado para gravação.

É recomendável listar os blobs ou arquivos e iterar sobre eles, para garantir que todos os blobs ou arquivos sejam lidos sem fazer nenhuma suposição de partição. O intervalo de partição potencialmente pode ser alterado durante um failover iniciado pela Microsoft ou failover manual do Hub IoT. Você pode usar a Listar API de blobs para enumerar a lista de blobs ou Listar API de ADLS Gen2 para a lista de arquivos. Por exemplo:

public void ListBlobsInContainer(string containerName, string iothub)
{
    var storageAccount = CloudStorageAccount(Microsoft.Azure.Storage.Auth.StorageCredentials storageCredentials, bool useHttps);
    var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
    if (cloudBlobContainer.Exists())
    {
        var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
        foreach (IListBlobItem item in results)
        {
            Console.WriteLine(item.Uri);
        }
    }
}

Filas do Barramento de Serviço e Tópicos do Barramento de Serviço como um ponto de extremidade de roteamento

As filas e os tópicos do Barramento de Serviço utilizados como pontos de extremidade do Hub IoT não devem ter Sessões nem Detecção Duplicada habilitadas. Se qualquer uma dessas opções estiver habilitada, o ponto de extremidade aparecerá como Inacessível no Portal do Azure.

Hubs de Eventos como um ponto de extremidade de roteamento

Além do ponto de extremidade compatível com os Hubs de Eventos internos, você também pode encaminhar dados para pontos de extremidade personalizados do tipo Hubs de Eventos.

Azure Cosmos DB como um ponto de extremidade de roteamento

Você pode enviar dados diretamente para o Azure Cosmos DB do Hub IoT. O Hub IoT dá suporte à gravação no Cosmos DB em JSON (se especificado no tipo de conteúdo da mensagem) ou como binário codificado em Base64.

Para dar suporte a cenários de alta escala, você pode habilitar chaves de partição sintéticas para o ponto de extremidade do Cosmos DB. Como o Cosmos DB é um armazenamento de dados em hiperescala, todos os dados/documentos gravados nele devem conter um campo que represente uma partição lógica. Cada partição lógica tem um tamanho máximo de 20 GB. Você pode especificar o nome da propriedade da chave de partição em Nome da chave de partição. O nome da propriedade da chave de partição é definido no nível do contêiner e não pode ser atualizado.

Você pode configurar o valor da chave de partição sintética especificando um modelo em Modelo de chave de partição com base no volume de dados estimado. Por exemplo, em cenários de fabricação, espera-se que sua partição lógica se aproxime do limite máximo de 20 GB em um mês. Nesse caso, você pode definir uma chave de partição sintética como uma combinação da ID do dispositivo e do mês. O valor da chave de partição gerada é adicionado automaticamente à propriedade da chave de partição para cada novo registro do Cosmos DB, garantindo que partições lógicas sejam criadas mensalmente para cada dispositivo.

Integridade do ponto de extremidade

Você pode usar a API REST Obter integridade do ponto de extremidade para obter o status da integridade dos pontos de extremidade. É recomendável usar as métricas de roteamento do Hub IoT, relacionadas à latência da mensagem de roteamento, para a identificação e depuração de erros quando a integridade do ponto de extremidade estiver inativa ou não íntegra, porque esperamos que a latência seja maior quando o ponto de extremidade estiver em um desses estados. Para saber mais sobre o uso das métricas do Hub IoT, confira Monitorar o Hub IoT.

Próximas etapas

Saiba mais sobre estes tópicos:

• Linguagem de consulta do Hub IoT para dispositivos e módulos gêmeos, trabalhos e roteamento de mensagens
• Cotas e limitação do Hub IoT
• Comunicar com o Hub IoT usando o protocolo MQTT
• Endereços IP do Hub IoT