Associazioni di Hub eventi di Azure per Funzioni di AzureAzure Event Hubs bindings for Azure Functions

Questo articolo illustra come usare le associazioni di Hub eventi di Azure in Funzioni di Azure.This article explains how to work with Azure Event Hubs bindings for Azure Functions. Funzioni di Azure supporta il trigger e le associazioni di output per Hub eventi.Azure Functions supports trigger and output bindings for Event Hubs.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

TriggerTrigger

È possibile usare il trigger di Hub eventi per rispondere a un evento inviato a un flusso di eventi di Hub eventi.Use the Event Hubs trigger to respond to an event sent to an event hub event stream. Per configurare il trigger è necessario avere accesso in lettura ad Hub eventi.You must have read access to the event hub to set up the trigger.

Quando viene attivata una funzione trigger di Hub eventi, il messaggio che la attiva viene passato alla funzione sotto forma di stringa.When an Event Hubs trigger function is triggered, the message that triggers it is passed into the function as a string.

Trigger - ridimensionamentoTrigger - scaling

Ogni istanza di una funzione attivata di Hub eventi è supportata da una sola istanza di EventProcessorHost (EPH).Each instance of an Event Hub-Triggered Function is backed by only 1 EventProcessorHost (EPH) instance. Hub eventi garantisce che solo un EPH può ottenere un lease in una determinata partizione.Event Hubs ensures that only 1 EPH can get a lease on a given partition.

Si supponga, ad esempio, di iniziare con la configurazione e i presupposti seguenti per un Hub eventi:For example, suppose we begin with the following setup and assumptions for an Event Hub:

  1. 10 partizioni.10 partitions.
  2. 1000 eventi distribuiti in modo uniforme tra tutte le partizioni = > 100 messaggi in ogni partizione.1000 events distributed evenly across all partitions => 100 messages in each partition.

Quando la funzione è stata abilitata, è solo 1 istanza della funzione.When your function is first enabled, there is only 1 instance of the function. Denominiamo questa istanza della funzione Function_0.Let's call this function instance Function_0. Function_0 avrà un EPH che gestisce per ottenere un lease in tutte le 10 partizioni.Function_0 will have 1 EPH that manages to get a lease on all 10 partitions. Inizierà la lettura degli eventi dalle partizioni da 0 a 9.It will start reading events from partitions 0-9. A partire da questo punto potranno verificarsi una delle condizioni seguenti:From this point forward, one of the following will happen:

  • È necessaria una sola istanza della funzione - Function_0 è in grado di elaborare tutti i 1000 eventi prima che si attivi la logica di ridimensionamento delle Funzioni di Azure.Only 1 function instance is needed - Function_0 is able to process all 1000 before the Azure Functions' scaling logic kicks in. Di conseguenza, tutti i 1000 messaggi vengono elaborati da Function_0.Hence, all 1000 messages are processed by Function_0.

  • Aggiunta di un'altra istanza della funzione - La logica di ridimensionamento delle Funzioni di Azure determina che Function_0 presenta più messaggi di quanti ne possa elaborare e quindi viene creata una nuova istanza, Function_1.Add 1 more function instance - Azure Functions' scaling logic determines that Function_0 has more messages than it can process, so a new instance, Function_1, is created. Hub eventi rileva che una nuova istanza EPH sta tentando di leggere i messaggi.Event Hubs detects that a new EPH instance is trying read messages. Hub eventi avvierà il bilanciamento del carico delle partizioni tra le istanze EPH, ad esempio, le partizioni da 0 a 4 vengono assegnate a Function_0 e le partizioni da 5 a 9 a Function_1.Event Hubs will start load balancing the partitions across the EPH instances, e.g., partitions 0-4 are assigned to Function_0 and partitions 5-9 are assigned to Function_1.

  • Aggiunta di N altre istanze della funzione - La logica di ridimensionamento delle Funzioni di Azure determina che sia Function_0 sia Function_1 hanno più messaggi di quanti ne possano elaborare.Add N more function instances - Azure Functions' scaling logic determines that both Function_0 and Function_1 have more messages than they can process. Verrà eseguito il ridimensionamento per Function_2...N, dove N è maggiore delle partizioni di Hub eventi.It will scale again for Function_2...N, where N is greater than the Event Hub paritions. Hub eventi eseguirà il bilanciamento del carico delle partizioni nelle istanze Function_0... 9.Event Hubs will load balance the partitions across Function_0...9 instances.

Un fattore univoco della logica di ridimensionamento corrente delle Funzioni di Azure è che N è maggiore del numero di partizioni.Unique to Azure Functions' current scaling logic is the fact that N is greater than the number of partitions. Questa operazione viene eseguita per assicurare che ci siano sempre istanze di EPH immediatamente disponibili per ottenere rapidamente un blocco delle partizioni appena diventano disponibili da altre istanze.This is done to ensure that there are always instances of EPH readily available to quickly get a lock on the partition(s) as they become available from other instances. Agli utenti vengono addebitati solo i costi delle risorse usate quando viene eseguita l'istanza della funzione e non vengono addebitati i costi dell'overprovisioning.Users are only charged for the resources used when the function instance executes, and are not charged for this over-provisioning.

Se tutte le esecuzioni delle funzioni riescono senza errori, i checkpoint vengono aggiunti all'account di archiviazione associato.If all function executions succeed without errors, checkpoints are added to the associated storage account. Quando il checkpoint ha esito positivo, non sarà più necessario recuperare nuovamente tutti i 1000 messaggi.When check-pointing succeeds, all 1000 messages should never be retrieved again.

Trigger - esempioTrigger - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Trigger - esempio in C#Trigger - C# example

Nell'esempio seguente un funzione c# che registra il corpo del messaggio del trigger di hub eventi.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 = "EventHubConnection")] string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# Event Hub trigger function processed a message: {myEventHubMessage}");
}

Per ottenere l'accesso ai metadati dell'evento, associare un oggetto EventData (richiede un'istruzione using per Microsoft.ServiceBus.Messaging).To get access to the event metadata, bind to an EventData object (requires a using statement for Microsoft.ServiceBus.Messaging).

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnection")] EventData myEventHubMessage, TraceWriter log)
{
    log.Info($"{Encoding.UTF8.GetString(myEventHubMessage.GetBytes())}");
}

Per ricevere gli eventi in un batch, impostare string o EventData come matrice:To receive events in a batch, make string or EventData an array:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnection")] string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# Event Hub trigger function processed a message: {message}");
    }
}

Trigger - esempio di script C#Trigger - C# script example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione script C# che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and a C# script function that uses the binding. La funzione registra il corpo del messaggio del trigger per Hub eventi.The function logs the message body of the event hub trigger.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice script C#:Here's the C# script code:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# Event Hub trigger function processed a message: {myEventHubMessage}");
}

Per ottenere l'accesso ai metadati dell'evento, associare un oggetto EventData (richiede un'istruzione 'using' per Microsoft.ServiceBus.Messaging).To get access to the event metadata, bind to an EventData object (requires a using statement for Microsoft.ServiceBus.Messaging).

#r "Microsoft.ServiceBus"
using System.Text;
using Microsoft.ServiceBus.Messaging;

public static void Run(EventData myEventHubMessage, TraceWriter log)
{
    log.Info($"{Encoding.UTF8.GetString(myEventHubMessage.GetBytes())}");
}

Per ricevere gli eventi in un batch, impostare string o EventData come matrice: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# Event Hub trigger function processed a message: {message}");
    }
}

Trigger - Esempio in F#Trigger - F# example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione F# che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and an F# function that uses the binding. La funzione registra il corpo del messaggio del trigger per Hub eventi.The function logs the message body of the event hub trigger.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice F#:Here's the F# code:

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

Trigger - esempio JavaScriptTrigger - JavaScript example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione registra il corpo del messaggio del trigger per Hub eventi.The function logs the message body of the event hub trigger.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice JavaScript:Here's the JavaScript code:

module.exports = function (context, myEventHubMessage) {
    context.log('Node.js eventhub trigger function processed work item', myEventHubMessage);    
    context.done();
};

Trigger - attributiTrigger - attributes

In librerie di classi c#, utilizzare il EventHubTriggerAttribute attributo, che è definito nel pacchetto NuGet Microsoft.Azure.WebJobs.ServiceBus.In C# class libraries, use the EventHubTriggerAttribute attribute, which is defined in NuGet package Microsoft.Azure.WebJobs.ServiceBus.

Il costruttore dell'attributo accetta il nome di Hub eventi, il nome del gruppo di consumer e il nome di un'impostazione di app che contiene la stringa di connessione.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. Per altre informazioni su queste impostazioni, vedere la sezione relativa alla configurazione dei trigger.For more information about these settings, see the trigger configuration section. Di seguito è riportato un esempio di attributo EventHubTriggerAttribute:Here's an EventHubTriggerAttribute attribute example:

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

Per un esempio completo, vedere Trigger - esempio c#.For a complete example, see Trigger - C# example.

Trigger - configurazioneTrigger - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo EventHubTrigger.The following table explains the binding configuration properties that you set in the function.json file and the EventHubTrigger attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DESCRIZIONEDescription
typetype n/dn/a Il valore deve essere impostato su eventHubTrigger.Must be set to eventHubTrigger. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/dn/a Il valore deve essere impostato su in.Must be set to in. Questa proprietà viene impostata automaticamente quando si crea il trigger nel portale di Azure.This property is set automatically when you create the trigger in the Azure portal.
nomename n/dn/a Nome della variabile che rappresenta l'elemento evento nel codice della funzione.The name of the variable that represents the event item in function code.
pathpath EventHubNameEventHubName Nome di Hub eventi.The name of the event hub.
consumerGroupconsumerGroup ConsumerGroupConsumerGroup Proprietà facoltativa usata per impostare il gruppo di consumer usato per effettuare la sottoscrizione agli eventi nell'hub.An optional property that sets the consumer group used to subscribe to events in the hub. Se omessa, al suo posto viene usato il gruppo di consumer $Default.If omitted, the $Default consumer group is used.
connessioneconnection ConnectionConnection Nome di un'impostazione dell'app che contiene la stringa di connessione per lo spazio dei nomi di Hub eventi.The name of an app setting that contains the connection string to the event hub's namespace. Copiare questa stringa di connessione facendo clic sul pulsante Informazioni di connessione per lo spazio dei nomi, non per lo stesso Hub eventi.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Per attivare il trigger, questa stringa di connessione deve disporre almeno delle autorizzazioni Read.This connection string must have at least read permissions to activate the trigger.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Trigger - proprietà di host.jsonTrigger - host.json properties

Il file host.json contiene le impostazioni che controllano il comportamento del trigger per Hub eventi.The host.json file contains settings that control Event Hubs trigger behavior.

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
ProprietàProperty DefaultDefault DescrizioneDescription
maxBatchSizemaxBatchSize 6464 Il numero massimo degli eventi ricevuto per ogni ciclo di ricezione.The maximum event count received per receive loop.
prefetchCountprefetchCount n/dn/a Il valore predefinito di PrefetchCount che verrà utilizzato dall’EventProcessorHost sottostante.The default PrefetchCount that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 Il numero di batch di eventi da elaborare prima di creare un checkpoint di cursore EventHub.The number of event batches to process before creating an EventHub cursor checkpoint.

OutputOutput

È possibile usare l'associazione di output di Hub eventi per scrivere eventi in un flusso di eventi.Use the Event Hubs output binding to write events to an event stream. Per scrivervi eventi, è necessario disporre dell'autorizzazione Send verso un Hub eventi.You must have send permission to an event hub to write events to it.

Output - esempioOutput - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Output - esempio in C#Output - C# example

Nell'esempio seguente un funzione c# che scrive un messaggio a un hub eventi, utilizzando il valore restituito del metodo come output: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 = "EventHubConnection")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, TraceWriter log)
{
    log.Info($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

Output - esempio di script C#Output - C# script example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione script C# che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and a C# script function that uses the binding. La funzione scrive un messaggio in un Hub eventi.The function writes a message to an event hub.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice script C# che crea un messaggio:Here's C# script code that creates one message:

using System;

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

Ecco il codice script C# che crea più messaggi:Here's C# script code that creates multiple messages:

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

Output - esempio in F#Output - F# example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione F# che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and an F# function that uses the binding. La funzione scrive un messaggio in un Hub eventi.The function writes a message to an event hub.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice F#:Here's the F# code:

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

Output - esempio JavaScriptOutput - JavaScript example

L'esempio seguente mostra un'associazione di trigger per Hub eventi in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows an event hub trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione scrive un messaggio in un Hub eventi.The function writes a message to an event hub.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

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

Ecco il codice JavaScript che invia un messaggio:Here's JavaScript code that sends a single message:

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

Ecco il codice JavaScript che invia più messaggi:Here's JavaScript code that sends multiple messages:

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

    context.bindings.outputEventHubMessage = [];

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

Output - attributiOutput - attributes

Per librerie di classi c#, utilizzare il EventHubAttribute attributo, che è definito nel pacchetto NuGet Microsoft.Azure.WebJobs.ServiceBus.For C# class libraries, use the EventHubAttribute attribute, which is defined in NuGet package Microsoft.Azure.WebJobs.ServiceBus.

Il costruttore dell'attributo accetta il nome di Hub eventi e il nome di un'impostazione di app che contiene la stringa di connessione.The attribute's constructor takes the name of the event hub and the name of an app setting that contains the connection string. Per altre informazioni su queste impostazioni, vedere la sezione relativa alla configurazione dell'output.For more information about these settings, see Output - configuration. Di seguito è riportato un esempio di attributo EventHub:Here's an EventHub attribute example:

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

Per un esempio completo, vedere Output - esempio c#.For a complete example, see Output - C# example.

Output - configurazioneOutput - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo EventHub.The following table explains the binding configuration properties that you set in the function.json file and the EventHub attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DESCRIZIONEDescription
typetype n/dn/a Il valore deve essere impostato su "eventHub".Must be set to "eventHub".
directiondirection n/dn/a Deve essere impostato su "out".Must be set to "out". Questo parametro viene impostato automaticamente quando si crea l'associazione nel portale di Azure.This parameter is set automatically when you create the binding in the Azure portal.
nomename n/dn/a Nome della variabile usato nel codice della funzione che rappresenta l'evento.The variable name used in function code that represents the event.
pathpath EventHubNameEventHubName Nome di Hub eventi.The name of the event hub.
connessioneconnection ConnectionConnection Nome di un'impostazione dell'app che contiene la stringa di connessione per lo spazio dei nomi di Hub eventi.The name of an app setting that contains the connection string to the event hub's namespace. Copiare questa stringa di connessione facendo clic sul pulsante Informazioni di connessione per lo spazio dei nomi, non per lo stesso Hub eventi.Copy this connection string by clicking the Connection Information button for the namespace, not the event hub itself. Per inviare il messaggio al flusso di eventi, questa stringa di connessione deve disporre di autorizzazioni Send.This connection string must have send permissions to send the message to the event stream.

Quando si sviluppa in locale, le impostazioni dell'app vengono inserite nel file local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Output - usoOutput - usage

In C# e negli script C# è possibile inviare messaggi con un parametro del metodo, ad esempio out string paramName.In C# and C# script, send messages by using a method parameter such as out string paramName. Negli script C#, paramName è il valore specificato nella proprietà name di function.json.In C# script, paramName is the value specified in the name property of function.json. Per scrivere più messaggi, è possibile usare ICollector<string> o IAsyncCollector<string> al posto di out string.To write multiple messages, you can use ICollector<string> or IAsyncCollector<string> in place of out string.

In JavaScript accedere all'evento di output usando context.bindings.<name>.In JavaScript, access the output event by using context.bindings.<name>. <name> è il valore specificato nella proprietà name di function.json.<name> is the value specified in the name property of function.json.

Passaggi successiviNext steps