Associações de Hubs de Eventos do Azure para o Azure FunctionsAzure Event Hubs bindings for Azure Functions

Este artigo explica como trabalhar com associações de Hubs de Eventos do Azure para o Azure Functions.This article explains how to work with Azure Event Hubs bindings for Azure Functions. O Azure Functions dá suporte a associações de gatilho e de saída para os Hubs de Eventos.Azure Functions supports trigger and output bindings for Event Hubs.

Essas são as informações de referência para desenvolvedores do Azure Functions.This is reference information for Azure Functions developers. Se for novo no Azure Functions, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Pacotes – Functions 1.xPackages - Functions 1.x

Para a versão de funções do Azure 1. x, em que as associações de Hubs de eventos são fornecidas a Microsoft.Azure.WebJobs.ServiceBus pacote NuGet, versão 2. x.For Azure Functions version 1.x, the Event Hubs bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x. O código-fonte do pacote está no repositório GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporte emTo add support in
Funções 1.xFunctions 1.x
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - Script do C#, JavaScript, F#Local development - C# script, JavaScript, F# AutomáticoAutomatic
Desenvolvimento de portalPortal development AutomáticoAutomatic

Pacotes-funções 2. x e superiorPackages - Functions 2.x and higher

Para o Functions 2. x e superior, use o pacote Microsoft. Azure. webjobs. Extensions. EventHubs , versão 3. x.For Functions 2.x and higher, use the Microsoft.Azure.WebJobs.Extensions.EventHubs package, version 3.x. O código-fonte do pacote está no repositório GitHub azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

A tabela a seguir informa como adicionar suporte para essa associação em cada ambiente de desenvolvimento.The following table tells how to add support for this binding in each development environment.

Ambiente de desenvolvimentoDevelopment environment Para adicionar suporteTo add support
Desenvolvimento local - biblioteca de classes do C#Local development - C# class library Instalar o pacoteInstall the package
Desenvolvimento local - script do C#, JavaScript, F#, Java e PythonLocal development - C# script, JavaScript, F#, Java and Python Registrar a extensãoRegister the extension
Desenvolvimento de portalPortal development Instalar ao adicionar uma associação de saídaInstall when adding output binding

Para saber como atualizar as extensões de associação existentes no portal sem precisar republicar o projeto de aplicativo de funções, consulte Atualizar as extensões.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

GatilhoTrigger

Use o gatilho de função para responder a um evento enviado a um fluxo de eventos do hub de eventos.Use the function trigger to respond to an event sent to an event hub event stream. Você deve ter acesso de leitura ao Hub de eventos subjacente para configurar o gatilho.You must have read access to the underlying event hub to set up the trigger. Quando a função é disparada, a mensagem passada para a função é digitada como uma cadeia de caracteres.When the function is triggered, the message passed to the function is typed as a string.

Gatilho - dimensionamentoTrigger - scaling

Cada instância de uma função disparada por evento é apoiada por uma única instância de EventProcessorHost .Each instance of an event triggered function is backed by a single EventProcessorHost instance. O gatilho (da plataforma de hubs de eventos) garante que apenas uma instância EventProcessorHost possa obter uma concessão em uma determinada partição.The trigger (powered by Event Hubs) ensures that only one EventProcessorHost instance can get a lease on a given partition.

Por exemplo, considere um Hub de eventos da seguinte maneira:For example, consider an Event Hub as follows:

  • 10 partições10 partitions
  • 1.000 eventos distribuídos uniformemente em todas as partições, com 100 mensagens em cada partição1,000 events distributed evenly across all partitions, with 100 messages in each partition

Quando sua função é habilitada pela primeira vez, há apenas uma instância da função.When your function is first enabled, there is only one instance of the function. Vamos chamar a primeira instância de função Function_0.Let's call the first function instance Function_0. A função Function_0 tem uma única instância de EventProcessorHost que contém uma concessão em todas as dez partições.The Function_0 function has a single instance of EventProcessorHost that holds a lease on all ten partitions. Esta instância está lendo eventos das partições 0 a 9.This instance is reading events from partitions 0-9. Deste ponto em diante, uma destas opções ocorre:From this point forward, one of the following happens:

  • Novas instâncias de função não são necessárias: Function_0 é capaz de processar todos os eventos 1.000 antes que a lógica de dimensionamento de funções entre em vigor.New function instances are not needed: Function_0 is able to process all 1,000 events before the Functions scaling logic take effect. Nesse caso, todas as mensagens 1.000 são processadas pelo Function_0.In this case, all 1,000 messages are processed by Function_0.

  • Uma instância de função adicional é adicionada: se a lógica de dimensionamento de funções determinar que Function_0 tem mais mensagens do que pode processar, uma nova instância de aplicativo de função (Function_1) será criada.An additional function instance is added: If the Functions scaling logic determines that Function_0 has more messages than it can process, a new function app instance (Function_1) is created. Essa nova função também tem uma instância associada de EventProcessorHost.This new function also has an associated instance of EventProcessorHost. Como os hubs de eventos subjacentes detectam que uma nova instância do host está tentando ler mensagens, ele balanceia a carga das partições em suas instâncias de host.As the underlying Event Hubs detect that a new host instance is trying read messages, it load balances the partitions across the its host instances. Por exemplo, as partições de 0 a 4 podem ser atribuídas a Function_0 e as partições de 5 a 9 para Function_1.For example, partitions 0-4 may be assigned to Function_0 and partitions 5-9 to Function_1.

  • N mais instâncias de função são adicionadas: se a lógica de dimensionamento de funções determinar que tanto Function_0 quanto Function_1 têm mais mensagens do que podem ser processadas, novas instâncias de aplicativo de função Functions_N são criadas.N more function instances are added: If the Functions scaling logic determines that both Function_0 and Function_1 have more messages than they can process, new Functions_N function app instances are created. Os aplicativos são criados para o ponto em que N é maior que o número de partições do hub de eventos.Apps are created to the point where N is greater than the number of event hub partitions. Em nosso exemplo, os Hubs de Eventos balanceiam a carga das partições novamente e, nesse caso, entre as instâncias Function_0 e Functions_9.In our example, Event Hubs again load balances the partitions, in this case across the instances Function_0...Functions_9.

Quando o Functions é dimensionado, N instâncias é um número maior que o número de partições do hub de eventos.When Functions scales, N instances is a number greater than the number of event hub partitions. Isso é feito para garantir que as instâncias de EventProcessorHost estejam disponíveis para obter bloqueios em partições à medida que se tornam disponíveis de outras instâncias.This is done to ensure EventProcessorHost instances are available to obtain locks on partitions as they become available from other instances. Você é cobrado apenas pelos recursos usados quando a instância de função é executada.You are only charged for the resources used when the function instance executes. Em outras palavras, você não será cobrado por esse excesso de provisionamento.In other words, you are not charged for this over-provisioning.

Quando todas as execuções de função são concluídas (com ou sem erros), os pontos de verificação são adicionados à conta de armazenamento associada.When all function execution completes (with or without errors), checkpoints are added to the associated storage account. Quando o ponto de verificação for executado com sucesso, todas as mensagens 1.000 nunca serão recuperadas novamente.When check-pointing succeeds, all 1,000 messages are never retrieved again.

Gatilho - exemploTrigger - example

Consulte o exemplo específico a um idioma:See the language-specific example:

Gatilho - exemplo C#Trigger - C# example

O exemplo a seguir mostra uma função C# que registra o corpo da mensagem do gatilho dos hub de eventos.The following example shows a C# function that logs the message body of the event hub trigger.

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

Para obter acesso aos metadados no código da função, associe um objeto de EventData (requer o uso de uma instrução para Microsoft.Azure.EventHubs).To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.Azure.EventHubs). Você também pode acessar as mesmas propriedades usando expressões de associação na assinatura do método.You can also access the same properties by using binding expressions in the method signature. O exemplo a seguir mostra duas formas de obter os mesmos dados:The following example shows both ways to get the same data:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

Para receber eventos em um lote, faça string ou EventData uma matriz.To receive events in a batch, make string or EventData an array.

Observação

Ao receber em um lote, não é possível associar aos parâmetros do método, como no exemplo acima com DateTime enqueuedTimeUtc, e deve recebê-los de cada objeto EventDataWhen receiving in a batch you cannot bind to method parameters like in the above example with DateTime enqueuedTimeUtc and must receive these from each EventData object

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Gatilho - exemplo de script C#Trigger - C# script example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função C# script que usa a associação.The following example shows an event hub trigger binding in a function.json file and a C# script function that uses the binding. A função registra em log o corpo da mensagem do gatilho de hub de eventos.The function logs the message body of the event hub trigger.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file.

Versão 2. x e superiorVersion 2.x and higher

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versão 1.xVersion 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Aqui está o código de script do C#:Here's the C# script code:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

Para obter acesso aos metadados no código da função, associe um objeto de EventData (requer o uso de uma instrução para Microsoft.Azure.EventHubs).To get access to event metadata in function code, bind to an EventData object (requires a using statement for Microsoft.Azure.EventHubs). Você também pode acessar as mesmas propriedades usando expressões de associação na assinatura do método.You can also access the same properties by using binding expressions in the method signature. O exemplo a seguir mostra duas formas de obter os mesmos dados:The following example shows both ways to get the same data:

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public static void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

Para receber eventos em um lote, faça string ou EventData uma matriz:To receive events in a batch, make string or EventData an array:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

Gatilho - Exemplo F#Trigger - F# example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função F# que usa a associação.The following example shows an event hub trigger binding in a function.json file and an F# function that uses the binding. A função registra em log o corpo da mensagem do gatilho de hub de eventos.The function logs the message body of the event hub trigger.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file.

Versão 2. x e superiorVersion 2.x and higher

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versão 1.xVersion 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

O código F# é o seguinte:Here's the F# code:

let Run(myEventHubMessage: string, log: TraceWriter) =
    log.Log(sprintf "F# eventhub trigger function processed work item: %s" myEventHubMessage)

Gatilho - exemplo de JavaScriptTrigger - JavaScript example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função JavaScript que usa a associação.The following example shows an event hub trigger binding in a function.json file and a JavaScript function that uses the binding. A função lê os metadados de evento e registra a mensagem.The function reads event metadata and logs the message.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file.

Versão 2. x e superiorVersion 2.x and higher

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versão 1.xVersion 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Aqui está o código JavaScript:Here's the JavaScript code:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

Para receber eventos em um lote, defina cardinality para many no arquivo function.json, conforme mostrado nos exemplos a seguir.To receive events in a batch, set cardinality to many in the function.json file, as shown in the following examples.

Versão 2. x e superiorVersion 2.x and higher

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Versão 1.xVersion 1.x

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "path": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Aqui está o código JavaScript:Here's the JavaScript code:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

Gatilho – exemplo do PythonTrigger - Python example

O exemplo a seguir mostra uma ligação de acionador do Hub de Eventos em um arquivo function.json e uma função Python que usa a ligação.The following example shows an event hub trigger binding in a function.json file and a Python function that uses the binding. A função lê os metadados de evento e registra a mensagem.The function reads event metadata and logs the message.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Confira o código Python:Here's the Python code:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info('Function triggered to process a message: ', event.get_body())
    logging.info('  EnqueuedTimeUtc =', event.enqueued_time)
    logging.info('  SequenceNumber =', event.sequence_number)
    logging.info('  Offset =', event.offset)

Trigger - exemplo de JavaTrigger - Java example

O exemplo a seguir mostra uma ligação de acionador do Hub de Eventos em um arquivo function.json e uma função Java que usa a ligação.The following example shows an Event Hub trigger binding in a function.json file and an Java function that uses the binding. A função registra o corpo da mensagem do gatilho de Hub de eventos.The function logs the message body of the Event Hub trigger.

{
  "type": "eventHubTrigger",
  "name": "msg",
  "direction": "in",
  "eventHubName": "myeventhubname",
  "connection": "myEventHubReadConnectionAppSetting"
}
@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

