Hubs de Eventos do Azure gatilho para Funções do Azure

Este artigo explica como trabalhar com Hubs de Eventos do Azure gatilho para Funções do Azure. Funções do Azure suporta as ligações de gatilho e saída para os Centros de Eventos.

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

Utilize o gatilho de função para responder a um evento enviado para um stream de eventos do centro de eventos. Deve ter lido o acesso ao centro de eventos subjacente para configurar o gatilho. Quando a função é desencadeada, a mensagem transmitida para a função é dactilografada como uma corda.

Exemplo

O exemplo a seguir mostra uma função C# que regista o corpo de mensagens do gatilho do Event Hubs.

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

Para ter acesso aos metadados de eventos no código de função, ligue-se a um objeto EventData . Também pode aceder às mesmas propriedades usando expressões de encadernação na assinatura do método. O exemplo a seguir mostra ambas as formas de obter os mesmos dados:

[FunctionName("EventHubTriggerCSharp")]
public 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 num lote, faça string ou EventData array.

Nota

Ao receber num lote não pode ligar-se a parâmetros metódicos como no exemplo acima com DateTime enqueuedTimeUtc e deve recebê-los de cada EventData objeto

[FunctionName("EventHubTriggerCSharp")]
public 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}");
    }
}

O exemplo a seguir mostra uma ligação de gatilho de Centros de Eventos num ficheiro function.json e numa função JavaScript que utiliza a ligação. A função lê metadados de evento e regista a mensagem.

O exemplo a seguir mostra um dado de ligação do Event Hubs no ficheiro function.json , que é diferente para a versão 1.x do tempo de execução de Funções em comparação com versões posteriores.

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

Aqui está o código JavaScript:

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 num lote, definido cardinality no many ficheiro function.json , como mostrado nos seguintes exemplos.

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

Aqui está o código JavaScript:

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();
};

Estão pendentes exemplos completos do PowerShell.

O exemplo a seguir mostra uma ligação do gatilho de Centros de Eventos num ficheiro function.json e numa função Python que utiliza a ligação. A função lê metadados de evento e regista a mensagem.

Os exemplos a seguir mostram dados de ligação do Event Hubs no ficheiro function.json .

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

Aqui está o código Python:

import logging
import azure.functions as func


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

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

O exemplo a seguir mostra uma ligação de gatilho de Centros de Eventos que regista o corpo de mensagens do gatilho do Event Hubs.

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

Na biblioteca de funções Java, utilize a EventHubTrigger anotação em parâmetros cujo valor provém do centro de eventos. Parâmetros com estas anotações fazem com que a função funcione quando um evento chega. Esta anotação pode ser usada com tipos nativos de Java, POJOs ou valores anulados usando Optional<T>.

O exemplo a seguir ilustra o uso extensivo de SystemProperties e outras opções vinculativas para uma maior introspeção 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 de processo em processo e isolado C# utilizam o atributo para configurar o gatilho. O script C# utiliza, em vez disso, um ficheiro de configuração fun.json.

Nas bibliotecas de classe C#, utilize o EventHubTriggerAttribute, que suporta as seguintes propriedades.

Parâmetros Description
Nome eventHub O nome do centro de eventos. Quando o nome do hub do evento também está presente na cadeia de ligação, esse valor substitui esta propriedade em tempo de execução. Pode ser referenciado em configurações de aplicativos, como %eventHubName%
Grupo de Consumidores Um imóvel opcional que define o grupo de consumidores usado para subscrever eventos no centro. Quando omitido, o $Default grupo de consumidores é utilizado.
Ligação O nome de uma configuração de aplicação ou coleção de definição que especifica como se conectar com Os Centros de Eventos. Para saber mais, consulte as Ligações.

Anotações

Na biblioteca de funções Java, utilize a anotação EventHubTrigger , que suporta as seguintes definições:

Configuração

A tabela seguinte explica as propriedades de configuração do gatilho que definiu no ficheiro function.json , que difere por versão de tempo de execução.

function.json propriedade Description
tipo Deve ser definido para eventHubTrigger. Esta propriedade é definida automaticamente quando cria o gatilho no portal do Azure.
direção Deve ser definido para in. Esta propriedade é definida automaticamente quando cria o gatilho no portal do Azure.
nome O nome da variável que representa o item do evento no código de função.
eventHubName O nome do centro de eventos. Quando o nome do hub do evento também está presente na cadeia de ligação, esse valor substitui esta propriedade em tempo de execução. Pode ser referenciado através de configurações de aplicativos%eventHubName%
consumerGroup Um imóvel opcional que define o grupo de consumidores usado para subscrever eventos no centro. Se omitido, o $Default grupo de consumidores é utilizado.
cardinalidade De modo a many ativar o lote. Se omitir ou definir, oneuma única mensagem é transmitida para a função.
conexão O nome de uma configuração de aplicação ou coleção de definição que especifica como se conectar com Os Centros de Eventos. Ver Ligações.

Quando estiver a desenvolver localmente, adicione as definições de aplicação no ficheiro local.settings.json na Values coleção.

Utilização

Para saber mais sobre como os Centros de Eventos disparam e Hub IoT escalas de gatilho, consulte o gatilho do Event Hubs.

O tipo de parâmetro suportado pela ligação de saída do Event Hubs depende da versão de tempo de execução de Funções, da versão do pacote de extensão e da modalidade C# utilizada.

As funções da biblioteca da classe C# suportam os seguintes tipos:

