Azure Functions gatilhos e associações

Neste artigo, você aprenderá os conceitos de alto nível em torno de gatilhos e associações para funções.

Os gatilhos fazem com que as funções sejam executadas. Um gatilho define como uma função é invocada e uma função deve ter exatamente um gatilho. Gatilhos também podem passar dados para sua função, como você faria com chamadas de método.

A associação a uma função é uma maneira de conectar declarativamente suas funções a outros recursos. As associações passam dados para sua função (uma associação de entrada) ou permitem que você escreva dados de sua função (uma associação de saída) usando parâmetros de associação. O gatilho de função é basicamente um tipo especial de vinculação de entrada.

Você pode misturar e combinar associações para atender ao cenário específico da função. As associações são opcionais e uma função pode ter uma ou várias associações de entrada e/ou saída.

Gatilhos e associações permitem evitar codificar o acesso a outros serviços. Sua função recebe dados (por exemplo, o conteúdo de uma mensagem da fila) em parâmetros de função. Você envia dados (por exemplo, para criar uma mensagem da fila) usando o valor retornado da função.

Considere os seguintes exemplos de como você pode implementar funções:

Cenário de exemplo Gatilho Associação de entrada Associação de saída
Uma nova mensagem de fila chega, o que executa uma função para gravar em outra fila. Fila* Nenhum Fila*
Um trabalho agendado lê o conteúdo do Armazenamento de Blobs do Azure e cria um novo documento no Azure Cosmos DB. Timer Armazenamento de Blobs Azure Cosmos DB
Grade de Eventos do Azure é usado para ler uma imagem de Armazenamento de Blobs e um documento de Azure Cosmos DB para enviar um email. Grade de Eventos Armazenamento de Blobs e Azure Cosmos DB SendGrid

* Representa filas diferentes.

Esses exemplos não devem ser exaustivos, mas ilustram como você pode usar gatilhos e associações juntos. Para obter um conjunto mais abrangente de cenários, consulte os cenários do Azure Functions.

Dica

Azure Functions não exige que você use associações de entrada e saída para se conectar aos serviços de Azure. Você sempre pode criar um cliente SDK do Azure em seu código e usá-lo para suas transferências de dados. Para obter mais informações, confira Conectar aos serviços.

Definições de associação e gatilho

O exemplo a seguir mostra uma função disparada por HTTP com uma associação de saída que grava uma mensagem em uma fila de Armazenamento do Azure.

Para funções de biblioteca de classes C#, você configura gatilhos e associações decorando métodos e parâmetros com atributos C#. O atributo específico que você aplica pode depender do modelo de runtime do C#:

Você define o gatilho HTTP (HttpTrigger) no Run método para uma função chamada HttpExample que retorna um MultiResponse objeto:

[Function("HttpExample")]
public MultiResponse Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req)

Este exemplo mostra a definição de MultiResponse objeto. A definição do objeto retorna HttpResponse à solicitação HTTP e grava uma mensagem em uma fila de armazenamento usando uma associação QueueOutput:

public class MultiResponse
{
    [QueueOutput("outqueue", Connection = "AzureWebJobsStorage")]
    public string[] Messages { get; set; }
    public IActionResult HttpResponse { get; set; }
}

Para obter mais informações, consulte o guia em C# para modelos de trabalho isolados.

As funções de script C# herdadas usam um function.json arquivo de definição. Para obter mais informações, consulte a referência de desenvolvedor de script Azure Functions C# (.csx).

Para Java funções, você configura gatilhos e associações anotando métodos e parâmetros específicos. Você define esse gatilho HTTP (@HttpTrigger) no run método para uma função chamada HttpExample. A função grava em uma fila de armazenamento chamada outqueue definida no parâmetro @QueueOutput pela anotação msg.

