Partilhar via

Gatilho e associações de Hubs de Eventos do Azure para o Azure Functions

Este artigo explica como trabalhar com associações de Hubs de Eventos do Azure para o Azure Functions. O Azure Functions dá suporte a associações de gatilho e saída para Hubs de Eventos.

Ação Tipo
Responda a eventos enviados para um fluxo de eventos do hub de eventos. Acionador
Gravar eventos em um fluxo de eventos Vinculação de saída

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.

Esta versão suporta a configuração de gatilhos e ligações através da integração do .NET Aspire .

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

Instalar pacote

Para poder usar essa extensão de associação em seu aplicativo, certifique-se de que o arquivo dehost.json na raiz do seu projeto contém esta extensionBundle referência:

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

Neste exemplo, o version valor de instrui o host Functions a usar uma versão de [4.0.0, 5.0.0) pacote que seja pelo menos 4.0.0 , mas menor que 5.0.0, que inclui todas as versões potenciais do 4.x. Essa notação mantém efetivamente seu aplicativo na versão secundária mais recente disponível do pacote de extensão v4.x.

Quando possível, você deve usar a versão principal mais recente do pacote de extensão e permitir que o tempo de execução mantenha automaticamente a versão secundária mais recente. Você pode visualizar o conteúdo do pacote mais recente na página de lançamento dos pacotes de extensão. Para obter mais informações, consulte Pacotes de extensão do Azure Functions.

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 uma das seguintes opções:

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 de [Azure.Messaging.EventHubs] está em pré-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 Descrição
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 Descrição
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 Descrição
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 Descrição
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.

Tipos de vinculação SDK

Os Tipos de SDK para o Azure EventHub estão em Pré-visualização. Siga o exemplo Python SDK Bindings for EventHub para começar a usar os tipos de SDK para Hubs de Eventos em Python.

Importante

Usar associações de tipo SDK requer o modelo de programação Python v2.

Vinculativo Tipos de parâmetros Exemplos
Gatilho do EventHub Dados de Evento EventData

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
            }
        }
    }
}
Propriedade Predefinição Descrição
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. Existe uma pequena margem 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 null 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 null 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 null 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 é arredondada para um número que cria uma distribuição de partição balanceada.
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 null 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