Biblioteca de clientes dos Hubs de Eventos do Azure WebJobs para .NET – versão 6.0.1

  • Artigo

Essa extensão fornece funcionalidade para acessar Hubs de Eventos do Azure de uma função do Azure.

Introdução

Instalar o pacote

Instale a extensão dos Hubs de Eventos com o NuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs

Pré-requisitos

  • Assinatura do Azure: Para usar os serviços do Azure, incluindo Hubs de Eventos do Azure, você precisará de uma assinatura. Se você não tiver uma conta existente do Azure, poderá se inscrever para uma avaliação gratuita ou usar seus benefícios de assinatura do Visual Studio ao criar uma conta.

  • Namespace dos Hubs de Eventos com um Hub de Eventos: Para interagir com Hubs de Eventos do Azure, você também precisará ter um namespace e um Hub de Eventos disponíveis. Se você não estiver familiarizado com a criação de recursos do Azure, convém seguir o guia passo a passo para criar um Hub de Eventos usando o portal do Azure. Lá, você também pode encontrar instruções detalhadas para usar os modelos da CLI do Azure, Azure PowerShell ou ARM (Azure Resource Manager) para criar um Hub de Eventos.

  • Conta de Armazenamento do Azure com armazenamento de blobs: Para persistir pontos de verificação como blobs no Armazenamento do Azure, você precisará ter uma conta de Armazenamento do Azure com blobs disponíveis. Se você não estiver familiarizado com contas de Armazenamento do Azure, convém seguir o guia passo a passo para criar uma conta de armazenamento usando o portal do Azure. Lá, você também pode encontrar instruções detalhadas para usar os modelos da CLI do Azure, Azure PowerShell ou ARM (Azure Resource Manager) para criar contas de armazenamento.

Botão Implantar

Autenticar o Cliente

Para que a biblioteca de clientes dos Hubs de Eventos interaja com um Hub de Eventos, ela precisará entender como se conectar e autorizar com ele. O meio mais fácil para fazer isso é usar um cadeia de conexão, que é criado automaticamente ao criar um namespace dos Hubs de Eventos. Se você não estiver familiarizado com o uso de cadeias de conexão com Os Hubs de Eventos, convém seguir o guia passo a passo para obter uma cadeia de conexão dos Hubs de Eventos.

A Connection propriedade de EventHubAttribute e EventHubTriggerAttribute é usada para especificar a propriedade de configuração que armazena o cadeia de conexão.

O AzureWebJobsStorage cadeia de conexão é usado para preservar as informações de ponto de verificação de processamento.

Para o desenvolvimento local, use o local.settings.json arquivo para armazenar o cadeia de conexão:

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>": "Endpoint=sb://<event_hubs_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8="
  }
}

Quando implantado, use as configurações do aplicativo para definir o cadeia de conexão.

Autenticação baseada em identidade

Se o ambiente tiver a identidade gerenciada habilitada, você poderá usá-la para autenticar a extensão dos Hubs de Eventos. Antes de fazer isso, você precisará garantir que as permissões tenham sido configuradas conforme descrito no guia do desenvolvedor do Azure Functions.

Para usar a autenticação baseada em identidade, forneça a <connection_name>__fullyQualifiedNamespace configuração.

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>__fullyQualifiedNamespace": "{event_hubs_namespace}.servicebus.windows.net"
  }
}

Ou, no caso do aplicativo implantado, defina a mesma configuração nas configurações do aplicativo:

<connection_name>__fullyQualifiedNamespace={event_hubs_namespace}.servicebus.windows.net

Mais detalhes sobre como configurar uma conexão baseada em identidade podem ser encontrados aqui.

Principais conceitos

Gatilho do Hub de Eventos

O Gatilho do Hub de Eventos permite que uma função seja executada quando uma mensagem é enviada para um Hub de Eventos.

Siga o tutorial Hubs de Eventos do Azure gatilho para saber mais sobre os gatilhos do Hub de Eventos.

Associação de saída do Hub de Eventos

A Associação de Saída do Hub de Eventos permite que uma função envie eventos do Hub de Eventos.