@FunctionName("HttpExample")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) 
        HttpRequestMessage<Optional<String>> request, 
        @QueueOutput(name = "msg", queueName = "outqueue", 
        connection = "AzureWebJobsStorage") OutputBinding<String> msg, 
        final ExecutionContext context) {
    context.getLogger().info("Java HTTP trigger processed a request.");

Para obter mais informações, consulte o Java guia do desenvolvedor.

A maneira como você define gatilhos e associações para funções de Node.js depende da versão específica do Node.js para Azure Functions:

Em Node.js para Azure Functions versão 4, você configura gatilhos e associações usando objetos exportados do módulo @azure/functions. Para saber mais, confira o Guia de desenvolvedores do Node.js.

O método do http objeto exportado app define um gatilho HTTP. O método storageQueue em output define uma associação de saída neste gatilho.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

O método do http objeto exportado app define um gatilho HTTP. O método storageQueue em output define uma associação de saída neste gatilho.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Este arquivo function.json de exemplo define a função:

    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Para obter mais informações, consulte o Guia de desenvolvedor do PowerShell.

A forma como você define a função depende da versão do Python para Azure Functions:

Em Python para Azure Functions versão 2, você define a função diretamente no código usando decoradores:

app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.route(route="HttpExample")
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
def HttpExample(req: func.HttpRequest, msg: func.Out[func.QueueMessage]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

Considerações de vinculação

  • Nem todos os serviços dão suporte a vinculações de entrada e de saída. Consulte sua extensão de associação específica para obter exemplos de código específicos para associações.

  • Os gatilhos e as associações são definidos de forma diferente, dependendo da linguagem de desenvolvimento. Selecione seu idioma na parte superior deste artigo.

  • Os nomes de gatilho e associação são limitados a caracteres alfanuméricos e _, o sublinhado.

Tarefa para adicionar associações a uma função

Você pode conectar a função a outros serviços usando associações de entrada ou saída. Adicione uma associação adicionando suas definições específicas à função. Para saber como, consulte Adicionar associações a uma função existente no Azure Functions.

Azure Functions suporta múltiplas conexões, que você deve configurar corretamente. Por exemplo, uma função pode ler dados de uma fila (vinculação de entrada) e gravar dados em um banco de dados (vinculação de saída) ao mesmo tempo.

Associações com suporte

Esta tabela mostra os gatilhos e bindings disponíveis no Azure Functions:1

Tipo Gatilho Entrada Saída
Armazenamento de Blobs ✔ ✔ ✔
Azure Cosmos DB ✔ ✔ ✔
Azure Data Explorer ✔ ✔
SQL Azure ✔ ✔ ✔
Grade de Eventos ✔ ✔
Hubs de Eventos ✔ ✔
HTTP e webhooks ✔ ✔
Hub IoT ✔
Kafka2 ✔ ✔
Protocolo de contexto de modelo ✔
Armazenamento de Filas ✔ ✔
Redis ✔ ✔ ✔
RabbitMQ2 ✔ ✔
SendGrid ✔
Barramento de Serviço ✔ ✔
Serviço Azure SignalR ✔ ✔ ✔
Armazenamento de Tabelas ✔ ✔
Timer ✔
Twilio ✔
Conector gerenciado ✔
  1. Registre todas as associações, exceto HTTP e temporizador. Consulte Registrar extensões de bindings do Azure Functions.
  2. Não há suporte para gatilhos no Plano de Consumo. Este tipo de associação requer gatilhos controlados pelo runtime.

Para obter informações sobre quais associações estão na visualização ou são aprovadas para o uso de produção, consulte Idiomas com suporte.

Há suporte para versões específicas de extensões de associação somente enquanto o SDK do serviço subjacente é suportado. As alterações no suporte na versão do SDK do serviço subjacente afetam o suporte para a extensão de consumo.

Conectores gerenciados

Conectores gerenciados no Azure Connector Namespace expandem os serviços disponíveis por meio de associações com suporte. Você pode usar gatilhos de conector e ações do SDK para integrar-se a serviços como Microsoft 365, Teams e SharePoint, enquanto o namespace do conector gerencia webhooks, autenticação e novas tentativas. Para saber mais, veja Usar conectores gerenciados no Azure Functions.

Tipos de SDK

Azure Functions extensões de associação usam SDKs de serviço Azure para se conectar a serviços de Azure. Os tipos específicos de SDK usados por associações podem afetar como você trabalha com os dados em suas funções. Algumas associações dão suporte a tipos específicos do SDK que fornecem funcionalidades mais avançadas e melhor integração com o serviço, enquanto outras usam tipos mais genéricos, como cadeias de caracteres ou matrizes de bytes. Quando disponível, o uso de tipos específicos do SDK pode fornecer benefícios como melhor segurança de tipo, manipulação de dados mais fácil e acesso a recursos específicos do serviço.

Esta tabela indica extensões de associação que atualmente dão suporte a tipos de SDK:

Extension Tipos Nível de suporte
Armazenamento de Blobs do Azure BlobClient
BlobContainerClient
BlockBlobClient
PageBlobClient
AppendBlobClient
Gatilho: GA
Entrada: GA
Azure Cosmos DB CosmosClient
Database
Container
Entrada: GA
Grid de Eventos do Azure CloudEvent
EventGridEvent
Gatilho: GA
Hubs de eventos do Azure EventData
EventHubProducerClient
Gatilho: GA
Armazenamento de Filas do Azure QueueClient
QueueMessage
Gatilho: GA
Barramento de Serviço do Azure ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage
Gatilho: GA
Armazenamento de Tabelas do Azure TableClient
TableEntity
Entrada: GA

Considerações sobre tipos de SDK:

  • Ao usar expressões de associação que dependem de dados de gatilho, não é possível usar os tipos de SDK do próprio gatilho.
  • Para cenários de saída em que você pode usar um tipo de SDK, crie e trabalhe com clientes do SDK diretamente em vez de usar uma associação de saída.
  • O gatilho do Azure Cosmos DB utiliza o feed de alterações do Azure Cosmos DB e expõe os itens desse feed como tipos que podem ser serializados em JSON. Como resultado, não há suporte para tipos de SDK para esse disparador.

Para obter mais informações, consulte os tipos de SDK no guia do desenvolvedor em C#.

Extension Tipos Nível de suporte Exemplos
Armazenamento de Blobs do Azure BlobClient
ContainerClient
StorageStreamDownloader
Gatilho: GA
Entrada: GA
Quickstart
BlobClient
ContainerClient
StorageStreamDownloader
Azure Cosmos DB CosmosClient
DatabaseProxy
ContainerProxy
Entrada: visualização Quickstart
ContainerProxy
CosmosClient
DatabaseProxy
Hubs de eventos do Azure EventData Gatilho: versão preliminar Quickstart
EventData
Barramento de Serviço do Azure ServiceBusReceivedMessage Gatilho: versão preliminar Quickstart
ServiceBusReceivedMessage

Considerações sobre tipos de SDK:

  • Para cenários de saída em que você pode usar um tipo de SDK, crie e trabalhe com clientes do SDK diretamente em vez de usar uma associação de saída.
  • O gatilho do Azure Cosmos DB utiliza o feed de alterações do Azure Cosmos DB e expõe os itens desse feed como tipos que podem ser serializados em JSON. Como resultado, não há suporte para tipos de SDK para esse disparador.

Os tipos de SDK só têm suporte ao usar o modelo de programação Python v2. Para obter mais informações, consulte SDK type bindings no guia do desenvolvedor do Python.

Extension Tipos Nível de suporte
Armazenamento de Blobs do Azure BlobClient
ContainerClient
ReadableStream
Preview
Barramento de Serviço do Azure ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage
Preview

Os tipos de SDK só têm suporte ao usar o modelo de programação Node v4. Para obter mais informações, consulte os tipos de SDK no guia do desenvolvedor do Node.js.

Extension Tipos Nível de suporte
Armazenamento de Blobs do Azure BlobClient
BlobContainerClient
Preview

Para obter mais informações, consulte SDK types no guia do desenvolvedor Java.

Importante

Atualmente, não há suporte para tipos de SDK para aplicativos do PowerShell.

O Go oferece suporte à injeção de clientes do SDK para gatilhos que fornecem clientes do SDK do Azure. Durante a visão preliminar pública, os gatilhos do Armazenamento de Blobs podem receber diretamente no manipulador um SDK do Azure *blob.Client autenticado.

Extension Tipos Nível de suporte
Armazenamento de Blobs do Azure *blob.Client Preview

Para obter mais informações, consulte acionadores de extensão na referência do desenvolvedor do Go.

Associações de agente

Importante

As vinculações de agente para aplicativos de função do Python estão em versão prévia. Recursos, nomes de pacotes e configurações podem mudar antes da disponibilidade geral.

As associações de agente permitem injetar um objeto Agent em uma função Python, mantendo os gatilhos, as associações e a lógica do aplicativo padrão do Azure Functions. Use vinculações de agentes quando parte do fluxo de trabalho de uma função se beneficia do raciocínio agente, mas seu código de função deve permanecer no controle da execução.

As associações de agente também dão suporte a orquestrações do Durable Functions. A API segura context.call_agent() para replay executa operações de agente em uma atividade para que a reprodução de orquestração permaneça determinística.

Vinculações de agentes estão disponíveis para o modelo de programação Python v2. Para mais informações, veja Vinculações de agentes para aplicativos de funções Python.

Exemplos de código para associações

Use a tabela a seguir para encontrar mais exemplos de tipos de vinculação específicos, que mostram como trabalhar com vinculações nas funções. Primeiro, escolha a guia da linguagem que corresponde ao seu projeto.

O código de associação para C# depende do modelo de processo específico.

Serviço Exemplos Exemplos
Armazenamento de Blobs Trigger
Entrada
Output
Link
Azure Cosmos DB Trigger
Entrada
Output
Link
Azure Data Explorer Entrada
Output
Link
SQL do Azure Trigger
Entrada
Output
Link
Grade de Eventos Trigger
Output
Link
Hubs de Eventos Trigger
Output
Hub IoT Trigger
Output
HTTP Trigger Link
Protocolo de contexto de modelo Gatilho da ferramenta
Acionador de Recurso
Prompt Trigger
Link
Armazenamento de Filas Trigger
Output
Link
RabbitMQ Trigger
Output
SendGrid Output
Barramento de Serviço Trigger
Output
Link
Serviço do Azure SignalR Trigger
Entrada
Output
Armazenamento de Tabelas Entrada
Output
Timer Trigger Link
Twilio Output Link
Conectores gerenciados Trigger Link
Serviço Exemplos Exemplos
Armazenamento de Blobs Trigger
Entrada
Output
Link
Azure Cosmos DB Trigger
Entrada
Output
Link
Azure Data Explorer Entrada
Output
Link
SQL do Azure Trigger
Entrada
Output
Grade de Eventos Trigger
Output
Link
Hubs de Eventos Trigger
Output
Hub IoT Trigger
Output
HTTP Trigger Link
Protocolo de contexto de modelo Gatilho da ferramenta
Acionador de Recurso
Prompt Trigger
Link
Armazenamento de Filas Trigger
Output
Link
RabbitMQ Trigger
Output
SendGrid Output
Barramento de Serviço Trigger
Output
Link
Serviço do Azure SignalR Trigger
Entrada
Output
Armazenamento de Tabelas Entrada
Output
Timer Trigger Link
Twilio Output
Serviço Exemplos Exemplos
Armazenamento de Blobs Trigger
Entrada
Output
Link
Azure Cosmos DB Trigger
Entrada
Output
Link
Azure Data Explorer Entrada
Output
SQL do Azure Trigger
Entrada
Output
Link
Grade de Eventos Trigger
Output
Hubs de Eventos Trigger
Output
Hub IoT Trigger
Output
HTTP Trigger Link
Protocolo de contexto de modelo Gatilho da ferramenta
Acionador de Recurso
Prompt Trigger
Link
Armazenamento de Filas Trigger
Output
Link
RabbitMQ Trigger
Output
SendGrid Output
Barramento de Serviço Trigger
Output
Link
Serviço do Azure SignalR Trigger
Entrada
Output
Armazenamento de Tabelas Entrada
Output
Timer Trigger
Twilio Output
Conectores gerenciados Trigger Link
Serviço Exemplos Exemplos
Armazenamento de Blobs Trigger
Entrada
Output
Azure Cosmos DB Trigger
Entrada
Output
SQL do Azure Trigger
Entrada
Output
Grade de Eventos Trigger
Output
Hubs de Eventos Trigger
Output
Hub IoT Trigger
Output
HTTP Trigger Link
Armazenamento de Filas Trigger
Output
RabbitMQ Trigger
Output
SendGrid Output
Barramento de Serviço Trigger
Output
Serviço do Azure SignalR Trigger
Entrada
Output
Armazenamento de Tabelas Entrada
Output
Timer Trigger
Twilio Output

O código de bindings para Python depende da versão do modelo Python.

Serviço Exemplos Exemplos
Armazenamento de Blobs Trigger
Entrada
Output
Link
Azure Cosmos DB Trigger
Entrada
Output
Link
Azure Data Explorer Entrada
Output
SQL do Azure Trigger
Entrada
Output
Link
Grade de Eventos Trigger
Output
Hubs de Eventos Trigger
Output
Hub IoT Trigger
Output
HTTP Trigger Link
Protocolo de contexto de modelo Gatilho da ferramenta
Acionador de Recurso
Prompt Trigger
Link
Armazenamento de Filas Trigger
Output
RabbitMQ Trigger
Output
SendGrid Output
Barramento de Serviço Trigger
Output
Link
Serviço do Azure SignalR Trigger
Entrada
Output
Armazenamento de Tabelas Entrada
Output
Timer Trigger
Twilio Output
Conectores gerenciados Trigger Link

Associações personalizadas

Você pode criar associações de entrada e saída personalizadas. Você deve criar bindings em .NET, mas pode consumi-los de qualquer linguagem suportada. Para obter mais informações sobre como criar associações personalizadas, consulte Criando associações de entrada e saída personalizadas.