Pontos finais 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.
Nota
Alguns dos recursos mencionados neste artigo, como mensagens de nuvem para dispositivo, gêmeos de dispositivo e gerenciamento de dispositivos, estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, consulte Escolha a camada certa do Hub IoT para sua solução.
Nomes do 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 se parece com o exemplo a seguir:
{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 sua funcionalidade a vários atores. O diagrama a seguir mostra os vários 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 os proprietários de assinaturas do Azure criem e excluam hubs IoT e atualizem as propriedades do hub IoT. As propriedades do Hub IoT regem as políticas de acesso compartilhado no nível do hub, em oposição ao controle de acesso no nível do dispositivo, e as opções funcionais para mensagens de nuvem para dispositivo e de dispositivo para nuvem. O provedor de recursos do Hub IoT também permite exportar identidades de dispositivo.
Gerenciamento de identidade de dispositivo: um conjunto de pontos de extremidade HTTPS REST para gerenciar identidades de dispositivo (criar, recuperar, atualizar e excluir). As identidades de dispositivo são usadas para autenticação de dispositivo e controle de acesso.
Gerenciamento de gêmeos de dispositivos: um conjunto de pontos de extremidade HTTPS REST voltados para o serviço para consultar e atualizar gêmeos de dispositivo (atualizar tags e propriedades).
Gerenciamento de trabalhos: um conjunto de pontos de extremidade HTTPS REST voltados 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 onde 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 através de WebSockets na porta 443. Esses pontos de extremidade do dispositivo incluem:
Enviar mensagens do dispositivo para a nuvem
Receba mensagens da nuvem para o dispositivo
Iniciar carregamentos de ficheiros
Recuperar e atualizar propriedades gêmeas do dispositivo (HTTPS não é suportado)
Receber solicitações diretas de método (HTTPS não é suportado)
Pontos de extremidade de serviço: um conjunto de pontos de extremidade para que seu back-end de solução se comunique com seus dispositivos. Com uma exceção, esses pontos de extremidade só são expostos usando os protocolos AMQP e AMQP sobre WebSockets. O ponto de extremidade de invocação direta do método é exposto pelo protocolo HTTPS.
Receber mensagens do dispositivo para a nuvem: este ponto de extremidade é o ponto de extremidade interno discutido nos conceitos de roteamento de mensagens. Um serviço back-end pode usá-lo para ler as mensagens do dispositivo para a nuvem enviadas pelos seus dispositivos. Você pode criar pontos de extremidade personalizados em seu hub IoT, além desse ponto de extremidade interno.
Envie mensagens da nuvem para o dispositivo e receba confirmações de entrega
Receber 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 não criptografados/não seguros.
Importante
A seguinte funcionalidade para dispositivos que usam a autenticação de autoridade de certificação (CA) X.509 ainda não está disponível em geral e o modo de visualização deve ser habilitado:
- HTTPS, MQTT sobre WebSockets e AMQP sobre protocolos WebSockets.
- Upload de arquivos (todos os protocolos).
Esses recursos estão geralmente disponíveis em dispositivos que usam autenticação de impressão digital X.509. Para saber mais sobre a autenticação X.509 com o Hub IoT, consulte Certificados X.509 suportados.
Pontos de extremidade personalizados para roteamento de mensagens
Você pode vincular serviços existentes do Azure em suas assinaturas do Azure ao seu hub IoT para atuar como pontos de extremidade para roteamento de mensagens. Esses pontos de extremidade atuam 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, consulte 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:
- Contentores de armazenamento
- Hubs de Eventos
- Filas do Service Bus
- 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 integrado
Você pode usar a integração padrão de Hubs de Eventos e SDKs para receber mensagens do dispositivo para a 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 que nenhuma rota seja criada, uma rota de fallback deve ser habilitada para rotear mensagens para o ponto de extremidade interno. O fallback é habilitado por padrão se você criar seu hub usando o portal ou a CLI.
Armazenamento do Microsoft Azure como um ponto final de encaminhamento
Há dois serviços de armazenamento para os quais o Hub IoT pode rotear mensagens: contas do Azure Blob Storage e Azure Data Lake Storage Gen2 (ADLS Gen2). Ambos usam blobs para seu armazenamento. Para usar o Azure Data Lake Gen2, sua conta de armazenamento deve ter namespaces hierárquicos habilitados. Para obter mais informações, consulte Criar uma conta de armazenamento para usar com o Armazenamento do Azure Data Lake.
O Hub IoT dá suporte à gravação de dados no Armazenamento do Azure no formato Apache Avro e no formato 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 mensagens. Ambos os valores não diferenciam maiúsculas de minúsculas. Se a codificação de conteúdo não estiver definida, o Hub IoT gravará as mensagens no formato codificado base 64.
O formato de codificação pode ser definido somente quando o ponto de extremidade de armazenamento de blob está configurado; ele não pode ser editado para um ponto de extremidade existente.
O Hub IoT envia mensagens em lote e grava dados no armazenamento sempre que o lote atinge um determinado tamanho ou um determinado período de tempo. O Hub IoT usa como padrão a seguinte convenção de nomenclatura de arquivos: {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}. Você pode usar qualquer convenção de nomenclatura de arquivo, mas deve usar todos os tokens listados. O Hub IoT grava em um blob vazio se não houver dados para gravar.
Recomendamos listar os blobs ou arquivos e, em seguida, iterar sobre eles, para garantir que todos os blobs ou arquivos sejam lidos sem fazer suposições de partição. O intervalo de partições pode ser alterado durante um failover iniciado pela Microsoft ou um failover manual do Hub IoT. Você pode usar a API List Blobs para enumerar a lista de blobs ou List ADLS Gen2 API 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 tópicos do Barramento de Serviço usados como pontos de extremidade do Hub IoT não devem ter Sessões ou Deteção de Duplicados 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 final de encaminhamento
Além do ponto de extremidade compatível com Hubs de Eventos integrados, você também pode rotear 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 a partir do Hub IoT. O Hub IoT suporta a gravação no Cosmos DB em JSON (se especificado no tipo de conteúdo da mensagem) ou como binário codificado na base 64.
Para oferecer 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 de 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, pode-se esperar que sua partição lógica se aproxime de seu limite máximo de 20 GB dentro de um mês. Nesse caso, você pode definir uma chave de partição sintética como uma combinação do 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 todos os meses para cada dispositivo.
Atenção
Se você estiver usando a identidade gerenciada atribuída ao sistema para autenticação no Cosmos DB, 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. A atribuição de função para o Cosmos DB não é suportada atualmente no portal do Azure. Para obter mais informações sobre as várias funções, consulte Configurar acesso baseado em função para o Azure Cosmos DB. Para entender a atribuição de funções por meio da CLI, consulte Gerenciar recursos de função SQL do Azure Cosmos DB.
Estado de Funcionamento do Ponto Final
Você pode usar a API REST Get Endpoint Health para obter o status de integridade dos endpoints. Recomendamos o uso das métricas de roteamento do Hub IoT relacionadas à latência de mensagens de roteamento para identificar e depurar erros quando a integridade do endpoint estiver morta ou não íntegra, pois esperamos que a latência seja maior quando o endpoint estiver em um desses estados. Para saber mais sobre como usar métricas do Hub IoT, consulte Monitorar o Hub IoT.
| Estado de Funcionamento | Description |
|---|---|
| saudável | O ponto de extremidade está aceitando mensagens conforme o esperado. |
| insalubridade | O ponto de extremidade não está aceitando mensagens e o Hub IoT está tentando novamente enviar mensagens para esse ponto de extremidade. |
| desconhecido | 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. |
| mortos | O Hub IoT não está mais entregando mensagens para esse ponto de extremidade. Falha ao tentar enviar mensagens para este ponto de extremidade. |
Próximos passos
Saiba mais sobre estes tópicos: