Associazioni di hub IoT di Azure per Funzioni di Azure

  • Articolo

Questo set di articoli illustra come usare le associazioni Funzioni di Azure per hub IoT. Il supporto hub IoT si basa sull'associazione Hub eventi di Azure.

Importante

Mentre gli esempi di codice seguenti usano l'API hub eventi, la sintassi specificata è applicabile per le funzioni di hub IoT.

Azione Type
Rispondere agli eventi inviati a un flusso di eventi dell'hub IoT. Trigger

Installare l'estensione

Il pacchetto NuGet di estensione installato dipende dalla modalità C# usata nell'app per le funzioni:

Le funzioni sono eseguite in un processo di lavoro C# isolato. Per altre informazioni, vedere Guida per l'esecuzione di Funzioni di Azure C# in un processo di lavoro isolato.

La funzionalità dell'estensione varia a seconda della versione dell'estensione:

Questa versione introduce la possibilità di connettersi usando un'identità anziché un segreto. Per un'esercitazione sulla configurazione delle app per le funzioni con identità gestite, vedere l'esercitazione sulla creazione di un'app per le funzioni con connessioni basate su identità.

Aggiungere l'estensione al progetto installando il pacchetto NuGet versione 5.x.

Installare il bundle

L'estensione di Hub eventi fa parte di un bundle di estensione, specificato nel file di progetto host.json. Potrebbe essere necessario modificare questo bundle per modificare la versione dell'associazione o se i bundle non sono già installati. Per altre informazioni, vedere bundle di estensioni.

Questa versione introduce la possibilità di connettersi usando un'identità anziché un segreto. Per un'esercitazione sulla configurazione delle app per le funzioni con identità gestite, vedere l'esercitazione sulla creazione di un'app per le funzioni con connessioni basate su identità.

È possibile aggiungere questa versione dell'estensione dal bundle di estensione v3 aggiungendo o sostituendo il codice seguente nel host.json file:

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

Per altre informazioni, vedere Aggiornare le estensioni.

Tipi di associazioni

I tipi di associazione supportati per .NET dipendono sia dalla versione dell'estensione che dalla modalità di esecuzione C#, che può essere una delle seguenti:

Una libreria di classi di processo di lavoro isolata compilata C# viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare i dettagli del tipo di associazione per la modalità e la versione.

Il processo di lavoro isolato supporta i tipi di parametro in base alle tabelle seguenti. Il supporto per l'associazione ai tipi da Azure.Messaging.EventHubs è disponibile in anteprima.

Trigger per Hub eventi

Quando si vuole che la funzione elabori un singolo evento, il trigger di Hub eventi può essere associato ai tipi seguenti:

Tipo Descrizione
string Evento come stringa. Usare quando l'evento è testo semplice.
byte[] Byte dell'evento.
Tipi serializzabili JSON Quando un evento contiene dati JSON, Funzioni tenta di deserializzare i dati JSON in un tipo POCO (Plain-Old CLR Object).
Azure.Messaging.EventHubs.EventData1 Oggetto evento.
Se si esegue la migrazione da versioni precedenti degli SDK di Hub eventi, si noti che questa versione elimina il supporto per il tipo legacy Body a favore di EventBody.

Quando si vuole che la funzione elabori un batch di eventi, il trigger di Hub eventi può essere associato ai tipi seguenti:

Tipo Descrizione
string[] Matrice di eventi del batch, sotto forma di stringhe. Ogni voce rappresenta un evento.
EventData[]1 Matrice di eventi del batch, come istanze di Azure.Messaging.EventHubs.EventData. Ogni voce rappresenta un evento.
T[] dove T è un tiposerializzabile JSON 1 Matrice di eventi del batch, come istanze di un tipo POCO personalizzato. Ogni voce rappresenta un evento.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 o versione successiva e alle dipendenze comuni per le associazioni di tipi SDK.

Associazione di output di Hub eventi

Quando si vuole che la funzione scriva un singolo evento, l'associazione di output di Hub eventi può essere associata ai tipi seguenti:

Tipo Descrizione
string Evento come stringa. Usare quando l'evento è testo semplice.
byte[] Byte dell'evento.
Tipi serializzabili JSON Oggetto che rappresenta l'evento. Funzioni tenta di serializzare un tipo di oggetto CLR (POCO) normale in dati JSON.

Quando si vuole che la funzione scriva più eventi, l'associazione di output di Hub eventi può essere associata ai tipi seguenti:

Tipo Descrizione
T[] dove T è uno dei singoli tipi di evento Matrice contenente più eventi. Ogni voce rappresenta un evento.

Per altri scenari di output, creare e usare i tipi direttamente da Microsoft.Azure.EventHubs .

impostazioni host.json

Il file host.json contiene impostazioni che controllano il comportamento per il trigger di Hub eventi. La configurazione è diversa a seconda della versione dell'estensione.

{
    "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
            }
        }
    }
}
Proprietà Predefinito Descrizione
maxEventBatchSize2 100 Numero massimo di eventi inclusi in un batch per una singola chiamata. Deve essere almeno 1.
minEventBatchSize1 1 Numero minimo di eventi desiderati in un batch. Il valore minimo si applica solo quando la funzione riceve più eventi e deve essere minore di maxEventBatchSize.
Le dimensioni minime non sono strettamente garantite. Un batch parziale viene inviato quando non è possibile preparare un batch completo prima che maxWaitTime sia trascorso. I batch parziali sono probabilmente anche per la prima chiamata della funzione dopo l'esecuzione del ridimensionamento.
maxWaitTime1 00:01:00 Intervallo massimo di attesa del trigger per riempire un batch prima di richiamare la funzione. Il tempo di attesa viene considerato solo quando minEventBatchSize è maggiore di 1 e viene altrimenti ignorato. Se sono disponibili meno di minEventBatchSize eventi prima della scadenza del tempo di attesa, la funzione viene richiamata con un batch parziale. Il tempo di attesa consentito più lungo è di 10 minuti.

NOTA: questo intervallo non è una garanzia rigorosa per l'intervallo esatto in cui viene richiamata la funzione. C'è una piccola magin di errore a causa della precisione del timer. Quando viene eseguita la scalabilità, la prima chiamata con un batch parziale può verificarsi più rapidamente o può richiedere fino al doppio del tempo di attesa configurato.
batchCheckpointFrequency 1 Numero di batch da elaborare prima di creare un checkpoint per l'hub eventi.
prefetchCount 300 Numero di eventi richiesti con entusiasmo da Hub eventi e mantenuti in una cache locale per consentire alle letture di evitare l'attesa in un'operazione di rete
transportType amqpTcp Protocollo e trasporto usato per comunicare con Hub eventi. Opzioni disponibili: amqpTcp, amqpWebSockets
Webproxy Null Proxy da usare per comunicare con Hub eventi tramite Web Socket. Non è possibile utilizzare un proxy con il amqpTcp trasporto.
customEndpointAddress Null Indirizzo da usare quando si stabilisce una connessione a Hub eventi, consentendo l'instradamento delle richieste di rete tramite un gateway applicazione o un altro percorso necessario per l'ambiente host. Lo spazio dei nomi completo per l'hub eventi è ancora necessario quando viene usato un indirizzo endpoint personalizzato e deve essere specificato in modo esplicito o tramite il stringa di connessione.
targetUnprocessedEventThreshold1 Null Numero desiderato di eventi non elaborati per ogni istanza di funzione. La soglia viene usata nel ridimensionamento basato su destinazione per ignorare la soglia di ridimensionamento predefinita dedotta dall'opzione maxEventBatchSize . Se impostato, il numero totale di eventi non elaborati viene diviso per questo valore per determinare il numero di istanze di funzione necessarie. Il numero di istanze verrà arrotondato fino a un numero che crea una distribuzione di partizione bilanciata.
initialOffsetOptions/type fromStart Posizione nel flusso di eventi per avviare l'elaborazione quando un checkpoint non esiste nell'archiviazione. Si applica a tutte le partizioni. Per altre informazioni, vedere la documentazione di OffsetType. Opzioni disponibili: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc Null Specifica il tempo di accodamento dell'evento nel flusso da cui iniziare l'elaborazione. Se initialOffsetOptions/type viene configurato come fromEnqueuedTime, questa impostazione è obbligatoria. Supporta l'ora in qualsiasi formato supportato da DateTime.Parse (), ad esempio 2020-10-26T20:31Z. Per maggiore chiarezza, è consigliabile specificare anche un fuso orario. Se il fuso orario non viene specificato, Funzioni presuppone il fuso orario locale del computer che esegue l'app per le funzioni, che è espresso in UTC in Azure.
clientRetryOptions/mode exponential Approccio da usare per calcolare i ritardi di ripetizione dei tentativi. La modalità esponenziale ritenta i tentativi con un ritardo in base a una strategia di back-off in cui ogni tentativo aumenterà la durata di attesa prima di riprovare. La modalità fissa ritenta i tentativi a intervalli fissi con ogni ritardo con una durata coerente. Opzioni disponibili: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Durata massima di attesa del completamento di un'operazione di Hub eventi per ogni tentativo.
clientRetryOptions/delay 00:00:00.80 Fattore di ritardo o back-off da applicare tra i tentativi di ripetizione.
clientRetryOptions/maximumDelay 00:00:01 Ritardo massimo consentito tra i tentativi.
clientRetryOptions/maximumRetries 3 Numero massimo di tentativi prima di considerare l'operazione associata non riuscita.

1 L'uso minEventBatchSize di e maxWaitTime richiede la versione 5.3.0 del Microsoft.Azure.WebJobs.Extensions.EventHubs pacchetto o una versione successiva.

2 Il valore predefinito maxEventBatchSize è cambiato nella versione 6.0.0 del Microsoft.Azure.WebJobs.Extensions.EventHubs pacchetto. Nelle versioni precedenti, questo era 10.

Vengono clientRetryOptions usati per ritentare le operazioni tra l'host di Funzioni e Hub eventi, ad esempio il recupero di eventi e l'invio di eventi. Per informazioni sull'applicazione dei criteri di ripetizione dei tentativi alle singole funzioni, vedere le indicazioni sulla gestione degli errori Funzioni di Azure.

Per informazioni di riferimento su host.json in Funzioni di Azure 2.x e versioni successive, vedere Informazioni di riferimento su host.json per Funzioni di Azure.

Passaggi successivi