Associações do Hub IoT do Azure para o Azure Functions

  • Artigo

Este conjunto de artigos explica como trabalhar com associações do Azure Functions para o Hub IoT. O suporte ao Hub IoT é baseado na Vinculação de Hubs de Eventos do Azure.

Importante

Embora os exemplos de código a seguir usem a API do Hub de Eventos, a sintaxe fornecida é aplicável para funções do Hub IoT.

Ação Type
Responda a eventos enviados para um fluxo de eventos do hub IoT. Acionador

Instalar a extensão

O pacote de extensão NuGet que você instala depende do modo C# que você está usando em seu aplicativo de função:

As funções são executadas em um processo de trabalho C# isolado. Para saber mais, consulte Guia para executar o C# Azure Functions em um processo de trabalho isolado.

A funcionalidade da extensão varia dependendo da versão da extensão:

Esta versão introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Adicione a extensão ao seu projeto instalando o pacote NuGet, versão 5.x.

Instalar pacote

A extensão Hubs de Eventos faz parte de um pacote de extensão, que é especificado no arquivo de projeto host.json. Talvez seja necessário modificar esse pacote para alterar a versão da associação ou se os pacotes ainda não estiverem instalados. Para saber mais, consulte Pacote de extensão.

Esta versão introduz a capacidade de se conectar usando uma identidade em vez de um segredo. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Você pode adicionar esta versão da extensão do pacote de extensão v3 adicionando ou substituindo o seguinte código em seu host.json arquivo:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Para saber mais, consulte Atualizar suas extensões.

Tipos de vinculação

Os tipos de associação suportados para .NET dependem da versão da extensão e do modo de execução C#, que pode ser um dos seguintes:

Uma biblioteca de classes de processo de trabalho isolada compilada função C# é executada em um processo isolado do tempo de execução.

Escolha uma versão para ver os detalhes do tipo de vinculação para o modo e a versão.

O processo de trabalho isolado suporta tipos de parâmetros de acordo com as tabelas abaixo. O suporte para associação a tipos do Azure.Messaging.EventHubs está em visualização.

Os Hubs de Eventos disparam

Quando você deseja que a função processe um único evento, o gatilho de Hubs de Eventos pode se vincular aos seguintes tipos:

Tipo Description
string O evento como uma cadeia de caracteres. Use quando o evento for texto simples.
byte[] Os bytes do evento.
Tipos serializáveis JSON Quando um evento contém dados JSON, o Functions tenta desserializar os dados JSON em um tipo de objeto CLR (POCO) simples.
Azure.Messaging.EventHubs.EventData1 O objeto do evento.
Se você estiver migrando de versões mais antigas dos SDKs de Hubs de Eventos, observe que essa versão descarta o suporte para o tipo herdado Body em favor de EventBody.

Quando você deseja que a função processe um lote de eventos, o gatilho Hubs de Eventos pode se vincular aos seguintes tipos:

Tipo Description
string[] Uma matriz de eventos do lote, como strings. Cada entrada representa um evento.
EventData[]1º Uma matriz de eventos do lote, como instâncias de Azure.Messaging.EventHubs.EventData. Cada entrada representa um evento.
T[] onde T é um JSON serializável tipo1 Uma matriz de eventos do lote, como instâncias de um tipo POCO personalizado. Cada entrada representa um evento.

1 Para usar esses tipos, você precisa fazer referência a Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 ou posterior e às dependências comuns para associações de tipo SDK.

Vinculação de saída de Hubs de Eventos

Quando você deseja que a função escreva um único evento, a associação de saída dos Hubs de Eventos pode ser vinculada aos seguintes tipos:

Tipo Description
string O evento como uma cadeia de caracteres. Use quando o evento for texto simples.
byte[] Os bytes do evento.
Tipos serializáveis JSON Um objeto que representa o evento. Functions tenta serializar um tipo de objeto CLR (POCO) simples em dados JSON.

Quando você deseja que a função escreva vários eventos, a ligação de saída dos Hubs de Eventos pode se vincular aos seguintes tipos:

Tipo Description
T[] onde T é um dos tipos de evento único Uma matriz que contém vários eventos. Cada entrada representa um evento.

Para outros cenários de saída, crie e use um EventHubProducerClient com outros tipos do Azure.Messaging.EventHubs diretamente. Consulte Registrar clientes do Azure para obter um exemplo de como usar a injeção de dependência para criar um tipo de cliente a partir do SDK do Azure.

host.json configurações

O arquivo host.json contém configurações que controlam o comportamento do gatilho de Hubs de Eventos. A configuração é diferente dependendo da versão da extensão.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Property Predefinição Description
maxEventBatchSize2 100 O número máximo de eventos incluídos em um lote para uma única invocação. Deve ser pelo menos 1.
minEventBatchSize1 1 O número mínimo de eventos desejados em um lote. O mínimo aplica-se apenas quando a função está a receber vários eventos e deve ser inferior a maxEventBatchSize.
O tamanho mínimo não é estritamente garantido. Um lote parcial é enviado quando um lote completo não pode ser preparado antes de ter decorrido maxWaitTime . Lotes parciais também são prováveis para a primeira invocação da função após o dimensionamento.
maxWaitTime1 00:01:00 O intervalo máximo que o gatilho deve esperar para preencher um lote antes de invocar a função. O tempo de espera só é considerado quando minEventBatchSize é maior que 1 e é ignorado. Se menos do que minEventBatchSize os eventos estavam disponíveis antes do tempo de espera decorrer, a função é invocada com um lote parcial. O tempo de espera mais longo permitido é de 10 minutos.

NOTA: Este intervalo não é uma garantia estrita para o momento exato em que a função é invocada. Há um pequeno magin de erro devido à precisão do temporizador. Quando o dimensionamento ocorre, a primeira chamada com um lote parcial pode ocorrer mais rapidamente ou pode levar até o dobro do tempo de espera configurado.
batchCheckpointFrequência 1 O número de lotes a serem processados antes de criar um ponto de verificação para o hub de eventos.
pré-fetchCount 300 O número de eventos que é solicitado ansiosamente dos Hubs de Eventos e mantido em um cache local para permitir leituras para evitar a espera em uma operação de rede
Tipo de transporte amqpTcp O protocolo e o transporte usados para comunicação com Hubs de Eventos. Opções disponíveis: amqpTcp, amqpWebSockets
Proxy web nulo O proxy a ser usado para comunicação com Hubs de Eventos por meio de soquetes da Web. Um proxy não pode ser usado com o amqpTcp transporte.
customEndpointAddress nulo O endereço a ser usado ao estabelecer uma conexão com Hubs de Eventos, permitindo que as solicitações de rede sejam roteadas por meio de um gateway de aplicativo ou outro caminho necessário para o ambiente host. O namespace totalmente qualificado para o hub de eventos ainda é necessário quando um endereço de ponto de extremidade personalizado é usado e deve ser especificado explicitamente ou por meio da cadeia de conexão.
targetUnprocessedEventThreshold1 nulo O número desejado de eventos não processados por instância de função. O limite é usado no dimensionamento baseado no destino para substituir o limite de dimensionamento padrão inferido da maxEventBatchSize opção. Quando definida, a contagem total de eventos não processados é dividida por esse valor para determinar o número de instâncias de função necessárias. A contagem de instâncias será arredondada para um número que cria uma distribuição de partição equilibrada.
initialOffsetOptions/type deStart O local no fluxo de eventos para iniciar o processamento quando um ponto de verificação não existir no armazenamento. Aplica-se a todas as partições. Para obter mais informações, consulte a documentação OffsetType. Opções disponíveis: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc nulo Especifica o tempo enfileirado do evento no fluxo a partir do qual iniciar o processamento. Quando initialOffsetOptions/type é configurado como fromEnqueuedTime, essa configuração é obrigatória. Suporta hora em qualquer formato suportado por DateTime.Parse(), como 2020-10-26T20:31Z. Para maior clareza, você também deve especificar um fuso horário. Quando o fuso horário não é especificado, o Functions assume o fuso horário local da máquina que executa o aplicativo de função, que é UTC quando executado no Azure.
clientRetryOptions/mode exponencial A abordagem a ser usada para calcular atrasos de repetição. O modo exponencial tenta novamente com um atraso baseado em uma estratégia de back-off, onde cada tentativa aumentará a duração que espera antes de tentar novamente. O modo fixo tenta novamente em intervalos fixos, com cada atraso tendo uma duração consistente. Opções disponíveis: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 A duração máxima para aguardar a conclusão de uma operação de Hubs de Eventos, por tentativa.
clientRetryOptions/atraso 00:00:00.80 O fator de atraso ou recuo a ser aplicado entre as tentativas de repetição.
clientRetryOptions/maximumDelay 00:00:01 O atraso máximo a ser permitido entre as tentativas de repetição.
clientRetryOptions/maximumRetries 3 O número máximo de tentativas de repetição antes de considerar que a operação associada falhou.

1 Usando minEventBatchSize e maxWaitTime requer v5.3.0 do Microsoft.Azure.WebJobs.Extensions.EventHubs pacote, ou uma versão posterior.

2 O padrão maxEventBatchSize foi alterado na v6.0.0 do Microsoft.Azure.WebJobs.Extensions.EventHubs pacote. Nas versões anteriores, eram 10.

Os clientRetryOptions são usados para repetir operações entre o host de funções e Hubs de Eventos (como buscar eventos e enviar eventos). Consulte as orientações sobre o tratamento de erros e novas tentativas do Azure Functions para obter informações sobre como aplicar políticas de repetição a funções individuais.

Para obter uma referência de host.json no Azure Functions 2.x e posterior, consulte host.json referência para o Azure Functions.

Próximos passos