Associação de saída dos Hubs de Eventos do Azure para 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 de saída para os Hubs de Eventos.

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

Use a associação de saída dos Hubs de Eventos para gravar eventos em um fluxo de eventos. É necessário ter permissão de envio para que um hub de eventos grave eventos nele.

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

Importante

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

O Azure Functions dá suporte a dois modelos de programação para Python. A maneira como você define suas associações depende do modelo de programação escolhido.

O modelo de programação v2 do Python permite que você defina associações usando decoradores diretamente no código de função do Python. Para saber mais, confira o Guia do desenvolvedor do Python.

Este artigo dá suporte a 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 retornado do método como a 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 disparada pelo 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 disparada pelo 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 associação do gatilho do hub de eventos e uma função do Python que usa a associação. A função grava uma mensagem em um hub de eventos. O exemplo depende do modelo de programação v1 ou v2 do Python que você usa.

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 evento a seguir mostrará uma função Java que grava uma mensagem contendo o horário atual de 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 runtime de funções Java, use a anotação @EventHubOutput em parâmetros cujo valor seria publicado nos Hubs de Eventos. O parâmetro deverá ser do tipo OutputBinding<T>, em que T é um POJO ou um tipo Java nativo.

Atributos

As bibliotecas C# em processo e de processo de trabalho isolado usam atributos para configurar a associaçã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 associação de saída para um hub de eventos, que permite as propriedades a seguir.

Parâmetros Descrição
EventHubName O nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.
Conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Para saber mais, confira Conexões.

Decoradores

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

Para funções Python v2 definidas usando um decorador, essas propriedades são suportadas para event_hub_output:

Propriedade DESCRIÇÃO
arg_name É o nome da variável usada no código da função que representa o evento.
event_hub_name o nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Para saber mais, confira Conexões.

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

Anotações

Na biblioteca de runtime de funções Java, use a anotação EventHubOutput em parâmetros cujo valor seria publicado nos Hubs de Eventos. As configurações a seguir são permitidas na anotação:

Configuração

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

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

Propriedade Descrição
eventHubName O nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Para saber mais, confira Conexões.

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json, que difere pela versão do runtime.

Propriedade function.json Descrição
tipo Deve ser definido como eventHub.
direction Deve ser definido como out. Esse parâmetro é definido automaticamente quando você cria a associação no portal do Azure.
name É o nome da variável usada no código da função que representa o evento.
eventHubName Functions 2.x e posterior. O nome do hub de eventos. Quando o nome do hub de eventos também estiver presente na cadeia de conexão, esse valor substitui essa propriedade em runtime.
connection O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos Hubs de Eventos. Para saber mais, confira Conexões.

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

Uso

Os tipos específicos com suporte pela associação de saída do Hubs de Eventos dependem da versão de runtime do Functions, da versão do pacote de extensão e da modalidade de C# usada.

Quando você quiser que a função escreva um único evento, a associação de saída dos Hubs de Eventos pode ser associada aos seguintes tipos:

Type Descrição
string O evento como uma cadeia de caracteres. Use quando a mensagem for de texto simples.
byte[] Os bytes do evento.
Tipos serializáveis JSON Um objeto que representa o evento. O Functions tenta serializar um tipo de objeto CLR básico (POCO) em dados JSON.

Quando você quiser que a função escreva vários eventos, a associação de saída dos Hubs de Eventos pode ser associada aos seguintes tipos:

Type Descrição
T[] em que 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 diretamente do Microsoft.Azure.EventHubs.

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

  • Valor retornado: ao aplicar a anotação à própria função, o valor retornado da função será mantido como uma mensagem dos Hubs de Eventos.

  • Imperativo: para definir o valor da mensagem de modo explícito, aplique a anotação a um parâmetro específico do tipo OutputBinding<T>, em que T será um POJO ou um tipo de Java nativo. Com essa configuração, passar um valor para o método setValue manterá o valor como uma mensagem dos 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 gerar uma mensagem dos Hubs de Eventos de uma função:

  • Valor retornado: definir a propriedade name no function.json para $return. Com essa configuração, o valor retornado da função será mantido como uma mensagem dos Hubs de Eventos.

  • Imperativo: passe um valor para definir o método do parâmetro declarado como um tipo de Saída. O valor passado para set será mantido como uma mensagem dos Hubs de Eventos.

conexões

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

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

Cadeia de conexão

Para obter essa cadeia de conexão, clique no botão Informações de Conexão do namespace, não no próprio hub de eventos. A cadeia de conexão deve ser para um namespace dos Hubs de Eventos, não para o próprio hub de eventos.

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 associações de saída, a cadeia de conexão deve ter permissões de "enviar" 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 que corresponda ao valor especificado pela propriedade connection da configuração de associação.

Conexões baseadas em identidade

Caso esteja usando a versão 5.x ou superior da extensão, em vez de usar uma cadeia de conexão com um segredo, faça com que o aplicativo use uma identidade do Microsoft Entra. Para fazer isso, defina as configurações em um prefixo comum que mapeia para a propriedade connection na configuração de gatilho e de associação.

Nesse modo, a extensão exige as seguintes propriedades:

Propriedade Modelo de variável de ambiente Descrição Valor de exemplo
Namespace totalmente qualificado <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace O namespace totalmente qualificado dos Hubs de Eventos. myeventhubns.servicebus.windows.net

É possível definir propriedades adicionais para personalizar a conexão. Confira Propriedades comuns para conexões baseadas em identidade.

Observação

Ao usar a Configuração de Aplicativos do Azure ou o Key Vault 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 de __ para garantir que os nomes sejam resolvidos corretamente.

Por exemplo, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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

Conceder permissão para a 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 será necessário atribuir uma função no Azure RBAC, usando as funções internas ou as personalizadas que fornecem essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

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

Tipo de associação Exemplo de funções internas
Gatilho Receptor de Dados dos Hubs de Eventos do Azure, Proprietário dos Dados dos Hubs de Eventos do Azure
Associação de saída Remetente de dados dos Hubs de Eventos do Azure

Exceções e códigos de retorno

Associação Referência
Hubs de Eventos Guia de Operações

Próximas etapas