Vinculação de saída dos Hubs de Eventos do Azure para o Azure Functions

  • Artigo

Este artigo explica como trabalhar com associações de Hubs de Eventos do Azure para o Azure Functions. O Azure Functions dá suporte a associações de gatilho e saída para Hubs de Eventos.

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

Use a associação de saída Hubs de Eventos para gravar eventos em um fluxo de eventos. Para escrever eventos em um hub de eventos, é preciso ter permissão de envio para ele.

Verifique se as referências de pacote necessárias estão em vigor antes de tentar implementar uma ligação de saída.

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 grava uma cadeia de caracteres de mensagem em um hub de eventos, usando o valor de retorno do método como saída:

[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 acionada por temporizador que envia uma única mensagem para um hub de eventos:

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

O exemplo a seguir mostra uma função JavaScript acionada por temporizador que envia uma única mensagem para um hub de eventos:

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

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Para gerar várias mensagens, retorne uma matriz em vez de um único objeto. Por exemplo:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Exemplos completos do PowerShell estão pendentes.

O exemplo a seguir mostra uma ligação de gatilho de hub de eventos e uma função Python que usa a ligação. A função grava uma mensagem em um hub de eventos. 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="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Aqui está o código Python que envia várias mensagens:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

O exemplo a seguir mostra uma função Java que grava uma mensagem contendo a hora atual em um hub de eventos.

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

Na biblioteca de tempo de execução de funções Java, use a @EventHubOutput anotação em parâmetros cujo valor seria publicado em Hubs de Eventos. O parâmetro deve ser do tipo OutputBinding<T> , onde T é um POJO ou qualquer tipo Java nativo.

Atributos

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

Use o [EventHubOutputAttribute] para definir uma ligação de saída para um hub de eventos, que suporta as 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.
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 usada no código da função que representa o evento.
event_hub_name o nome do centro 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. Para saber mais, 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 EventHubOutput em parâmetros cujo valor seria publicado em Hubs de Eventos. As seguintes configurações são suportadas na anotação:

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 output.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.
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. Para saber mais, consulte Conexões.

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

function.json propriedade Description
type Deve ser definido como eventHub.
direção Deve ser definido como out. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
Designação O nome da variável usada no código da função que representa o evento.
eventHubName Funções 2.x e superiores. 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.
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. Para saber mais, consulte Conexões.

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

Utilização

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 escreva um único evento, a associação de saída dos Hubs de Eventos pode ser vinculada 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 Um objeto que representa o evento. Functions tenta serializar um tipo de objeto CLR (POCO) simples em dados JSON.

Quando você deseja que a função escreva vários eventos, a ligação de saída dos Hubs de Eventos pode se vincular aos seguintes tipos:

Tipo Description
T[] onde T é um dos tipos de evento único Uma matriz que contém vários eventos. Cada entrada representa um evento.

Para outros cenários de saída, crie e use tipos de Microsoft.Azure.EventHubs diretamente.

Há duas opções para enviar uma mensagem de Hubs de Eventos de uma função usando a anotação EventHubOutput :

  • Valor de retorno: Ao aplicar a anotação à própria função, o valor de retorno da função é mantido como uma mensagem de Hubs de Eventos.

  • Imperativo: Para definir explicitamente o valor da mensagem, aplique a anotação a um parâmetro específico do tipo OutputBinding<T>, onde T é um POJO ou qualquer tipo Java nativo. Com essa configuração, passar um valor para o setValue método persiste o valor como uma mensagem de Hubs de Eventos.

Exemplos completos do PowerShell estão pendentes.

Acesse a mensagem de saída retornando o valor diretamente ou usando context.extraOutputs.set().

Há duas opções para enviar uma mensagem de Hubs de Eventos de uma função:

  • Valor de retorno: defina a name propriedade em function.json como $return. Com essa configuração, o valor de retorno da função é mantido como uma mensagem de Hubs de Eventos.

  • Imperativo: Passe um valor para o método set do parâmetro declarado como um tipo out . O valor passado para set é persistido como uma mensagem dos Hubs de Eventos.

Ligações

A connection propriedade é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar aos Hubs de Eventos. Pode especificar:

  • O nome de uma configuração de aplicativo que contém uma cadeia de conexão
  • O nome de um prefixo compartilhado para várias configurações de aplicativo, definindo em conjunto uma conexão baseada em identidade.

Se o valor configurado for uma correspondência exata para uma única configuração e uma correspondência de prefixo para outras configurações, a correspondência exata será usada.

Connection string

Obtenha essa cadeia de conexão clicando no botão Informações de Conexão para o namespace, não no hub de eventos em si. A cadeia de conexão deve ser para um namespace de Hubs de Eventos, não para o hub de eventos em si.

Quando usada para gatilhos, a cadeia de conexão deve ter pelo menos permissões de "leitura" para ativar a função. Quando usada para ligações de saída, a cadeia de conexão deve ter permissões de "envio" para enviar mensagens para o fluxo de eventos.

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.

Conexões baseadas em identidade

Se você estiver usando a versão 5.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, você pode fazer com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, você definiria as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e vinculação.

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

Property Modelo de variável de ambiente Description Valor de exemplo
Namespace totalmente qualificado <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O namespace Hubs de Eventos totalmente qualificado. myeventhubns.servicebus.windows.net

Propriedades adicionais podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

Nota

Ao usar a Configuração do Aplicativo do Azure ou o Cofre da Chave para fornecer configurações para conexões de Identidade Gerenciada, os nomes de configuração devem usar um separador de chave válido, como : ou / no lugar do para garantir que os __ nomes sejam resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

Você precisará criar uma atribuição de função que forneça acesso ao seu hub de eventos em tempo de execução. O escopo da atribuição de função pode ser para um namespace de Hubs de Eventos ou para o próprio hub de eventos. Funções de gestão como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão Hubs de Eventos em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funções internas
Acionador Recetor de Dados dos Hubs de Eventos do Azure, Proprietário de Dados dos Hubs de Eventos do Azure
Vinculação de saída Remetente de Dados dos Hubs de Eventos do Azure

Exceções e códigos de devolução

Enlace Referência
Hubs de Eventos Guia de Operações

Próximos passos