No biblioteca de runtime de funções Java, use o EventHubTrigger anotação em parâmetros cujo valor virá do Hub de eventos.In the Java functions runtime library, use the EventHubTrigger annotation on parameters whose value would come from Event Hub. Parâmetros com essas anotações fazem com que a função seja executada quando um evento é recebido.Parameters with these annotations cause the function to run when an event arrives. Esta anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando > opcional<T.This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

Gatilho – atributosTrigger - attributes

Em bibliotecas de classes de C#, utilize o atributo EventHubTriggerAttribute.In C# class libraries, use the EventHubTriggerAttribute attribute.

O construtor do atributo usa os nomes do hub de eventos, do grupo de consumidores e de uma configuração de aplicativo que contenham a cadeia de caracteres de conexão.The attribute's constructor takes the name of the event hub, the name of the consumer group, and the name of an app setting that contains the connection string. Para obter mais informações sobre essas configurações, consulte a seção sobre configuração do gatilho.For more information about these settings, see the trigger configuration section. Este é um EventHubTriggerAttribute exemplo de atributo:Here's an EventHubTriggerAttribute attribute example:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

Para ver um exemplo completo, consulte Gatilho – exemplo de C#.For a complete example, see Trigger - C# example.

Gatilho – configuraçãoTrigger - configuration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no EventHubTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype N/Dn/a Deve ser definido como eventHubTrigger.Must be set to eventHubTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection N/Dn/a Deve ser definido como in.Must be set to in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.This property is set automatically when you create the trigger in the Azure portal.
namename N/Dn/a O nome da variável que representa o item de evento no código de função.The name of the variable that represents the event item in function code.
pathpath EventHubNameEventHubName Funciona apenas 1. x.Functions 1.x only. O nome do hub de eventos.The name of the event hub. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Functions 2. x e superior.Functions 2.x and higher. O nome do hub de eventos.The name of the event hub. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.When the event hub name is also present in the connection string, that value overrides this property at runtime.
consumerGroupconsumerGroup ConsumerGroupConsumerGroup É uma propriedade opcional que define o grupo de consumidores usado para assinar eventos no hub.An optional property that sets the consumer group used to subscribe to events in the hub. Se omitido, o grupo de consumidores $Default será usado.If omitted, the $Default consumer group is used.
cardinalidadecardinality N/Dn/a Para JavaScript.For Javascript. Definido como many para habilitar o envio em lote.Set to many in order to enable batching. Se omitido ou definido como one, uma única mensagem será passada para a função.If omitted or set to one, single message passed to function.
conexãoconnection ConexãoConnection É o nome de uma configuração de aplicativo que contém a cadeia de conexão para o namespace do hub de eventos.The name of an app setting that contains the connection string to the event hub's namespace. Copie essa cadeia de conexão clicando no botão Informações de Conexão do namespace, não no próprio hub de eventos.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Essa cadeia de conexão deve ter, pelo menos, permissões de leitura para ativar o gatilho.This connection string must have at least read permissions to activate the trigger.
pathpath EventHubNameEventHubName O nome do hub de eventos.The name of the event hub. Pode ser referenciado por meio das configurações de aplicativo %eventHubName%Can be referenced via app settings %eventHubName%

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Gatilho: metadados de eventoTrigger - event metadata

O gatilho dos Hubs de Evento fornece várias propriedades de metadados.The Event Hubs trigger provides several metadata properties. Essas propriedades podem ser usadas como parte de expressões de associação em outras associações ou como parâmetros em seu código.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Essas são propriedades da classe EventData.These are properties of the EventData class.

PropriedadeProperty TypeType DescriçãoDescription
PartitionContext PartitionContextPartitionContext A instância PartitionContext.The PartitionContext instance.
EnqueuedTimeUtc DateTime O tempo de enfileiramento no UTC.The enqueued time in UTC.
Offset string O deslocamento dos dados em relação ao fluxo de partição do Hub de Eventos.The offset of the data relative to the Event Hub partition stream. O deslocamento é um marcador ou um identificador para um evento dentro do fluxo do Hubs de Eventos.The offset is a marker or identifier for an event within the Event Hubs stream. O identificador é exclusivo dentro de uma partição do fluxo de Hubs de Eventos.The identifier is unique within a partition of the Event Hubs stream.
PartitionKey string A partição para os dados de evento deve ser enviada.The partition to which event data should be sent.
Properties IDictionary<String,Object> Propriedades do usuário dos dados do evento.The user properties of the event data.
SequenceNumber Int64 O número de sequência lógica do evento.The logical sequence number of the event.
SystemProperties IDictionary<String,Object> Propriedades do sistema, incluindo dos dados do evento.The system properties, including the event data.

Consulte exemplos de código que usam essas propriedades neste artigo.See code examples that use these properties earlier in this article.

Gatilho - propriedades de host.jsonTrigger - host.json properties

O arquivo host.json contém configurações que controlam o comportamento de gatilho dos Hubs de Eventos.The host.json file contains settings that control Event Hubs trigger behavior.

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
PropriedadeProperty PadrãoDefault DESCRIÇÃODescription
maxBatchSizemaxBatchSize 6464 A contagem máxima de eventos recebidos por loop de recebimento.The maximum event count received per receive loop.
prefetchCountprefetchCount n/dn/a O PrefetchCount padrão que será usado pelo EventProcessorHost subjacente.The default PrefetchCount that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 O número de lotes de eventos para processar antes de criar um ponto de verificação do cursor do EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

SaídaOutput

Use a associação de saída dos Hubs de Eventos para gravar eventos em um fluxo de eventos.Use the Event Hubs output binding to write events to an event stream. É necessário ter permissão de envio para um hub de eventos a fim de gravar eventos nele.You must have send permission to an event hub to write events to it.

Verifique se as referências de pacote necessárias estão em vigor antes de tentar implementar uma associação de saída.Make sure the required package references are in place before you try to implement an ouput binding.

Saída - exemploOutput - example

Consulte o exemplo específico a um idioma:See the language-specific example:

Saída - exemplo C#Output - C# example

O exemplo a seguir mostra uma função C# que grava uma mensagem em um hub de eventos, usando o valor retornado do método como a saída:The following example shows a C# function that writes a message to an event hub, using the method return value as the output:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

O exemplo a seguir mostra como usar a interface IAsyncCollector para enviar um lote de mensagens.The following sample shows how to use the IAsyncCollector interface to send a batch of messages. Esse cenário é comum quando você está processando mensagens provenientes de um hub de eventos e enviando o resultado para outro hub de eventos.This scenario is common when you are processing messages coming from one Event Hub and sending the result to another Event Hub.

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<string> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // do some processing:
        var myProcessedEvent = DoSomething(eventData);

        // then send the message
        await outputEvents.AddAsync(JsonConvert.SerializeObject(myProcessedEvent));
    }
}

Saída - exemplo de script C#Output - C# script example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função C# script que usa a associação.The following example shows an event hub trigger binding in a function.json file and a C# script function that uses the binding. A função grava uma mensagem em um hub de eventos.The function writes a message to an event hub.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file. O primeiro exemplo é para o Functions 2. x e superior, e o segundo é para o Functions 1. x.The first example is for Functions 2.x and higher, and the second one is for Functions 1.x.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}
{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "path": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Este é o código C# script que cria uma mensagem:Here's C# script code that creates one message:

using System;
using Microsoft.Extensions.Logging;

public static void Run(TimerInfo myTimer, out string outputEventHubMessage, ILogger log)
{
    String msg = $"TimerTriggerCSharp1 executed at: {DateTime.Now}";
    log.LogInformation(msg);   
    outputEventHubMessage = msg;
}

Este é o código de script C# que cria várias mensagens:Here's C# script code that creates multiple messages:

public static void Run(TimerInfo myTimer, ICollector<string> outputEventHubMessage, ILogger log)
{
    string message = $"Message created at: {DateTime.Now}";
    log.LogInformation(message);
    outputEventHubMessage.Add("1 " + message);
    outputEventHubMessage.Add("2 " + message);
}

Saída - Exemplo #FOutput - F# example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função F# que usa a associação.The following example shows an event hub trigger binding in a function.json file and an F# function that uses the binding. A função grava uma mensagem em um hub de eventos.The function writes a message to an event hub.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file. O primeiro exemplo é para o Functions 2. x e superior, e o segundo é para o Functions 1. x.The first example is for Functions 2.x and higher, and the second one is for Functions 1.x.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}
{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "path": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

O código F# é o seguinte:Here's the F# code:

let Run(myTimer: TimerInfo, outputEventHubMessage: byref<string>, log: ILogger) =
    let msg = sprintf "TimerTriggerFSharp1 executed at: %s" DateTime.Now.ToString()
    log.LogInformation(msg);
    outputEventHubMessage <- msg;

Saída - exemplo JavaScriptOutput - JavaScript example

O exemplo a seguir mostra uma associação de gatilho de hub de eventos em um arquivo function.json e uma função JavaScript que usa a associação.The following example shows an event hub trigger binding in a function.json file and a JavaScript function that uses the binding. A função grava uma mensagem em um hub de eventos.The function writes a message to an event hub.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file. O primeiro exemplo é para o Functions 2. x e superior, e o segundo é para o Functions 1. x.The first example is for Functions 2.x and higher, and the second one is for Functions 1.x.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}
{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "path": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Este é o código JavaScript que envia uma mensagem única:Here's JavaScript code that sends a single message:

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();
    context.log('Message created at: ', timeStamp);   
    context.bindings.outputEventHubMessage = "Message created at: " + timeStamp;
    context.done();
};

Este é o código JavaScript que envia várias mensagens:Here's JavaScript code that sends multiple messages:

module.exports = function(context) {
    var timeStamp = new Date().toISOString();
    var message = 'Message created at: ' + timeStamp;

    context.bindings.outputEventHubMessage = [];

    context.bindings.outputEventHubMessage.push("1 " + message);
    context.bindings.outputEventHubMessage.push("2 " + message);
    context.done();
};

Saída – exemplo do PythonOutput - Python example

O exemplo a seguir mostra uma ligação de acionador do Hub de Eventos em um arquivo function.json e uma função Python que usa a ligação.The following example shows an event hub trigger binding in a function.json file and a Python function that uses the binding. A função grava uma mensagem em um hub de eventos.The function writes a message to an event hub.

Os exemplos a seguir mostram dados de associação de Hubs de eventos no function.json arquivo.The following examples show Event Hubs binding data in the function.json file.

{
    "type": "eventHub",
    "name": "$return",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Este é o código Python que envia uma mensagem única:Here's Python code that sends a single message:

import datetime
import logging
import azure.functions as func


def main(timer: func.TimerRequest) -> str:
    timestamp = datetime.datetime.utcnow()
    logging.info('Message created at: %s', timestamp)
    return 'Message created at: {}'.format(timestamp)

Saída - exemplo de JavaOutput - Java example

O exemplo a seguir mostra uma função Java que grava uma mensagem contendo a hora atual em um Hub de Eventos.The following example shows a Java function that writes a message contianing the current time to an Event Hub.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 *&#47;5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

Na biblioteca de runtime de funções Java, use a anotação @EventHubOutput em parâmetros cujo valor seria publicado no Hub de Eventos.In the Java functions runtime library, use the @EventHubOutput annotation on parameters whose value would be published to Event Hub. O parâmetro deve ser do tipo OutputBinding<T>, em que T é um POJO ou qualquer tipo Java nativo.The parameter should be of type OutputBinding<T> , where T is a POJO or any native Java type.

Saída - atributosOutput - attributes

Para bibliotecas de classes de C#, utilize o atributo EventHubAttribute.For C# class libraries, use the EventHubAttribute attribute.

O construtor do atributo usa os nomes do hub de eventos e de uma configuração de aplicativo que contenham a cadeia de caracteres de conexão.The attribute's constructor takes the name of the event hub and the name of an app setting that contains the connection string. Para obter mais informações sobre essas configurações, consulte Saída - configuração.For more information about these settings, see Output - configuration. Este é um EventHub exemplo de atributo:Here's an EventHub attribute example:

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    ...
}

Para ver um exemplo completo, consulte Saída – exemplo de C#.For a complete example, see Output - C# example.

Saída - configuraçãoOutput - configuration

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json e no EventHub atributo.The following table explains the binding configuration properties that you set in the function.json file and the EventHub attribute.

Propriedade function.jsonfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
tipotype N/Dn/a Deve ser definido como "eventHub".Must be set to "eventHub".
directiondirection N/Dn/a Deve ser definido como "out".Must be set to "out". Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.This parameter is set automatically when you create the binding in the Azure portal.
namename N/Dn/a É o nome da variável usada no código da função que representa o evento.The variable name used in function code that represents the event.
pathpath EventHubNameEventHubName Funciona apenas 1. x.Functions 1.x only. O nome do hub de eventos.The name of the event hub. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.When the event hub name is also present in the connection string, that value overrides this property at runtime.
eventHubNameeventHubName EventHubNameEventHubName Functions 2. x e superior.Functions 2.x and higher. O nome do hub de eventos.The name of the event hub. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.When the event hub name is also present in the connection string, that value overrides this property at runtime.
conexãoconnection ConexãoConnection É o nome de uma configuração de aplicativo que contém a cadeia de conexão para o namespace do hub de eventos.The name of an app setting that contains the connection string to the event hub's namespace. Copie essa cadeia de conexão clicando no botão Informações de Conexão do namespace, não no próprio hub de eventos.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Essa cadeia de conexão deve ter permissões de envio para enviar a mensagem à transmissão do evento.This connection string must have send permissions to send the message to the event stream.

Quando você estiver desenvolvendo localmente, as configurações de aplicativo serão adicionadas ao arquivo local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Saída - usoOutput - usage

Em C# e C# script, envie mensagens usando um parâmetro de método, como out string paramName.In C# and C# script, send messages by using a method parameter such as out string paramName. No script do C#, paramName é o valor especificado na propriedade name de function.json.In C# script, paramName is the value specified in the name property of function.json. Para gravar várias mensagens, você pode usar ICollector<string> ou IAsyncCollector<string> no lugar de out string.To write multiple messages, you can use ICollector<string> or IAsyncCollector<string> in place of out string.

Em JavaScript, acesse o evento de saída usando context.bindings.<name>.In JavaScript, access the output event by using context.bindings.<name>. <name> é o valor especificado na propriedade name de function.json.<name> is the value specified in the name property of function.json.

Exceções e códigos de retornoExceptions and return codes

AssociaçãoBinding ReferênciaReference
Hub de EventoEvent Hub Guia de OperaçõesOperations Guide

configurações de host.jsonhost.json settings

Esta seção descreve as definições de configuração global disponíveis para essa associação nas versões 2. x e superior.This section describes the global configuration settings available for this binding in versions 2.x and higher. O arquivo host. JSON de exemplo abaixo contém apenas as configurações da versão 2. x + para essa associação.The example host.json file below contains only the version 2.x+ settings for this binding. Para obter mais informações sobre definições de configuração global nas versões 2. x e posteriores, consulte referência de host. JSON para Azure Functions.For more information about global configuration settings in versions 2.x and beyond, see host.json reference for Azure Functions.

Observação

Para obter uma referência de host.json no Functions 1.x, consulte Referência de host.json para o Azure Functions 1.x.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            }
        }
    }
}  
PropriedadeProperty PadrãoDefault DescriçãoDescription
maxBatchSizemaxBatchSize 6464 A contagem máxima de eventos recebidos por loop de recebimento.The maximum event count received per receive loop.
prefetchCountprefetchCount N/Dn/a O PrefetchCount padrão que será usado pelo EventProcessorHost subjacente.The default PrefetchCount that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 O número de lotes de eventos para processar antes de criar um ponto de verificação do cursor do EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

Próximos passosNext steps