Siga a Hubs de Eventos do Azure associação de saída para saber mais sobre as associações do Hub de Eventos.

Tipos com suporte

Os seguintes tipos têm suporte para associações de gatilho e saída:

  • EventData
  • string – o valor seria codificado usando a codificação UTF8
  • BinaryData
  • byte[]
  • Os tipos de modelo personalizados serão serializados em JSON usando Newtonsoft.Json
  • IAsyncCollector<T> de qualquer um dos tipos acima para gatilhos em lote
  • EventHubProducerClient para associações de saída

Exemplos

Enviando evento individual

Você pode enviar eventos individuais para um Hub de Eventos aplicando o EventHubAttribute valor retornado da função. O valor retornado pode ser do string tipo ou EventData . Uma chave de partição pode não ser especificada ao usar um valor retornado; para fazer isso, você precisará associar ao IAsyncCollector<EventData>, conforme mostrado em Enviando vários eventos.

[FunctionName("BindingToReturnValue")]
[return: EventHub("<event_hub_name>", Connection = "<connection_name>")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
    // This value would get stored in EventHub event body.
    // The string would be UTF8 encoded
    return $"C# Timer trigger function executed at: {DateTime.Now}";
}

Enviando vários eventos

Para enviar vários eventos de uma única invocação de Função do Azure, você pode aplicar o EventHubAttribute ao IAsyncCollector<string> parâmetro ou IAsyncCollector<EventData> . As chaves de partição só podem ser usadas ao associar a IAsyncCollector<EventData>.

[FunctionName("BindingToCollector")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] IAsyncCollector<EventData> collector)
{
    // When no partition key is used, partitions will be assigned per-batch via round-robin.
    await collector.AddAsync(new EventData($"Event 1 added at: {DateTime.Now}"));
    await collector.AddAsync(new EventData($"Event 2 added at: {DateTime.Now}"));

    // Using a partition key will help group events together; events with the same key
    // will always be assigned to the same partition.
    await collector.AddAsync(new EventData($"Event 3 added at: {DateTime.Now}"), "sample-key");
    await collector.AddAsync(new EventData($"Event 4 added at: {DateTime.Now}"), "sample-key");
}

Usando a associação a modelos fortemente tipado

Para usar classes de modelo fortemente tipadas com a associação EventHub, aplique o EventHubAttribute ao parâmetro de modelo.

[FunctionName("TriggerSingleModel")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] Dog dog,
    ILogger logger)
{
    logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}

Enviando vários eventos usando EventHubProducerClient

Você também pode associar ao EventHubProducerClient diretamente para ter o maior controle sobre o envio de eventos.

[FunctionName("BindingToProducerClient")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] EventHubProducerClient eventHubProducerClient)
{
    // IAsyncCollector allows sending multiple events in a single function invocation
    await eventHubProducerClient.SendAsync(new[]
    {
        new EventData($"Event 1 added at: {DateTime.Now}"),
        new EventData($"Event 2 added at: {DateTime.Now}")
    });
}

Gatilhos por evento

Para executar uma função sempre que um evento é enviado para o Hub de Eventos, aplique o EventHubTriggerAttribute a um string parâmetro ou EventData .

[FunctionName("TriggerSingle")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] string eventBodyAsString,
    ILogger logger)
{
    logger.LogInformation($"C# function triggered to process a message: {eventBodyAsString}");
}

Gatilhos do Lote

Para executar uma função para um lote de eventos recebidos, aplique o EventHubTriggerAttribute a um string[] parâmetro ou EventData[] .

[FunctionName("TriggerBatch")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] EventData[] events,
    ILogger logger)
{
    foreach (var e in events)
    {
        logger.LogInformation($"C# function triggered to process a message: {e.EventBody}");
        logger.LogInformation($"EnqueuedTime={e.EnqueuedTime}");
    }
}

Solução de problemas

Consulte Monitorar Azure Functions para obter diretrizes de solução de problemas.

Próximas etapas

Leia a introdução ao Azure Functions ou à criação de um guia de função do Azure.

Participante

Confira nosso CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões