Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
O Hub IoT do Azure expõe vários endpoints para suportar os 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 e o tamanho certos do Hub IoT para sua solução.
Nomes do Hub IoT
Pode encontrar o nome de host de um hub IoT no portal Azure, no painel de Visão Geral do seu 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
endpoints com TLS 1.3 ativado
O Hub IoT do Azure fornece endpoints adicionais para suportar o TLS 1.3 com requisitos de segurança reforçados. Para hubs com o perfil de ligação clássico, estes endpoints estão disponíveis juntamente com o endpoint existente para permitir uma adoção gradual e sem interrupções.
Não está prevista qualquer alteração ao endpoint existente do Hub IoT (<hub>.azure-devices.net), comumente referido como o endpoint clássico. Este endpoint mantém-se totalmente suportado, incluindo para cenários de Private Link, e continua a ser o padrão para cargas de trabalho existentes.
Os novos endpoints são aditivos, não substitutos, e permitem aos clientes adotar configurações de segurança mais robustas ao seu próprio ritmo.
Tipos de terminais
| Tipo de ponto final | Hostname | Suporte de protocolo |
|---|---|---|
| Classic | <hub>.azure-devices.net |
TLS 1.2 (comportamento existente) |
| Ponto de extremidade do dispositivo | <hub>.device.azure-devices.net |
TLS 1.2 (restrito) + TLS 1.3 |
| Ponto final de serviço | <hub>.service.azure-devices.net |
TLS 1.2 (restrito) + TLS 1.3 |
Perfis de ligação e seleção do endpoint
Um perfil de ligação descreve a configuração de conectividade do hub. Um endpoint é o nome de host ao qual um dispositivo ou aplicação de serviço se liga. Alterar o nome de host não altera o perfil de ligação nem ativa o MQTT v5.
- Perfil de ligação clássico: O endpoint clássico e os endpoints de dispositivo e serviço compatíveis com TLS 1.3 estão geralmente disponíveis. Um perfil de ligação clássico não está limitado ao endpoint clássico.
- Perfil de ligação MQTT v5: Os endpoints de dispositivo e serviço compatíveis com TLS 1.3 estão em pré-visualização. As mensagens de dispositivos utilizam MQTT v5, não MQTT v3.1.1, AMQP ou HTTPS. A disponibilidade do TLS 1.3 para hubs de perfil clássico não altera o estado da pré-visualização do MQTT v5.
Utilize o endpoint de dispositivo atribuído para ligações de dispositivo e o endpoint de serviço para aplicações backend. Para um dispositivo provisionado, utilize o endpoint retornado pelo Serviço de Provisionamento de Dispositivos (DPS), em vez de construir um nome de host.
Ao obter uma cadeia de ligação de serviço com a CLI de pré-visualização, selecione --hostname-type service; uma cadeia de ligação de serviço não é uma credencial de onboarding de dispositivo.
As ligações de dispositivo MQTT v5 requerem autenticação X.509. Para credenciais de integração, emissão e renovação de certificados através do DPS, e resolução de problemas do dispositivo, consulte Configurar um dispositivo.
Principais considerações
- As aplicações e dispositivos existentes que usam o endpoint clássico continuam a funcionar sem quaisquer alterações.
- Os novos endpoints suportam TLS 1.3 e requisitos de segurança reforçados.
- Ambos os modelos de endpoint coexistem para suportar migrações graduais sem interrupções do serviço.
- Compatível com TLS 1.3 não significa que TLS 1.3 seja necessário para todas as ligações. O cliente e o endpoint negociam uma versão TLS e um conjunto de cifras que ambos suportam. As versões TLS e as versões do protocolo de mensagens do dispositivo são independentes.
- Os endpoints de dispositivos e serviços requerem Indicação de Nome de Servidor (SNI). Para detalhes sobre suites de cifras e protocolos, consulte o suporte Hub IoT TLS.
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:
Nota
Os protocolos do dispositivo e as operações de mensagens listados nesta secção descrevem o perfil de ligação clássico. Para o suporte e limitações do MQTT v5, consulte as capacidades do MQTT v5.
Fornecedor 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.
Gestão de identidade de dispositivos: um conjunto de endpoints HTTPS REST para gerir identidades de dispositivos (criar, recuperar, atualizar e eliminar). As identidades de dispositivos são usadas para autenticação e controlo de acesso.
Gestão de dispositivos gémeos: um conjunto de endpoints HTTPS REST orientados para o serviço para consultar e atualizar gémeos de dispositivos (atualizar tags e propriedades).
Gestão de jobs: um conjunto de endpoints HTTPS REST voltados para serviços para consultar e gerir jobs.
Endpoints de dispositivos: um conjunto de endpoints para cada dispositivo no registo de identidade. Exceto onde indicado, 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)
Endpoints de serviço: um conjunto de endpoints para o backend da sua solução comunicar com os seus dispositivos. Com uma exceção, esses endpoints são expostos apenas através dos protocolos AMQP e AMQP sobre WebSockets. O ponto de extremidade de invocação direta do método é exposto através do protocolo HTTPS.
Receber mensagens do dispositivo para a nuvem: este ponto de extremidade é o ponto de extremidade incorporado discutido nos conceitos de roteamento de mensagens. Um serviço back-end pode usá-lo para ler as mensagens enviadas pelos seus dispositivos para a nuvem. 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 sobre os SDKs do Hub IoT do Azure descreve as várias formas de aceder a esses pontos de extremidade.
Todos os endpoints Hub IoT utilizam o protocolo TLS , e nenhum endpoint é alguma vez exposto em canais não encriptados ou não seguros.
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 conseguem escrever diretamente nos endpoints. 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
- Microsoft Fabric Eventstreams
Para obter os limites de pontos de extremidade por hub, consulte Cotas e limitação de velocidade.
Ponto de extremidade integrado
O endpoint incorporado e o encaminhamento de fallback não estão disponíveis para o perfil de ligação MQTT v5. Configure uma rota explícita para um destino suportado; consulte Diferenças de perfil de ligação de roteamento.
Você pode usar a integração padrão de Hubs de Eventos e SDKs para receber mensagens de dispositivo para nuvem do ponto de extremidade interno (mensagens/eventos). Assim que crias qualquer rota, os dados deixam de fluir para o endpoint incorporado, a menos que seja criada uma rota para esse endpoint. Mesmo que não crie nenhuma rota, deve ativar uma rota de reserva para encaminhar mensagens para o endpoint incorporado. O recurso alternativo está ativado por defeito se criar o seu hub usando o portal ou a CLI.
A carga útil da mensagem não está codificada em base64 no endpoint incorporado.
Armazenamento do Azure como um endpoint de encaminhamento
O Hub IoT pode encaminhar mensagens para dois serviços de armazenamento: Armazenamento de Blobs do Azure e Azure Data Lake Storage Gen2 (ADLS Gen2). Ambos estes serviços utilizam blobs para armazenamento. Para usar o Azure Data Lake Gen2, sua conta de armazenamento deve ter namespaces hierárquicos habilitados. Para mais informações, veja 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 formato padrão é Avro. Para usar codificação JSON, defina a contentType propriedade para application/json e a contentEncoding propriedade para UTF-8 nas propriedades do sistema de mensagens. Ambos os valores não têm sensibilidade a maiúsculas e minúsculas.
Se não definir as propriedades necessárias do sistema, o Hub IoT aplica codificação base64. Para evitar a codificação base64, defina tanto a contentType propriedade para application/json como a contentEncoding propriedade para UTF-8 nas propriedades do sistema de mensagens. Se estas propriedades não estiverem definidas, o Hub IoT escreve as mensagens em formato codificado base64.
Só podes definir o formato de codificação quando configurares o endpoint de armazenamento de blobs. Não podes editar o formato de codificação para um endpoint 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.
Para garantir que todos os blobs ou ficheiros são lidos sem fazer suposições sobre partições, liste os blobs ou ficheiros e depois itere sobre eles. 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 listar blobs ou a API List ADLS Gen2 para listar 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 Service Bus que utiliza como endpoints do Hub IoT não devem ter Sessões ou Deteção de Duplicação ativadas. Se ativares qualquer uma dessas opções, o endpoint aparece como Inalcançável no portal Azure.
A codificação Base64 nunca acontece ao encaminhar para filas ou tópicos do Service Bus. As mensagens são escritas de forma direta para o endpoint.
Hubs de Eventos como um ponto final de encaminhamento
Para além do endpoint compatível com Event Hubs incorporado, também pode encaminhar dados para endpoints personalizados do tipo Event Hubs.
A codificação Base64 nunca acontece quando se encaminha para endpoints personalizados de Event Hubs. As mensagens são escritas de forma direta para o endpoint.
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 escrita para o Cosmos DB em JSON (se especificado no tipo de conteúdo da mensagem) ou como binário codificado base64.
A codificação Base64 é aplicada se as propriedades necessárias do sistema não estiverem definidas. Para escrever em JSON, defina a contentType propriedade para application/json e a contentEncoding propriedade para UTF-8 nas propriedades do sistema de mensagens. Se estas propriedades não estiverem definidas, os dados são codificados em base64 quando escritos no Cosmos DB.
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.
Microsoft Fabric Eventstreams como endpoint de roteamento
Pode encaminhar mensagens de dispositivo para nuvem para um eventstream Microsoft Fabric adicionando um endpoint personalizado Fabric Eventstream ao seu IoT Hub. Esta integração traz a telemetria do Hub IoT diretamente para Fabric Real-Time Intelligence para processamento e análise a jusante.
Nota
O endpoint de roteamento do Microsoft Fabric Eventstream está disponível para todos. Suporta os perfis de ligação clássico e MQTT v5. O próprio perfil MQTT v5 permanece em pré-visualização; a disponibilidade do endpoint não altera esse estado.
Para encaminhar mensagens para um eventstream Fabric, crie uma rota no Hub IoT, adicione um endpoint Fabric Eventstream e ligue-o a um eventstream Fabric que utilize um endpoint personalizado (código de aplicação personalizado).
No seu espaço de trabalho Microsoft Fabric, selecione o bloco de origem do endpoint personalizado ao qual quer ligar-se no seu Eventstream publicado. Se não existir um tile de origem de endpoint personalizado no seu Eventstream, crie um novo tile de origem de endpoint personalizado. Depois de selecionado o bloco de origem, vá ao painel de Detalhes . Selecione o Event Hub como protocolo. Selecione Entra ID Authentication e aceda aos detalhes da ligação. Para garantir que a Autenticação Entra ID está corretamente configurada para o seu espaço de trabalho Fabric, consulte Conectar ao Eventstream usando autenticação Microsoft Entra ID.
Authentication
O endpoint Fabric Eventstream suporta apenas autenticação com o Microsoft Entra ID. A autenticação por chave de assinatura de acesso partilhada (SAS) não é suportada. Pode usar uma identidade gerida atribuída pelo sistema ou pelo utilizador para o IoT Hub. Para obter mais informações, consulte Conectividade de saída do Hub IoT para outros recursos do Azure.
Esquema de mensagem
As mensagens encaminhadas para um ponto final do Fabric Eventstream são entregues através do modo de conteúdo binário do CloudEvents 1.0 sobre AMQP, que difere do esquema usado por outros pontos finais de encaminhamento, como o Event Hubs. A identidade do dispositivo e os metadados do evento são preservados no envelope CloudEvents. Para os hubs IoT que utilizam o Azure Device Registry (ADR), a carga útil do evento inclui identificadores ADR. Para uma comparação com o esquema predefinido de mensagens encaminhadas, consulte esquema de mensagens nos pontos finais de encaminhamento.
Após esta alteração, os campos de metadados do utilizador continuam presentes na mensagem, mas não aparecerão a menos que seja adicionada uma transformação SQL antes de os dados serem entregues ao destino no fluxo de eventos Fabric.
SELECT ,
GETMETADATAPROPERTYVALUE(
[<Add name of stream input>],
'[User]'
) AS UserProperties
INTO [<Add name of stream output>]
FROM [<Add name of stream input>];
O estado de disponibilidade geral do endpoint é independente das definições de referência de esquema e de formato da carga útil da mensagem em pré-visualização. Para os seus papéis distintos e a validação do consumidor, consulte Preparar telemetria para agentes e análise.
Restrições de propriedades de enriquecimento
Os nomes das propriedades de enriquecimento de mensagens para os endpoints do Fabric Eventstream têm as seguintes restrições:
- Os nomes devem começar por uma letra minúscula.
- Os nomes podem conter apenas letras minúsculas e dígitos.
- Hífens, carateres de sublinhado, pontos e camelCase não são permitidos.
- Os nomes podem ter no máximo 20 caracteres.
Tooling
Pode criar e configurar um endpoint de Eventstream do Fabric ao utilizar o CLI do Azure e o Bicep.
Nota
Começar com Fabric? Aproveite o Azure IoT Solution Accelerator Workload for Microsoft Fabric Real-Time Intelligence para um início rápido sobre como os dados Azure IoT dispositivos podem ser transformados em análises em tempo real, monitorização operacional, ações automatizadas e insights baseados em IA através da Fabric Real-Time Intelligence.
Saúde do Endpoint
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 com a latência de mensagens para identificar e depurar erros quando o endpoint estiver inativo ou com problemas de integridade, 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 Saúde | Descrição |
|---|---|
| bom estado de funcionamento | O terminal está a aceitar mensagens conforme esperado. |
| mau estado de funcionamento | 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á a recuperar-se de um estado de falha. |
| mortos | O Hub IoT já não está a entregar mensagens a este ponto de ligação. Falhas ao tentar novamente enviar mensagens para este endpoint. |
Próximos passos
Saiba mais sobre estes tópicos: