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

  • Artigo

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 de saída para os Hubs de Eventos.

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

Instalar a extensão

O pacote NuGet da extensão instalado depende do modo C# usado no aplicativo de funções:

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

A funcionalidade da extensão varia de acordo com a versão da extensão:

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções 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 dos 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 se for preciso alterar a versão das associações ou se os pacotes ainda não estiverem instalados. Para saber mais, confira pacotes de extensão.

Essa versão apresenta a capacidade de se conectar usando uma identidade em vez de um segredo. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções 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 arquivo host.json:

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

Para saber mais, confira Atualizar suas extensões.

Tipos de associação

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

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

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

O processo de trabalho isolado dá suporte a tipos de parâmetro de acordo com a tabela abaixo. O suporte à associação a tipos do Azure.Messaging.EventHubs está em versão prévia.

Gatilho de Hubs de Eventos

Quando você quiser que a função processe um único evento, o gatilho dos Hubs de Eventos pode ser associado aos seguintes tipos:

Type Descrição
string O evento como uma cadeia de caracteres. Use quando a mensagem for de 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 básico (POCO).
Azure.Messaging.EventHubs.EventData1 O objeto de evento.
Se você estiver migrando de versões mais antigas dos SDKs dos Hubs de Eventos, observe que essa versão descarta o suporte para o tipo herdado Body em favor do EventBody.

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

Type Descrição
string[] Uma matriz de eventos do lote, como cadeias de caracteres. Cada entrada representa um evento.
EventData[]1 Uma matriz de eventos do lote, como instâncias do Azure.Messaging.EventHubs.EventData. Cada entrada representa um evento.
T[] em que T é um tipo serializável por JSON 1 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 consultar asMicrosoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 ou posterior e as dependências comuns para vinculações de dados do tipo SDK.

Associação de saída dos Hubs de Eventos

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

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

Quando você quiser que a função escreva vários eventos, a associação de saída dos Hubs de Eventos pode ser associada aos seguintes tipos:

Type Descrição
T[] em que 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 tipos diretamente do Microsoft.Azure.EventHubs.

configurações de host.json

O arquivo host.json contém configurações que controlam o comportamento de gatilho dos 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 Padrã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 se aplica somente quando a função estiver recebendo vários eventos e deve ser menor que maxEventBatchSize.
O tamanho mínimo não é estritamente garantido. Um lote parcial é expedido quando um lote completo não pode ser preparado antes que maxWaitTime tenha decorrido. Lotes parciais também são prováveis para a primeira invocação da função após a colocação em escala ocorrer.
maxWaitTime1 00:01:00 O intervalo máximo que o gatilho deve aguardar para preencher um lote antes de invocar a função. O tempo de espera só é considerado quando minEventBatchSize é maior que 1. Caso contrário, ele é ignorado. Se menos de minEventBatchSize eventos estiverem disponíveis antes do tempo de espera passar, a função será invocada com um lote parcial. O tempo de espera mais longo permitido é de 10 minutos.

OBSERVAÇÃO: esse intervalo não é uma garantia estrita para o tempo exato no qual a função é invocada. Há uma pequena margem de erro devido à precisão do temporizador. Quando a colocação em escala ocorre, a primeira invocação com um lote parcial pode ocorrer mais rapidamente ou pode levar até o dobro do tempo de espera configurado.
batchCheckpointFrequency 1 O número de lotes a serem processados antes de criar um ponto de verificação para o hub de eventos.
prefetchCount 300 O número de eventos que serão solicitados antecipadamente dos Hubs de Eventos e mantidos em um cache local para permitir que as leituras evitem aguardar em uma operação de rede
transportType amqpTcp O protocolo e o transporte usados para comunicação com os Hubs de Eventos. Opções disponíveis: amqpTcp, amqpWebSockets
webProxy null O proxy a ser usado para se comunicar com os Hubs de Eventos por soquetes da Web. Um proxy não pode ser usado com o transporte amqpTcp.
customEndpointAddress null O endereço a ser usado ao estabelecer uma conexão com os 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 de 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 em colocação em escala baseada em destino para substituir o limite de colocação em escala padrão inferido da opção maxEventBatchSize. Quando definido, 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 fromStart 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 do OffsetType. Opções disponíveis: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Especifica o tempo de enfileiramento do evento no fluxo do qual iniciar o processamento. Quando initialOffsetOptions/type é configurado como fromEnqueuedTime, essa configuração é obrigatória. Compatível com hora em qualquer formato com suporte do 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 do computador que está executando o aplicativo de funções, que é o UTC quando executado no Azure.
clientRetryOptions/mode exponential A abordagem a ser usada para calcular atrasos de repetição. O modo exponencial fará novas tentativas com um atraso baseado em uma estratégia de retirada, na qual cada tentativa aumentará a duração que ela aguarda antes de tentar novamente. O modo fixo faz novas tentativas 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 dos Hubs de Eventos, por tentativa.
clientRetryOptions/delay 00:00:00.80 O fator de atraso ou de retirada a ser aplicado entre as tentativas de repetição.
clientRetryOptions/maximumDelay 00:00:01 O atraso máximo 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 Usar minEventBatchSize e maxWaitTime requer a v5.3.0 do pacote Microsoft.Azure.WebJobs.Extensions.EventHubs 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, era 10.

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

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

Próximas etapas