Esta versão do EventData deixa cair o suporte para o tipo legado Body a favor do EventBody.

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

  • Quaisquer tipos nativos de Java, tais como int, String, byte[].
  • Valores anulados utilizando opcional.
  • Qualquer tipo de POJO.

Para saber mais, consulte a referência EventHubTrigger .

Metadados de eventos

O gatilho do Event Hubs fornece várias propriedades de metadados. As propriedades dos metadados podem ser usadas como parte de expressões de ligação noutras ligações ou como parâmetros no seu código. As propriedades provêm da classe EventData .

Propriedade Tipo Description
PartitionContext PartitionContexto O PartitionContext exemplo.
EnqueuedTimeUtc DateTime O tempo encadeado na UTC.
Offset string A compensação dos dados relativos ao fluxo de partição do centro de eventos. O offset é um marcador ou identificador para um evento dentro do stream de Centros de Eventos. O identificador é único dentro de uma partição do fluxo de Centros de Eventos.
PartitionKey string A partição para a qual os dados do evento devem ser enviados.
Properties IDictionary<String,Object> As propriedades do utilizador dos dados do evento.
SequenceNumber Int64 O número da 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 utilizam estas propriedades anteriormente neste artigo.

Ligações

A connection propriedade é uma referência à configuração do ambiente que especifica como a aplicação deve ligar-se aos Centros de Eventos. Pode especificar:

Se o valor configurado for simultaneamente uma correspondência exata para uma única definição e uma correspondência de prefixo para outras definições, a correspondência exata é utilizada.

Cadeia de ligação

Obtenha esta cadeia de ligação clicando no botão Informação de Ligação para o espaço de nomes, não para o próprio centro de eventos. A cadeia de ligação deve ser para um espaço de nomes de Event Hubs, não para o próprio centro de eventos.

Quando utilizado para os gatilhos, a cadeia de ligação deve ter pelo menos permissões de "ler" para ativar a função. Quando utilizado para encadernações de saída, o fio de ligação deve ter permissões de "enviar" para enviar mensagens para o fluxo de eventos.

Esta cadeia de ligação deve ser armazenada numa definição de aplicação com um nome que corresponda ao valor especificado pela connection propriedade da configuração de encadernação.

Conexões baseadas em identidade

Se estiver a utilizar a versão 5.x ou superior da extensão, em vez de utilizar uma cadeia de ligação com um segredo, pode pedir à aplicação que utilize uma identidade do Azure Ative Directory. Para isso, definiria definições sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e ligação.

Neste modo, a extensão requer as seguintes propriedades:

Nota

A variável ambiental fornecida deve atualmente ser prefixada para AzureWebJobs funcionar no plano de Consumo. Nos planos Premium, este prefixo não é necessário.

Propriedade Modelo variável do ambiente Description Valor de exemplo
Espaço de nome totalmente qualificado AzureWebJobs<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O espaço de nomes de Event Hubs totalmente qualificado. <>event_hubs_namespace.servicebus.windows.net

Propriedades adicionais podem ser definidas para personalizar a ligação. Consulte propriedades comuns para ligações baseadas na identidade.

Nota

Ao utilizar Azure App Configuration ou Key Vault para fornecer definições para ligações de identidade gerida, os nomes de definição devem utilizar um separador de chave válido, como : ou / no lugar do para garantir que os __ nomes são resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quando hospedados no serviço Funções do Azure, as ligações baseadas na identidade utilizam uma identidade gerida. A identidade atribuída ao sistema é utilizada por padrão, embora uma identidade atribuída ao utilizador possa ser especificada com as credential propriedades e clientID propriedades. Note que configurar uma identidade atribuída ao utilizador com um ID de recurso não é suportado. Quando executado em outros contextos, como o desenvolvimento local, a sua identidade de desenvolvedor é usada em vez disso, embora isso possa ser personalizado. Consulte o desenvolvimento local com ligações baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja a ser usada deve ter permissões para executar as ações pretendidas. Você precisará atribuir um papel no Azure RBAC, usando papéis incorporados ou personalizados que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço alvo que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo a identidade apenas os privilégios necessários. Por exemplo, se a aplicação apenas precisar de ser capaz de ler a partir de uma fonte de dados, use uma função que apenas tenha permissão para ler. Seria inadequado atribuir um papel que também permite escrever a esse serviço, uma vez que seria uma autorização excessiva para uma operação de leitura. Da mesma forma, gostaria de garantir que a atribuição de funções é apenas limitada aos recursos que precisam de ser lidos.

Você precisará criar uma tarefa de função que forneça acesso ao seu centro de eventos em tempo de execução. O âmbito da atribuição de funções deve ser para um espaço de nomes de Event Hubs, não para o próprio centro de eventos. Funções de gestão como o Proprietário não são suficientes. A tabela que se segue mostra funções incorporadas que são recomendadas quando se utiliza a extensão do Event Hubs em funcionamento normal. A sua aplicação pode requerer permissões adicionais com base no código que escreve.

Tipo de encadernação Funções incorporadas exemplo
Acionador Recetor de Dados Hubs de Eventos do Azure, Proprietário de Dados Hubs de Eventos do Azure
Ligação de saída Hubs de Eventos do Azure Remetente de Dados

configurações host.json

O ficheiro host.json contém definições que controlam o comportamento do Event Hubs. Consulte a secção de definições host.json para obter informações sobre as definições disponíveis.

Passos seguintes