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.
Observação
Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, dispositivos gêmeos e gerenciamento de dispositivo estão disponíveis somente na camada Standard do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para sua solução.
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.
Importante
A funcionalidade a seguir para dispositivos que usam a autenticação de autoridade de certificação (CA) do certificado X.509 ainda não está disponível e o modo de visualização deve ser habilitado:
- HTTPS, MQTT por WebSockets e AMQP por protocolos WebSockets.
- Carregamentos de arquivos (todos os protocolos).
Geralmente, esses recursos estão em disponibilidade geral em dispositivos que usam a autenticação de impressão digital X.509. Para saber mais sobre a autenticação X.509 com o Hub IoT, confira Certificados X.509 com suporte.
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.
Atualmente, o Hub IoT dá suporte aos seguintes serviços do Azure como pontos de extremidade personalizados:
- Contêineres de armazenamento
- Hubs de Eventos
- Filas de barramento de serviço
- Tópicos do Service Bus
- 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 esse ponto de extremidade. 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.
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.Parse(this.blobConnectionString);
var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
if (cloudBlobContainer.Exists())
{
var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
foreach (IListBlobItem item in results)
{
Console.WriteLine(item.Uri);
}
}
}
Para criar uma conta de armazenamento compatível com Azure Data Lake Gen2, crie uma nova conta de armazenamento V2 e selecione Habilitar namespace hierárquico na seção Data Lake Storage Gen2 da guia Avançado, conforme mostrado na seguinte imagem:
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 alterado posteriormente.
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.
Cuidado
Se estiver usando a identidade gerenciada atribuída pelo sistema para autenticação no Cosmos DB, você deverá usar a CLI do Azure ou o Azure PowerShell para atribuir a definição de função interna do colaborador de dados interno do Cosmos DB à identidade. Atualmente, não há suporte para a atribuição de função para o Cosmos DB no portal do Azure. Para obter mais detalhes sobre as várias funções, consulte Configurar o acesso baseado em função para o Azure Cosmos DB. Para entender a atribuição de funções por meio da CLI, confira Gerenciar recursos de função SQL do Azure Cosmos DB.
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.
| Status de integridade | Descrição |
|---|---|
| Healthy | O ponto de extremidade está aceitando mensagens como esperado. |
| não íntegro | O ponto de extremidade não está aceitando mensagens e o Hub IoT está tentando novamente enviar mensagens para esse ponto de extremidade. |
| unknown | O Hub IoT não tentou entregar mensagens para esse ponto de extremidade. |
| degradado | O ponto de extremidade está aceitando mensagens mais lentamente do que o esperado ou está se recuperando de um estado não íntegro. |
| inativo | O Hub IoT não está mais entregando mensagens para esse ponto de extremidade. Falha ao tentar reenviar mensagens para esse ponto de extremidade. |
Próximas etapas
Saiba mais sobre estes tópicos: