Gatilho do Hub IoT do Azure para o Azure Functions

  • Artigo

Este artigo explica como trabalhar com associações do Azure Functions para o Hub IoT. O suporte ao Hub IoT é baseado na Vinculação de Hubs de Eventos do Azure.

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral.

Importante

Embora os exemplos de código a seguir usem a API do Hub de Eventos, a sintaxe fornecida é aplicável para funções do Hub IoT.

Use o gatilho de função para responder a um evento enviado para um fluxo de eventos do hub de eventos. Você deve ter acesso de leitura ao hub de eventos subjacente para configurar o gatilho. Quando a função é acionada, a mensagem passada para a função é digitada como uma cadeia de caracteres.

As decisões de dimensionamento dos Hubs de Eventos para os planos Consumo e Premium são feitas por meio do Target Based Scaling. Para obter mais informações, consulte Target Based Scaling.

Para obter informações sobre como o Azure Functions responde a eventos enviados para um fluxo de eventos do hub de eventos usando gatilhos, consulte Integrar Hubs de Eventos com funções sem servidor no Azure.

Importante

Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

O Azure Functions suporta dois modelos de programação para Python. A maneira como você define suas ligações depende do modelo de programação escolhido.

O modelo de programação Python v2 permite definir ligações usando decoradores diretamente em seu código de função Python. Para obter mais informações, consulte o guia do desenvolvedor do Python.

Este artigo suporta ambos os modelos de programação.

Exemplo

O exemplo a seguir mostra uma função C# que é acionada com base em um hub de eventos, onde a cadeia de caracteres da mensagem de entrada é gravada nos logs:

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

O exemplo a seguir mostra uma função TypeScript de gatilho de Hubs de Eventos. A função lê metadados de eventos e registra a mensagem.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

Para receber eventos em um lote, defina cardinality como many, conforme mostrado no exemplo a seguir.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

O exemplo a seguir mostra uma função JavaScript de gatilho de Hubs de Eventos. A função lê metadados de eventos e registra a mensagem.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

Para receber eventos em um lote, defina cardinality como many, conforme mostrado no exemplo a seguir.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

Aqui está o código do PowerShell:

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

O exemplo a seguir mostra uma ligação de gatilho de Hubs de Eventos e uma função Python que usa a ligação. A função lê metadados de eventos e registra a mensagem. O exemplo depende se você usa o modelo de programação Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

O exemplo a seguir mostra uma ligação de gatilho de Hubs de Eventos que registra o corpo da mensagem do gatilho de Hubs de Eventos.

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

Na biblioteca de tempo de execução de funções Java, use a EventHubTrigger anotação em parâmetros cujo valor vem do hub de eventos. Os parâmetros com essas anotações fazem com que a função seja executada quando um evento chega. Essa anotação pode ser usada com tipos Java nativos, POJOs ou valores anuláveis usando Optional<T>.

O exemplo a seguir ilustra o uso extensivo e outras opções de SystemProperties Binding para introspeção adicional do Evento, juntamente com o fornecimento de um caminho bem formado BlobOutput que é hierárquico de Data.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

Atributos

As bibliotecas C# do processo de trabalho isolado e em processo usam o atributo para configurar o gatilho. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Use o para definir um gatilho EventHubTriggerAttribute em um hub de eventos, que oferece suporte às seguintes propriedades.

Parâmetros Description
EventHubName O nome do hub de eventos. Quando o nome do hub de eventos também está presente na cadeia de conexão, esse valor substitui essa propriedade no tempo de execução. Pode ser referenciado nas configurações do aplicativo, como %eventHubName%
Grupo de Consumidores Uma propriedade opcional que define o grupo de consumidores usado para se inscrever em eventos no hub. Quando omitido, o grupo de $Default consumidores é utilizado.
Ligação O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar a Hubs de Eventos. Para saber mais, consulte Conexões.

Decoradores

Aplica-se apenas ao modelo de programação Python v2.

Para funções Python v2 definidas usando um decorador, as seguintes propriedades no cosmos_db_trigger:

Property Description
arg_name O nome da variável que representa o item de evento no código de função.
event_hub_name O nome do hub de eventos. Quando o nome do hub de eventos também está presente na cadeia de conexão, esse valor substitui essa propriedade no tempo de execução.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar a Hubs de Eventos. Consulte Conexões.

Para funções Python definidas usando function.json, consulte a seção Configuração .

Anotações

Na biblioteca de tempo de execução de funções Java, use a anotação EventHubTrigger, que suporta as seguintes configurações:

Configuração

Aplica-se apenas ao modelo de programação Python v1.

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para o app.eventHub() método.

Property Description
eventHubName O nome do hub de eventos. Quando o nome do hub de eventos também está presente na cadeia de conexão, esse valor substitui essa propriedade no tempo de execução. Pode ser referenciado através das definições da aplicação%eventHubName%
Grupo de consumidores Uma propriedade opcional que define o grupo de consumidores usado para se inscrever em eventos no hub. Em caso de omissão, utiliza-se o grupo de $Default consumidores.
cardinalidade Defina como many para habilitar o envio em lote. Se omitida ou definida como one, uma única mensagem é passada para a função.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar a Hubs de Eventos. Consulte Conexões.

A tabela a seguir explica as propriedades de configuração de gatilho definidas no arquivo function.json, que diferem de acordo com a versão de tempo de execução.

function.json propriedade Description
type Deve ser definido como eventHubTrigger. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
direção Deve ser definido como in. Essa propriedade é definida automaticamente quando você cria o gatilho no portal do Azure.
Designação O nome da variável que representa o item de evento no código de função.
eventHubName O nome do hub de eventos. Quando o nome do hub de eventos também está presente na cadeia de conexão, esse valor substitui essa propriedade no tempo de execução. Pode ser referenciado através das definições da aplicação%eventHubName%
Grupo de consumidores Uma propriedade opcional que define o grupo de consumidores usado para se inscrever em eventos no hub. Em caso de omissão, utiliza-se o grupo de $Default consumidores.
cardinalidade Defina como many para habilitar o envio em lote. Se omitida ou definida como one, uma única mensagem é passada para a função.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar a Hubs de Eventos. Consulte Conexões.

Quando estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na Values coleção.

Utilização

Para saber mais sobre como os Hubs de Eventos disparam e o Hub IoT é dimensionado, consulte Consumindo eventos com o Azure Functions.

O tipo de parâmetro suportado pela ligação de saída dos Hubs de Eventos depende da versão de tempo de execução do Functions, da versão do pacote de extensão e da modalidade C# usada.

Quando você deseja que a função processe um único evento, o gatilho de Hubs de Eventos pode se vincular aos seguintes tipos:

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

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

Tipo Description
string[] Uma matriz de eventos do lote, como strings. Cada entrada representa um evento.
EventData[]1 Uma matriz de eventos do lote, como instâncias de Azure.Messaging.EventHubs.EventData. Cada entrada representa um evento.
T[] onde T é um JSON serializável tipo1 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 fazer referência a Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 ou posterior e às dependências comuns para associações de tipo SDK.

O tipo de parâmetro pode ser um dos seguintes:

  • Qualquer tipo nativo de Java, como int, String, byte[].
  • Valores anuláveis usando Optional.
  • Qualquer tipo de POJO.

Para saber mais, consulte a referência EventHubTrigger .

Metadados do evento

O gatilho Hubs de Eventos fornece várias propriedades de metadados. As propriedades de metadados podem ser usadas como parte de expressões de ligação em outras associações ou como parâmetros em seu código. As propriedades vêm da classe EventData .

Propriedade Type Description
PartitionContext PartitionContext A PartitionContext instância.
EnqueuedTimeUtc DateTime A hora enfileirada em UTC.
Offset string O deslocamento dos dados relativos ao fluxo de partição do hub de eventos. O deslocamento é um marcador ou identificador para um evento dentro do fluxo de Hubs de Eventos. O identificador é exclusivo dentro de uma partição do fluxo de Hubs de Eventos.
PartitionKey string A partição para a qual os dados do evento devem ser enviados.
Properties IDictionary<String,Object> As propriedades do usuário dos dados do evento.
SequenceNumber Int64 O número de sequência lógica do evento.
SystemProperties IDictionary<String,Object> As propriedades do sistema, incluindo os dados do evento.

Consulte exemplos de código que usam essas propriedades anteriormente neste artigo.

Ligações

A connection propriedade é uma referência à configuração do ambiente que contém o nome de uma configuração de aplicativo que contém uma cadeia de conexão. Você pode obter essa cadeia de conexão selecionando o botão Informações de Conexão para o namespace. A cadeia de conexão deve ser para um namespace de Hubs de Eventos, não para o hub de eventos em si.

A cadeia de conexão deve ter pelo menos permissões de "leitura" para ativar a função.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela connection propriedade da configuração de ligação.

Nota

As conexões baseadas em identidade não são suportadas pelo gatilho do Hub IoT. Se você precisar usar identidades gerenciadas de ponta a ponta, poderá usar o Roteamento do Hub IoT para enviar dados para um hub de eventos que você controla. Dessa forma, o roteamento de saída pode ser autenticado com identidade gerenciada, o evento pode ser lido a partir desse hub de eventos usando a identidade gerenciada.

host.json propriedades

O arquivo host.json contém configurações que controlam o comportamento do gatilho do Hub de Eventos. Consulte a seção Configurações de host.json para obter detalhes sobre as configurações disponíveis.

Próximos passos