Criar gatilhos e associações

Concluído

Um gatilho define como uma função é invocada e uma função deve ter exatamente um gatilho. Gatilhos têm dados associados, que geralmente são fornecidos como o conteúdo da função.

Vincular a uma função é uma forma de conectar declarativamente outro recurso à função; as ligações podem ser conectadas como ligações de entrada, ligações de saída ou ambas. Dados de associações são fornecidos à função como parâmetros.

Você pode combinar diferentes associações para atender às suas necessidades. Associações são opcionais e uma função pode ter uma ou várias associações de entrada e/ou saída.

Os gatilhos e vinculaçõ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.

Quando você desenvolve suas funções localmente, é necessário levar em consideração os comportamentos de gatilho e vinculação. Para gatilhos HTTP, você pode chamar o ponto de extremidade HTTP no computador local, usando http://localhost/. Para funções não acionadas por HTTP, há várias opções para serem executadas localmente:

• A maneira mais fácil de testar associações durante o desenvolvimento local é usar cadeias de conexão direcionadas aos serviços dinâmicos do Azure. Você pode ter como alvo serviços dinâmicos adicionando as configurações de cadeia de conexão apropriadas na matriz Values no arquivo local.settings.json. Quando você faz isso, as execuções locais durante o teste usam dados de serviço dinâmicos. Por esse motivo, considere configurar serviços separados para uso durante o desenvolvimento e o teste e, em seguida, mude para serviços diferentes durante a produção.
• Para gatilhos baseados em armazenamento, você pode usar o emulador do Azurite local ao testar funções com associações de Armazenamento do Azure (Armazenamento de Filas, Armazenamento de Blobs e Armazenamento de Tabelas), sem precisar se conectar aos serviços de armazenamento remoto.
• Você pode executar manualmente funções de gatilho não HTTP usando pontos de extremidade especiais de administrador. Para obter mais informações, consulte Executar manualmente uma função não acionada por HTTP.

Definições de gatilho e vinculação

Gatilhos e vinculações são definidos de forma diferente dependendo da linguagem de desenvolvimento e do modelo de execução.

Linguagem	Configure gatilhos e vinculações por...
Biblioteca de classes C#	Métodos e parâmetros de decoração com atributos C# (processo de trabalho isolado ou interno)
Java	decorando métodos e parâmetros com anotações Java
JavaScript/TypeScript	Modelo de programação v4: defina entradas/saídas diretamente no código com @azure/functions; v3: configure usando um arquivo function.json por função
Python	Modelo de programação v2: definir entradas/saídas com decoradores; v1: configurar no function.json
PowerShell	Configurar em function.json

Observação

Em modelos modernos (Node.js v4 e Python v2), você cria a configuração de gatilho e associação no código e o runtime gera o function.jsoncorrespondente. Modelos mais antigos (Node.js v3, Python v1, PowerShell) usam function.json diretamente. Você não pode misturar modelos de programação no mesmo aplicativo de funções.

Para linguagens que dependem de function.json (por exemplo, Node.js v3, Python v1 e PowerShell), o portal fornece uma UI para adicionar vinculações na guia Integração. Você também pode editar o arquivo diretamente na guia Código + teste no portal da sua função. Para modelos de primeiro código, como Node.js v4 e Python v2, configure associações no código em seu projeto local; o portal reflete a configuração, mas pode não dar suporte a edições diretas.

No .NET e no Java, o tipo de parâmetro define o tipo de dados para dados de entrada. Por exemplo, use string para associar ao texto de um gatilho de fila, uma matriz de bytes para ler como binário e um tipo personalizado para desserializar para um objeto. Como as funções de biblioteca de classes do .NET e as funções Java não dependem do function.js para definições de associação, elas não podem ser criadas e editadas no portal. A edição do portal C# se baseia no script C#, que usa o function.json vez de atributos.

Para linguagens que são digitadas dinamicamente, como JavaScript (usando o modelo v3) ou PowerShell, use a dataType propriedade no arquivo function.json . Por exemplo, para ler o conteúdo de uma solicitação HTTP em formato binário, defina dataType para binary:

