Connector trigger for Funções do Azure (Preview)

Use o gatilho Connector para executar uma função quando ocorre um evento num serviço como Office 365, SharePoint, Dataverse, SMTP, Salesforce e muitos mais. O gatilho recebe eventos de um conector gerido no Azure Connector Namespace. Para explorar os conectores geridos disponíveis, consulte a referência de conectores.

Para informações sobre a instalação da extensão, tipos de binding suportados, autenticação de callback e configuração em toda a aplicação, consulte a visão geral da extensão Connector.

Importante

O gatilho do Conector está atualmente em pré-visualização pública. Funcionalidades, nomes de configuração e conectores suportados podem mudar antes da disponibilidade geral (GA). A utilização desta funcionalidade está sujeita aos Termos Suplementares de Utilização para Prévias do Microsoft Azure.

Note

O disparador Connector não é atualmente suportado para esta linguagem.

Examples

Os exemplos Office 365 Outlook e SharePoint Online usam cargas úteis fortemente tipadas do SDK Azure Connectors. Para operações de conector que ainda não têm cargas úteis fortemente tipadas, vincule para string receber a carga útil JSON bruta. Estes exemplos registam intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo Connector. Substitua o registo pela lógica de processamento da sua aplicação.

Office 365 Outlook

O exemplo seguinte executa-se quando um novo email chega à caixa de correio Office 365 Outlook configurada:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.Office365.Models;

namespace Office365App;

public class O365Functions
{
    private readonly ILogger<O365Functions> _logger;

    public O365Functions(ILogger<O365Functions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger] Office365OnNewEmailTriggerPayload payload)
    {
        var messageCount = payload.Body?.Value?.Count ?? 0;
        _logger.LogInformation(
            "Received {MessageCount} new email message(s).",
            messageCount);
    }
}

O Office365OnNewEmailTriggerPayload tipo é definido no Azure.Connectors.Sdk.Office365.Models namespace.

Para o exemplo completo de código, incluindo infraestrutura e registo de triggers, veja Office 365 Outlook triggers para .NET.

SharePoint Online

O exemplo seguinte executa-se quando um ficheiro é criado na biblioteca de documentos SharePoint Online configurada:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.SharePointOnline.Models;

namespace SharePointApp;

public class SharePointFunctions
{
    private readonly ILogger<SharePointFunctions> _logger;

    public SharePointFunctions(ILogger<SharePointFunctions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger] SharePointOnlineOnNewFileItemsTriggerPayload payload)
    {
        var fileCount = payload.Body?.Value?.Count ?? 0;
        _logger.LogInformation(
            "Received {FileCount} new SharePoint file(s).",
            fileCount);
    }
}

O SharePointOnlineOnNewFileItemsTriggerPayload tipo é definido no Azure.Connectors.Sdk.SharePointOnline.Models namespace.

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, consulte SharePoint Online gatilhos para .NET.

Conector sem uma carga útil fortemente tipada

Alguns eventos de conector ainda não têm uma carga útil .NET fortemente tipada. O exemplo seguinte executa-se quando uma nova mensagem é adicionada a um chat ou canal do Microsoft Teams e vincula o payload astring:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;

namespace TeamsApp;

public class TeamsFunctions
{
    private readonly ILogger<TeamsFunctions> _logger;

    public TeamsFunctions(ILogger<TeamsFunctions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage([ConnectorTrigger] string payload)
    {
        _logger.LogInformation("Received a new Teams message: {Payload}", payload);
    }
}

Para identificar operações de conectores que ainda não têm payloads fortemente tipados, veja Operations to Funções do Azure signature mapeping.

Attributes

Numa aplicação worker isolada .NET, aplique [ConnectorTrigger] ao parâmetro de função que recebe a carga útil do evento:

[Function("OnConnectorEvent")]
public void Run([ConnectorTrigger] string payload)
{
    // Process the raw JSON payload.
}

O ConnectorTrigger atributo não tem propriedades configuráveis. Configure o conector, operação, parâmetros de operação, função de destino e autenticação de callback na configuração do trigger no Azure Connector Namespace.

Examples

A extensão do conector Node.js fornece contextos tipados para as operações Office 365 Outlook, SharePoint Online e Microsoft Teams apresentadas nesta secção. Estes exemplos registam intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo Connector. Substitua o registo pela lógica de processamento da sua aplicação.

Office 365 Outlook

O exemplo seguinte executa-se quando um novo email chega à caixa de correio Office 365 Outlook configurada:

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    EmailTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

O EmailTriggerContext tipo expõe as mensagens como um array tipado emails .

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, veja Office 365 Outlook gatilhos para o TypeScript.

SharePoint Online

O exemplo seguinte executa-se quando um ficheiro é criado na biblioteca de documentos SharePoint Online configurada:

import { InvocationContext } from '@azure/functions';
import {
    connectors,
    FileTriggerContext,
} from '@azure/functions-extensions-connectors';

connectors.sharepoint.onNewFile('OnSharepointNewFile', {
    handler: async (
        context: FileTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.files.length} new SharePoint file(s).`,
        );
    },
});

O FileTriggerContext tipo expõe os metadados do ficheiro como um array tipado files .

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, consulte SharePoint Online triggers para TypeScript.

Microsoft Teams

O exemplo seguinte executa-se quando uma nova mensagem é adicionada a um canal do Microsoft Teams:

import { InvocationContext } from '@azure/functions';
import {
    ChannelMessageTriggerContext,
    connectors,
} from '@azure/functions-extensions-connectors';

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    handler: async (
        context: ChannelMessageTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

O ChannelMessageTriggerContext tipo expõe as mensagens como um array tipado messages .

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, veja Microsoft Teams triggers para TypeScript.

Registration

Use a função genérica connectorTrigger para uma operação que não tenha um registo específico do conector:

import { InvocationContext } from '@azure/functions';
import {
    connectorTrigger,
    ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';

connectorTrigger('OnConnectorEvent', {
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

O registo genérico devolve o tipo de item por defeito para unknown. Valide a carga útil antes de aceder a propriedades específicas da operação. Configure o conector, operação, parâmetros de operação, função de destino e autenticação de callback na configuração do trigger no Azure Connector Namespace.

Examples

A extensão do conector Node.js fornece contextos específicos do conector para as operações Office 365 Outlook, SharePoint Online e Microsoft Teams apresentadas nesta secção. Estes exemplos registam intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo Connector. Substitua o registo pela lógica de processamento da sua aplicação.

Office 365 Outlook

O exemplo seguinte executa-se quando um novo email chega à caixa de correio Office 365 Outlook configurada:

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

O contexto do handler expõe as mensagens através do emails array.

SharePoint Online

O exemplo seguinte executa-se quando um ficheiro é criado na biblioteca de documentos SharePoint Online configurada:

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.sharepoint.onNewFile('OnSharepointNewFile', {
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.files.length} new SharePoint file(s).`,
        );
    },
});

O contexto do handler expõe os metadados do ficheiro através do files array.

Microsoft Teams

O exemplo seguinte executa-se quando uma nova mensagem é adicionada a um canal do Microsoft Teams:

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

O contexto do handler expõe as mensagens através do messages array.

Registration

Use a função genérica connectorTrigger para uma operação que não tenha um registo específico do conector:

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    handler: async (context, invocationContext) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

O registo genérico normaliza o envelope de callback, mas não valida a forma específica da carga útil da operação. Valide a carga útil antes de aceder a propriedades específicas da operação. Configure o conector, operação, parâmetros de operação, função de destino e autenticação de callback na configuração do trigger no Azure Connector Namespace.

Examples

O exemplo Office 365 Outlook utiliza uma carga útil fortemente tipada registada pela extensão do conector Python. Os exemplos do SharePoint Online e do Microsoft Teams vinculam-se e str analisam o JSON bruto porque essas operações não têm atualmente conversores Python tipados registados. Estes exemplos registam intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo Connector. Substitua o registo pela lógica de processamento da sua aplicação.

Office 365 Outlook

O exemplo seguinte executa-se quando um novo email chega à caixa de correio Office 365 Outlook configurada:

import logging
from typing import List