{
    "dataType": "binary",
    "type": "httpTrigger",
    "name": "req",
    "direction": "in"
}

Outras opções para dataType são stream e string.

Direção da vinculação

Todos os gatilhos e vinculações têm uma propriedade de direção no arquivo function.json:

• Para gatilhos, a direção é sempre in
• Associações de entrada e saída usam in e out
• Algumas associações dão suporte a uma direção especial inout. Se você usar inout, somente o Editor avançado estará disponível na guia Integrar no portal.

Quando você usa atributos em uma biblioteca de classes para configurar associações e gatilhos, a direção é fornecida em um construtor de atributo ou inferida do tipo de parâmetro.

Exemplos de gatilho e associação do Azure Functions

Suponha que você queira gravar uma mensagem no Armazenamento de Filas do Azure sempre que uma solicitação HTTP for recebida. Você pode implementar isso com um gatilho HTTP e uma vinculação de saída da Fila de Armazenamento. A abordagem de configuração depende do seu modelo de linguagem e programação.

Aqui está um arquivo function.json herdado para este cenário (aplicável a Node.js v3, Python v1 ou PowerShell).

{
    "disabled": false,
    "bindings": [
        {
            "type": "httpTrigger",
            "direction": "in",
            "name": "req",
            "authLevel": "function",
            "methods": ["get","post"]
        },
                {
                    "type": "queue",
                    "direction": "out",
                    "name": "outqueue",
                    "queueName": "outqueue",
                    "connection": "AzureWebJobsStorage"
                }
  ]
}

O primeiro elemento na bindings matriz é o gatilho HTTP. As propriedades type e direction identificam o gatilho. A name propriedade identifica o parâmetro de função que recebe a solicitação HTTP e methods lista os verbos HTTP com suporte.

O segundo elemento na matriz bindings é a associação de saída da fila de armazenamento. As propriedades type e direction identificam a associação. A propriedade name especifica como a função fornece a nova mensagem de fila, queueName identifica a fila, e connection refere-se às configurações do aplicativo que contêm a cadeia de conexão de armazenamento.

Observação

Desabilitar uma função por meio da disabled propriedade em function.json é um comportamento herdado. Prefira usar a configuração do aplicativo AzureWebJobs.<FunctionName>.Disabled=true.

Exemplo de C# (trabalho isolado)

Este exemplo mostra uma função disparada por HTTP que grava uma mensagem em uma Fila de Armazenamento usando uma associação de saída definida por atributos. Para obter mais informações, consulte o guia de trabalho isolado em C#.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;

public static class HttpToQueue
{
    [Function("HttpToQueue")]
    public static MultiResponse Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
    {
        var message = "Processed request";
        return new MultiResponse
        {
            Messages = new[] { message },
            HttpResponse = req.CreateResponse(System.Net.HttpStatusCode.OK)
        };
    }
}

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

exemplo de Node.js (modelo de programação v4)

No modelo de programação de Node.js v4, você configura entradas e saídas no código usando @azure/functions. Para obter mais informações, consulte Node.js guia do desenvolvedor (v4).

import { app, output } from "@azure/functions";

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

app.http("HttpToQueue", {
  methods: ["GET", "POST"],
  authLevel: "function",
  extraOutputs: [queueOutput],
  handler: async (request, context) => {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body || "Processed request");
    return { status: 200, body: "Queued" };
  }
});

Exemplo de Python (modelo de programação v2)

No modelo de programação do Python v2, você usa decoradores para definir associações. O runtime gera function.json para você. Visite o guia do desenvolvedor do Python para obter mais informações.

import azure.functions as func

app = func.FunctionApp()

@app.route(route="HttpToQueue", auth_level=func.AuthLevel.FUNCTION)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
def HttpToQueue(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    body = req.get_body().decode("utf-8") if req.get_body() else "Processed request"
    msg.set(body)
    return func.HttpResponse("Queued", status_code=200)

Observação

Em Node.js v4 e Python v2, o runtime gera function.json a partir do seu código. Evite editar function.json diretamente no portal para esses modelos; fazer alterações no código e republicar.