import azure.functions as func
import azurefunctions.extensions.connectors.office365 as office365

app = func.FunctionApp()


@app.function_name(name="OnNewEmail")
@app.connector_trigger(arg_name="emails")
def on_new_email(
    emails: List[office365.ClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

O ClientReceiveMessage tipo é fornecido por azurefunctions-extensions-connectors e representa as Office 365 Outlook mensagens do lote.

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, veja Office 365 Outlook gatilhos para Python.

SharePoint Online

O exemplo seguinte executa-se quando um ficheiro é criado na biblioteca de documentos SharePoint Online configurada:

import json
import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(arg_name="payload")
def on_sharepoint_new_file(payload: str) -> None:
    data = json.loads(payload)
    files = data.get("body", {}).get("value", [])
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

Para o exemplo completo de código, incluindo infraestrutura e registo de gatilhos, consulte SharePoint Online triggers para Python.

Conector sem uma carga útil fortemente tipada

O exemplo seguinte executa-se quando uma nova mensagem é adicionada a um canal do Microsoft Teams e vincula o payload astr:

import json
import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnNewChannelMessage")
@app.connector_trigger(arg_name="payload")
def on_new_channel_message(payload: str) -> None:
    data = json.loads(payload)
    messages = data.get("body", {}).get("value", [])
    logging.info(
        "Received %s new Teams message(s).",
        len(messages),
    )

Para identificar operações de conector que ainda não têm payloads Python fortemente tipados, veja Operations to Funções do Azure signature mapeping.

Para o exemplo completo de código, incluindo infraestrutura e registo de triggers, veja Microsoft Teams triggers para Python.

Decorators

Aplique connector_trigger à função que recebe a carga útil do evento:

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(arg_name="payload")
def on_connector_event(payload: str) -> None:
    # Process the raw JSON payload.
    pass

O arg_name valor identifica o parâmetro da função que recebe a carga útil. Configure o conector, operação, parâmetros de operação, função de destino e autenticação de callback na configuração do trigger no Azure Connector Namespace.

Configurar o gatilho

Uma configuração de trigger no Azure Connector Namespace associa um evento de serviço externo ao callback da função de destino.

Valores de configuração de gatilho

Valor de configuração Description
Ligação A ligação gerida autorizada, como Office 365 Outlook ou SharePoint Online.
Nome da operação A operação de disparo do conector, como OnNewEmailV3 ou GetOnNewFileItems.
Parameters Valores exigidos pela operação, como uma pasta do Outlook ou uma biblioteca de sites e documentos do SharePoint.
URL de retorno de chamada O endpoint webhook da extensão Connector para a função de destino. Veja Autenticar callbacks.
Nome da função O nome da função registada no código da sua aplicação.
Authentication A configuração de autenticação usada para chamar a aplicação de funções.

O functionName valor da string de consulta na URL de chamada de retorno da configuração do trigger deve corresponder ao nome da função registada. Os nomes válidos de funções contêm de 1 a 128 letras, números, sublinhados ou hífens.

O nome da operação é definido pelo conector gerido. Escolhes o nome da função no teu código, e a configuração do trigger mapeia a operação para essa função. Os exemplos neste artigo utilizam estes mapeamentos:

Evento de conector Nome da operação Nome da função
Novo Office 365 Outlook email OnNewEmailV3 OnNewEmail
Novo ficheiro SharePoint Online GetOnNewFileItems OnNewFile
Nova mensagem de chat ou canal do Microsoft Teams WebhookNewMessageTrigger OnNewTeamsMessage
Evento de conector Nome da operação Nome da função
Novo Office 365 Outlook email OnNewEmailV3 OnNewEmail
Novo ficheiro SharePoint Online GetOnNewFileItems OnSharepointNewFile
Nova mensagem do canal do Microsoft Teams WebhookNewMessageTrigger OnNewChannelMessage

Criar uma configuração de gatilho

Crie uma configuração de trigger usando o CLI do Azure ou o portal Connector Namespace.

Antes de criar a configuração do trigger, crie uma ligação de conector gerida autorizada no namespace do seu conector e implemente a aplicação de funções que contém a função de destino.

O exemplo seguinte do Bash usa CLI do Azure e jq para criar um gatilho Office 365 Outlook novo email. Substitua os valores provisórios para os seus recursos e ligação:

resourceGroup="<RESOURCE_GROUP>"
namespaceName="<CONNECTOR_NAMESPACE>"
functionAppName="<FUNCTION_APP>"
functionName="OnNewEmail"
triggerName="<TRIGGER_NAME>"
connectionName="<CONNECTION_NAME>"
connectorName="office365"
operationName="OnNewEmailV3"
subscriptionId=$(az account show --query id --output tsv)

connectorKey=$(az functionapp keys list \
    --resource-group "$resourceGroup" \
    --name "$functionAppName" \
    --query "systemKeys.connector_extension" \
    --output tsv)

callbackUrl="https://${functionAppName}.azurewebsites.net/runtime/webhooks/connector?functionName=${functionName}"

notificationFile=$(mktemp)
trap 'rm -f "$notificationFile"' EXIT

jq -n \
    --arg callbackUrl "$callbackUrl" \
    --arg connectorKey "$connectorKey" \
    '{
        callbackUrl: $callbackUrl,
        authentication: {
            type: "QueryString",
            name: "code",
            value: $connectorKey
        }
    }' > "$notificationFile"

az connector-namespace trigger create \
    --resource-group "$resourceGroup" \
    --namespace "$namespaceName" \
    --name "$triggerName" \
    --connection-details "{connectionName:${connectionName},connectorName:${connectorName}}" \
    --operation-name "$operationName" \
    --parameters "[{name:folderPath,value:'Inbox'}]" \
    --notification-details "@$notificationFile" \
    --description "${connectorName} ${operationName} -> ${functionName}" \
    --metadata "{destinationType:functionApp,functionAppName:${functionAppName},functionAppResourceGroup:${resourceGroup},functionAppSubscriptionId:${subscriptionId},functionName:${functionName},recurrenceFrequency:Minute,recurrenceInterval:'5'}"

rm -f "$notificationFile"
trap - EXIT

O --parameters valor é específico para a operação do conector. Neste exemplo, folderPath seleciona a pasta Outlook para monitorizar. O URL de retorno de chamada não contém a chave do sistema. O notificationDetails.authentication objeto adiciona a chave como um segredo de query string quando o Espaço de Nomes do Conector invoca a função.

Utilização

O gatilho liga o corpo do pedido JSON a qualquer um dos tipos de ligação .NET suportados pela extensão.

As operações do conector podem devolver um evento ou um conjunto de eventos. Utilize o modelo de carga útil específica da operação porque a sua forma representa o contrato de resposta para essa operação do conector.

Utilização

O registo genérico recebe um ConnectorTriggerContext<T>. A sua payload propriedade contém o envelope de callback normalizado, items contém os itens do evento e rawPayload preserva o corpo original do pedido. Registos específicos de conectores fornecem arrays tipados nomeados, como emails, files, ou messages.

Para uma operação sem registo específico do conector, o tipo de item é unknownpor defeito . Valide a carga útil antes de aceder a propriedades específicas da operação.

Utilização

O gatilho pode vincular o corpo do pedido a str, dict, ou bytes. Quando azurefunctions-extensions-connectors regista um conversor para a anotação do SDK da função, o trabalhador desserializa o corpo do pedido no tipo de operação suportado.

As operações do conector podem devolver um evento ou um conjunto de eventos. Utilize o tipo ou anotação de coleção identificada para a operação no mapeamento de assinatura da operação.

A extensão aceita HTTP POST e PUT pedidos com o tipo de application/json conteúdo. Um corpo de pedido não vazio deve conter JSON válido. A extensão rejeita corpos de pedido superiores a 10 MB.

Metadata

O disparador Connector atualmente não expõe cabeçalhos de callback ou outros metadados de pedidos como dados de ligação. A extensão define um contrato de dados de ligação vazio, pelo que a função recebe apenas o corpo do pedido JSON num tipo de ligação suportado pela linguagem selecionada.

Passos seguintes

  • Última atualização a