Connector Trigger para Azure Functions

Azure Functions fornece extensões de gatilho e vinculação que se integram a vários serviços, principalmente serviços Azure. A Extensão Connector amplia essas integrações para uma seleção muito mais ampla de serviços, incluindo sistemas de negócios e plataformas de dados.

Por exemplo, use o Gatilho do Conector para executar uma função quando um novo e-mail chegar em Office 365 Outlook, um arquivo for criado em SharePoint ou um registro for alterado no Salesforce. O gatilho recebe eventos de um conector gerenciado no Azure Connector Namespace. Para explorar os conectores gerenciados disponíveis, veja a referência de conectores.

Para mais informações sobre conectores gerenciados, quando utilizá-los e disponibilidade de recursos, consulte Use managed connectors in Azure Functions.

Note

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

Modos de entrega

Conectores gerenciados suportam dois modos de entrega:

  • Polling: O host de Funções se conecta de saída ao Namespace do Conector para receber eventos. Defina deliveryMode: 'Poll', e forneça connection e triggerConfigName nas opções de registro.
  • Webhook: O Namespace do Conector envia eventos para o endpoint de callback da extensão. Webhook é o padrão quando você omite deliveryModeo .

Ambos os modos suportam ajudantes nomeados, como connectors.office365.onNewEmail e o ajudante genérico connectorTrigger . Para ajuda na escolha de um modo, consulte Escolher um modo de entrega.

Introdução

Siga o caminho de configuração para o seu modo de entrega:

  1. Instale os pacotes Node.js e configure o pacote de extensões.
  2. Crie ou reutilize um namespace e uma conexão, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint da votação.
  4. Configure credenciais do chamador, acesso à conexão e configurações locais ou implantadas.
  5. Use um exemplo de pesquisa abaixo, comparando seus connection valores triggerConfigName com suas configurações.

A pesquisa não requer um endpoint público de callback ou chave de sistema. Para entrega por webhook, a função de destino e o endpoint de callback devem estar prontos antes de você criar a configuração do gatilho.

Modos de entrega

Conectores gerenciados suportam dois modos de entrega:

  • Polling: O host de Funções se conecta de saída ao Namespace do Conector para receber eventos. Defina delivery_mode=func.DeliveryMode.POLL, e forneça connection e trigger_config_name em @app.connector_trigger.
  • Webhook: O Namespace do Conector envia eventos para o endpoint de callback da extensão. Webhook é o padrão quando você omite delivery_mode o @app.connector_trigger.

Para ajuda na escolha de um modo, consulte Escolher um modo de entrega.

Introdução

Siga o caminho de configuração para o seu modo de entrega:

  1. Instale os pacotes Python e configure o pacote de extensões.
  2. Crie ou reutilize um namespace e uma conexão, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint da votação.
  4. Configure credenciais do chamador, acesso à conexão e configurações locais ou implantadas.
  5. Use um exemplo de pesquisa abaixo, comparando seus connection valores trigger_config_name com suas configurações.

A pesquisa não requer um endpoint público de callback ou chave de sistema. Para entrega por webhook, a função de destino e o endpoint de callback devem estar prontos antes de você criar a configuração do gatilho.

Modos de entrega

Conectores gerenciados suportam dois modos de entrega:

  • Polling: O host de Funções se conecta de saída ao Namespace do Conector para receber eventos. Defina DeliveryMode = ConnectorTriggerDeliveryMode.Poll, e adicione as configurações de conexão e acione a configuração em [ConnectorTrigger].
  • Webhook: O Namespace do Conector envia eventos para o endpoint de callback da extensão. Webhook é o padrão quando você omite DeliveryMode o [ConnectorTrigger] atributo.

Para ajuda na escolha de um modo, consulte Escolher um modo de entrega.

Introdução

Siga o caminho de configuração para o seu modo de entrega:

  1. Instale a extensão.
  2. Crie ou reutilize um namespace e uma conexão, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint da votação.
  4. Configure credenciais do chamador, acesso à conexão e configurações locais ou implantadas.
  5. Use um exemplo abaixo, correspondendo seus Connection valores TriggerConfigName e valores às suas configurações.

A pesquisa não requer um endpoint público de callback ou chave de sistema. Para entrega por webhook, a função de destino e o endpoint de callback devem estar prontos antes de você criar a configuração do gatilho.

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 possuem payloads fortemente tipados, vincule para string receber a carga útil JSON bruta. Esses exemplos armazenam intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo conector. Substitua o registro pela lógica de processamento da sua aplicação.

Para encontrar quais operações de conector suportam payloads fortemente tipados para .NET, consulte Operations to Azure Functions signature mapping.

O modo de entrega de sondamento também suporta propriedades opcionais no [ConnectorTrigger] atributo. Para descrições, valores suportados e valores padrão, consulte Propriedades de atributos de sondagem.

Office 365 Outlook

O exemplo a seguir é executado quando um novo e-mail chega na caixa de correio Office 365 Outlook configurada:

Este exemplo recebe lotes de até quatro eventos de conectores, cada um contendo um e-mail, e é usado ConnectorEvent<T> para acessar o payload e MessageIdo pacote de cada evento.

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 sealed class O365Functions(ILogger<O365Functions> logger)
{
    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewEmailTriggerConfigName%",
            IsBatched = true,
            MaxBatchSize = 4,
            TargetPendingEventThreshold = 16)]
        ConnectorEvent<Office365OnNewEmailTriggerPayload>[] emails)
    {
        foreach (var email in emails)
        {
            var messageCount = email.Data.Body?.Value?.Count ?? 0;
            logger.LogInformation(
                "Poll event {MessageId}: received {MessageCount} new email message(s).",
                email.MessageId,
                messageCount);
        }
    }
}

Para desenvolvimento local, inclua as configurações de conexão e o nome da configuração do gatilho na Values seção local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}

As propriedades do atributo referem-se a estas configurações:

  • Connection = "ConnectorNamespace" Identifica o prefixo de configurações. A extensão lê o endpoint de polling a partir de ConnectorNamespace__pollingEndpoint. Para como obter o endpoint e informações sobre as credenciais e políticas de acesso necessárias, consulte Endpoint de sondamento.
  • TriggerConfigName = "%OnNewEmailTriggerConfigName%" resolve o valor da OnNewEmailTriggerConfigName configuração. Defina seu valor para o nome da configuração do gatilho de sondamento no seu Namespace do Conector.

Os nomes do prefixo e das configurações são ilustrativos; se você os alterar, atualize tanto as propriedades do atributo quanto as configurações para corresponder. Para um aplicativo de função implantado, adicione as mesmas configurações às configurações do aplicativo de funções em vez de local.settings.json.

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

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

SharePoint Online

O exemplo a seguir é executado quando um arquivo é criado na biblioteca de documentos SharePoint Online configurada:

Este exemplo recebe um evento de conector contendo um arquivo por invocação (o padrão) e o usa ConnectorEvent<T> para acessar seu payload e MessageId.

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 sealed class SharePointFunctions(ILogger<SharePointFunctions> logger)
{
    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewFileTriggerConfigName%")]
        ConnectorEvent<SharePointOnlineOnNewFileItemsTriggerPayload> file)
    {
        var fileCount = file.Data.Body?.Value?.Count ?? 0;
        logger.LogInformation(
            "Poll event {MessageId}: received {FileCount} new SharePoint file(s).",
            file.MessageId,
            fileCount);
    }
}

Para desenvolvimento local, inclua estes valores no Values objeto em local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}

As propriedades do atributo referem-se a estas configurações:

  • Connection = "ConnectorNamespace" Identifica o prefixo de configurações. A extensão lê o endpoint de polling a partir de ConnectorNamespace__pollingEndpoint. Para como obter o endpoint e informações sobre as credenciais e políticas de acesso necessárias, consulte Endpoint de sondamento.
  • TriggerConfigName = "%OnNewFileTriggerConfigName%" resolve o valor da OnNewFileTriggerConfigName configuração. Defina seu valor como o nome da configuração do gatilho de polling do SharePoint no seu Namespace do Conector.

Os nomes do prefixo e das configurações são ilustrativos; se você os alterar, atualize tanto as propriedades do atributo quanto as configurações para corresponder. Para um aplicativo de função implantado, adicione as mesmas configurações às configurações do aplicativo de funções em vez de local.settings.json.

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

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

Conector sem uma carga útil fortemente tipada

Alguns eventos de conector ainda não possuem uma carga útil .NET fortemente tipada. O exemplo a seguir é executado quando uma nova mensagem é adicionada a um chat ou canal do Microsoft Teams. Polling usa ConnectorEvent<string> para receber a carga JSON bruta com metadados de entrega; entrega por webhook vincula-se diretamente a string:

Este exemplo recebe um evento de conector por invocação (padrão) e é usado ConnectorEvent<string> para acessar seu payload JSON e MessageId.

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

namespace TeamsApp;

public sealed class TeamsFunctions(ILogger<TeamsFunctions> logger)
{
    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%")]
        ConnectorEvent<string> message)
    {
        logger.LogInformation(
            "Poll event {MessageId}: received a Teams payload of {PayloadLength} characters.",
            message.MessageId,
            message.Data.Length);
    }
}

Para desenvolvimento local, inclua estes valores no Values objeto em local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}

As propriedades do atributo referem-se a estas configurações:

  • Connection = "ConnectorNamespace" Identifica o prefixo de configurações. A extensão lê o endpoint de polling a partir de ConnectorNamespace__pollingEndpoint. Para como obter o endpoint e informações sobre as credenciais e políticas de acesso necessárias, consulte Endpoint de sondamento.
  • TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%" resolve o valor da OnNewTeamsMessageTriggerConfigName configuração. Defina seu valor para o nome da configuração do gatilho de sondamento do Teams no seu Namespace do Conector.

Os nomes do prefixo e das configurações são ilustrativos; se você os alterar, atualize tanto as propriedades do atributo quanto as configurações para corresponder. Para um aplicativo de função implantado, adicione as mesmas configurações às configurações do aplicativo de funções em vez de local.settings.json.

Para o exemplo completo de código, incluindo infraestrutura e registro de gatilhos, consulte Gatilhos genéricos de conector para .NET.

Mapeamentos de eventos do conector

O nome da operação é definido pelo conector gerenciado. Você escolhe o nome da função no seu código. Os exemplos de polling e webhook usam os mesmos nomes de evento, operação e função:

Evento de conector Nome da operação Nome da função
Novo e-mail Office 365 Outlook OnNewEmailV3 OnNewEmail
Novo arquivo SharePoint Online GetOnNewFileItems OnNewFile
Nova mensagem de chat ou canal do Microsoft Teams WebhookNewMessageTrigger OnNewTeamsMessage

Payloads Webhook podem conter múltiplos itens, dependendo da configuração do gatilho.

A entrega por sondamento sempre habilita splitOn, então cada evento em fila contém um item dividido. No entanto, o modo de sondagem pode agrupar eventos em uma única invocação de função definindo IsBatched = true. Para configuração de lote, consulte Atributos.

Tipos de associação

Para funções de trabalho isoladas .NET, ambos os modos de entrega suportam estes tipos de parâmetros:

Tipo Description
string Recebe o corpo do evento como JSON bruto. Use esse tipo quando um modelo de SDK fortemente tilado não estiver disponível ou quando quiser desserializar a carga útil você mesmo.
Modelo SDK do conector Desserializa o corpo do evento JSON em um modelo específico de operação a partir de Azure.Connectors.Sdk, como Office365OnNewEmailTriggerPayload ou SharePointOnlineOnNewFileItemsTriggerPayload.
JSON-desserializável POCO Desserializa o corpo do evento JSON em um tipo .NET cujo formato corresponde à carga útil do conector usando o serializador de trabalho configurado.
ConnectorEvent<T> Envolve um tipo de payload suportado em Data. MessageId contém o identificador de entrega para polling e é null para entrega por webhook.

Parâmetros de matriz

Parâmetros de array têm significados diferentes em cada modo de entrega.

Para polling, IsBatched determina a forma do parâmetro da função, onde T é um tipo de payload de evento suportado:

IsBatched Tipo de parâmetro de função
false (predefinição) T ou ConnectorEvent<T>
true T[] ou ConnectorEvent<T>[], mesmo quando MaxBatchSize = 1

Definido MaxBatchSize para um valor de 1 a 32; sem loteamento, o tamanho efetivo do lote deve ser 1. O tamanho do lote conta eventos do conector, não itens dentro da carga útil de um evento. O batching não altera o tipo de carga útil dentro de cada evento. A coleção de Body.Value uma carga útil de SDK é separada da matriz externa de eventos fornecida a uma invocação em lote.

Para webhook, use T[] para desserializar o corpo do array JSON de um único callback em um array de itens de payload. Este não é um lote de eventos entregues separadamente. Entrega por Webhook processa um callback por invocação; IsBatched aplica-se apenas a sondamento.

Examples

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

Para encontrar quais operações de conector suportam payloads fortemente tipados para JavaScript e TypeScript, consulte a referência de extensão de conectorNode.js.

Office 365 Outlook

O exemplo a seguir é executado quando um novo e-mail chega na caixa de correio Office 365 Outlook configurada:

Este exemplo recebe até quatro eventos de conector por invocação. O assistente fornece os e-mails desses eventos como uma única lista.

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

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    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 exemplos adicionais, veja Office 365 Outlook gatilhos para TypeScript.

SharePoint Online

O exemplo a seguir é executado quando um arquivo é criado na biblioteca de documentos SharePoint Online configurada:

Este exemplo recebe um evento de conector por invocação, o padrão. O ajudante fornece seus registros de propriedades de arquivo como uma lista.

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

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (
        context: SharepointItemTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

O SharepointItemTriggerContext tipo expõe registros de propriedades de arquivo para records a GetOnNewFileItems operação. O auxiliar preserva os campos fornecidos pelo conector sem convertê-los em um esquema de arquivo fixo. Para exemplos adicionais, consulte SharePoint Online triggers para TypeScript.

Equipes da Microsoft

O exemplo a seguir ocorre quando uma nova mensagem é adicionada a um canal do Microsoft Teams:

Este exemplo recebe um evento de conector por invocação, o padrão. O auxiliar fornece sua carga útil de mensagens em forma de lista.

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

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    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 exemplos adicionais, consulte os gatilhos do Microsoft Teams para TypeScript.

Carga útil genérica do conector

Use o auxiliar genérico quando uma operação não tiver um registro nomeado. Acesse context.rawPayload quando seu código precisar processar o próprio payload original.

Este exemplo recebe um evento de conector por invocação, o padrão. O ajudante fornece seus itens de carga em forma de lista.

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

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

O contexto genérico estabelece seu tipo de item como padrão para unknown. Valide itens antes de acessar propriedades específicas da operação. context.rawPayload preserva a entrada analisada antes da normalização, incluindo o array de eventos externo para consulta em lote.

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 mostradas nesta seção. Esses exemplos registram intencionalmente apenas informações básicas de carga útil para manter o foco em como definir funções acionadas pelo Connector. Substitua o registro pela lógica de processamento da sua aplicação.

Para encontrar quais operações de conector suportam payloads fortemente tipados para JavaScript e TypeScript, consulte a referência de extensão de conectorNode.js.

Office 365 Outlook

O exemplo a seguir é executado quando um novo e-mail chega na caixa de correio Office 365 Outlook configurada:

Este exemplo recebe até quatro eventos de conector por invocação. O assistente fornece os e-mails desses eventos como uma única lista.

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

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    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 a seguir é executado quando um arquivo é criado na biblioteca de documentos SharePoint Online configurada:

Este exemplo recebe um evento de conector por invocação, o padrão. O ajudante fornece seus registros de propriedades de arquivo como uma lista.

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

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

O contexto do manipulador expõe registros de propriedades de arquivo para records a GetOnNewFileItems operação. O auxiliar preserva os campos fornecidos pelo conector sem convertê-los em um esquema de arquivo fixo.

Equipes da Microsoft

O exemplo a seguir ocorre quando uma nova mensagem é adicionada a um canal do Microsoft Teams:

Este exemplo recebe um evento de conector por invocação, o padrão. O auxiliar fornece sua carga útil de mensagens em forma de lista.

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

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    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.

Carga útil genérica do conector

Use o auxiliar genérico quando uma operação não tiver um registro nomeado. Acesse context.rawPayload quando seu código precisar processar o próprio payload original.

Este exemplo recebe um evento de conector por invocação, o padrão. O ajudante fornece seus itens de carga em forma de lista.

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

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

Valide itens antes de acessar propriedades específicas da operação. context.rawPayload preserva a entrada analisada antes da normalização, incluindo o array de eventos externo para consulta em lote.

Configurações locais de votação

Adicione os nomes de configuração do endpoint de sondagem e dos gatilhos à local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "OnNewTeamsMessageTriggerConfigName": "<teams-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

O valor dos connection: 'ConnectorNamespace' exemplos identifica o prefixo de configurações. Cada triggerConfigName expressão resolve para a configuração correspondente do aplicativo. Para configurações implantadas e permissões de conexão, consulte Questionar autenticação.

Para outro exemplo de registro em votação, consulte a amostraNode.js de pesquisa.

Examples

Os exemplos Office 365 Outlook e SharePoint Online usam conversores fornecidos por azurefunctions-extensions-connectors. O exemplo genérico recebe JSON bruto sem anotação de SDK. Esses exemplos registram apenas informações básicas de payload; substitua o registro pela lógica de processamento da sua aplicação.

Para encontrar quais operações de conector suportam payloads fortemente tipados para Python, consulte Conceitos-chave na extensão do conector Python.

Office 365 Outlook

O exemplo a seguir é executado quando um novo e-mail chega na caixa de correio Office 365 Outlook configurada:

Este exemplo recebe até quatro eventos de conector por invocação. O conversor fornece os e-mails desses eventos como uma única lista.

import logging

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",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnNewEmailTriggerConfigName%",
    cardinality=func.Cardinality.MANY,
    max_batch_size=4,
    target_pending_event_threshold=16,
)
def on_new_email(
    emails: list[office365.GraphClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

A GraphClientReceiveMessage vinculação suporta a OnNewEmailV3 operação. Para código completo, infraestrutura e registro de gatilhos para ambos os modos, consulte Office 365 Outlook gatilhos para Python.

SharePoint Online

O exemplo a seguir é executado quando um arquivo é criado na biblioteca de documentos SharePoint Online configurada:

Este exemplo recebe um evento de conector por invocação, o padrão. O conversor fornece seus registros de propriedades de arquivo como uma lista.

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.sharepointonline as sharepoint

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(
    arg_name="files",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnSharepointNewFileTriggerConfigName%",
)
def on_sharepoint_new_file(files: list[sharepoint.Item]) -> None:
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

A Item vinculação suporta a GetOnNewFileItems operação e preserva propriedades do arquivo em dynamic_properties. Para código completo, infraestrutura e registro de gatilhos para ambos os modos, consulte SharePoint Online triggers para Python.

Carga útil genérica do conector

Use a azure-functions biblioteca para receber eventos como strings JSON brutas quando uma operação não tiver um conversor tipado suportado, ou quando você quiser analisar o JSON você mesmo.

Este exemplo recebe um evento de conector por invocação, o padrão, como uma string JSON bruta.

import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(
    arg_name="payload",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%GenericTriggerConfigName%",
)
def on_connector_event(payload: str) -> None:
    logging.info("Received a connector event.")

Para exemplos completos, consulte Gatilhos genéricos de conector para Python.

Para polling local, defina os nomes de configuração dos endpoints e triggers em Valueslocal.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

O valor dos connection="ConnectorNamespace" exemplos identifica o prefixo de configurações. Cada trigger_config_name expressão resolve para a configuração correspondente do aplicativo. Para configurações implantadas e permissões de conexão, consulte Questionar autenticação.

Tipos de associação

Ambos os modos de entrega suportam as seguintes formas de registro e carga útil:

Registration Entrada do manipulador
app.connectorTrigger direto de @azure/functions Recebe a entrada original do gatilho sem normalização auxiliar. O tipo de entrada TypeScript é unknownpadrão ; para polling em lote, use um tipo de array como unknown[].
connectorTrigger direto de @azure/functions-extensions-connectors Recebe um ConnectorTriggerContext<T> com normalizado payload e items, analisado rawPayload, e toJSON() serialização. O tipo de item TypeScript é padrão para unknown.
Ajudantes nomeados como connectors.office365.onNewEmail Receba o contexto normalizado com um array nomeado, como emails, , ou messages, que aliasa itemsrecords. TypeScript infere o tipo de item do SDK suportado.

Os ajudantes aceitam entradas de objetos ou strings JSON. Eles normalizam { body: item } e { body: { value: [...] } } envolvem. Para sondagens em lote, eles achatam o array externo de envelopes e seus itens de carga útil em um único items array, preservando a ordem. rawPayload mantém a entrada analisada antes da normalização, incluindo o array de eventos externo.

Defina cardinality: 'many' para habilitar o lote de invocação. Um array no contexto ou um tipo de array TypeScript sozinho não habilita o batching. maxBatchSize Conta eventos do conector, não itens no array normalizado. Cada invocação de webhook lida com um callback, que pode conter múltiplos itens de payload.

Os tipos TypeScript descrevem a carga útil esperada, mas não validam nem transformam campos específicos da operação em tempo de execução. Valide a carga útil antes de acessar propriedades quando sua forma não for conhecida. Para registros tipados suportados e tipos de carga útil SDK, consulte a referência de extensão do conectorNode.js.

Tipos de associação

O gatilho Connector suporta estes tipos de parâmetros em Python:

Tipo Description
str Recebe o corpo do evento como uma string JSON.
dict Aceito como anotação, mas o conversor bruto não analisa cadeias JSON em dicionários. Para analisar JSON bruto, vincule e str use json.loads.
bytes Recebe o corpo do evento como bytes brutos.
typing.List[str] ou typing.List[bytes] Recebe eventos de conectores entregues separadamente como uma lista quando o sondamento utiliza cardinality=func.Cardinality.MANY. Importe List de typing para essas anotações.
Anotação do SDK do Conector Suportado Usa um conversor registrado por azurefunctions-extensions-connectors para desserializar a carga útil em uma lista de modelos SDK específicos da operação.

Para ligações de SDK, anote o parâmetro com o tipo de vinculação suportado ou uma lista desse tipo, como list[office365.GraphClientReceiveMessage]. Os bindings do SDK suportados retornam listas tanto para invocações de evento único quanto em lote. Para sondagem em lote, o conversor agrupa os eventos de transporte e seus itens de carga útil em uma única lista.

Defina cardinality=func.Cardinality.MANY o decorador para habilitar o batching de invocação. Uma anotação de lista sozinha não habilita o agrupamento. A configuração de tamanho de lote conta os eventos do conector, não itens dentro da carga útil de um evento ou o número de modelos na lista retornada.

O acesso à conexão e a autorização de callback são separados. O Namespace do Conector gerencia automaticamente seu próprio acesso à conexão do conector gerenciado. Configure o acesso do aplicativo de função de acordo com seu modo de entrega.

Modo de votação

Attributes

O ConnectorTrigger atributo suporta as seguintes propriedades quando DeliveryMode configurado como ConnectorTriggerDeliveryMode.Poll:

Property Required Padrão Description
DeliveryMode Sim, para votação ConnectorTriggerDeliveryMode.Webhook Configure para ConnectorTriggerDeliveryMode.Poll usar sondagem.
Connection Yes null Identifica o prefixo de configuração para o endpoint de polling do Espaço de Nomes do Conector e as configurações de identidade. Por exemplo, "ConnectorNamespace" seleciona ConnectorNamespace__pollingEndpoint.
TriggerConfigName Yes null O nome da configuração do gatilho de polling no Namespace do Conector. Forneça o nome diretamente ou use uma expressão de configuração de aplicativo como "%OnNewEmailTriggerConfigName%".
IsBatched No false Se cada invocação recebe um lote de eventos do conector. Quando false, cada invocação recebe um evento. Defina e true use um parâmetro de array para receber lotes. Os lotes são processados um de cada vez por ouvinte.
MaxBatchSize No 1 Eventos máximos de conectores por invocação, de 1 a 32. Quando omitido ou definido como 0, usa a configuração do defaultMaxBatchSize host, que é padrão para 1 menos que esteja configurado de outra forma em host.json. O tamanho efetivo do lote deve ser 1 quando IsBatched é false.
MaxConcurrentCalls No 16 Tarefas máximas de processamento de evento único concorrentes por ouvinte em uma única instância, incluindo preparação, invocação e reconhecimento. Deve ser não-negativo. Quando omitido ou definido como 0, usa a configuração do defaultMaxConcurrentCalls host, que é padrão para 16 menos que esteja configurado de outra forma em host.json. Aplica-se somente quando IsBatched for false. Invocações em lote processam um lote por vez por ouvinte.
TargetPendingEventThreshold No 16 Número desejado de eventos pendentes de conectores por instância para escalamento baseado em destino. Deve ser não-negativo. Quando omitido ou definido como 0, usa a configuração do defaultTargetPendingEventThreshold host, que é padrão para 16 menos que esteja configurado de outra forma em host.json. O tempo de execução pode substituir esse alvo de escala. Esta propriedade não altera o tamanho do lote nem a concorrência de invocação.

Para os padrões de todo o aplicativo, consulte Configurações de host.json de sontagem. O tamanho do lote conta eventos do conector, não itens dentro da carga útil de um evento.

Decoradores de votação

Ative delivery_mode=func.DeliveryMode.POLL@app.connector_trigger e configure a conexão de sondamento e a configuração do gatilho:

Parameter Required Padrão Description
arg_name Yes None Identifica o parâmetro da função que recebe o payload.
delivery_mode Sim, para votação func.DeliveryMode.WEBHOOK Configure para func.DeliveryMode.POLL usar sondagem. As cordas "Poll" e "Webhook" também são suportadas.
connection Yes None Identifica o prefixo de configurações para o endpoint de polling e as configurações de identidade. Por exemplo, "ConnectorNamespace" seleciona ConnectorNamespace__pollingEndpoint.
trigger_config_name Yes None Identifica a configuração do gatilho de sondamento. Forneça o nome diretamente ou use uma expressão de configuração de aplicativo como "%OnNewEmailTriggerConfigName%".
cardinality No func.Cardinality.ONE Defina como func.Cardinality.MANY ou "many" para habilitar o batching de invocação. Invocações em lote são processadas uma de cada vez por ouvinte.
max_batch_size No Padrão do host: 1 Eventos máximos de conectores por invocação, de 1 a 32. Quando omitido ou definido como 0, usa defaultMaxBatchSize de host.json. Sem loteamento, o tamanho efetivo do lote deve ser 1.
max_concurrent_calls No Padrão do host: 16 Tarefas máximas de processamento de evento único simultâneas por ouvinte em uma única instância. Quando omitido ou definido como 0, usa defaultMaxConcurrentCalls de host.json. Deve ser não-negativo. Não se aplica a invocações em lote.
target_pending_event_threshold No Padrão do host: 16 Segmente eventos pendentes por instância para escalonamento baseado em destino. Quando omitido ou definido como 0, usa defaultTargetPendingEventThreshold de host.json. Deve ser não-negativo. Não altera o tamanho do lote nem a concorrência de invocação; o tempo de execução pode substituir o alvo de escala.

Para os padrões de todo o aplicativo, consulte Configurações de host.json de sontagem. Para formas de parâmetros e anotações de SDK, consulte Tipos de vinculação.

Opções de registro para votação

Defina deliveryMode: 'Poll' em um auxiliar nomeado, o assistente genérico connectorTrigger ou app.connectorTrigger, e configure a conexão de sondamento e a configuração do gatilho:

Option Required Padrão Description
deliveryMode Sim, para votação 'Webhook' Configure para 'Poll' usar sondagem.
connection Yes None Identifica o prefixo de configurações para o endpoint de polling e as configurações de identidade. Por exemplo, 'ConnectorNamespace' seleciona ConnectorNamespace__pollingEndpoint.
triggerConfigName Yes None Identifica a configuração do gatilho de sondamento. Forneça o nome diretamente ou use uma expressão de configuração de aplicativo como '%OnNewEmailTriggerConfigName%'.
cardinality No 'one' Defina para 'many' habilitar o batching de invocação. Invocações em lote são processadas uma de cada vez por ouvinte.
maxBatchSize No Padrão do host: 1 Eventos máximos de conectores por invocação, de 1 a 32. Quando omitido ou definido como 0, usa defaultMaxBatchSize de host.json. Sem loteamento, o tamanho efetivo do lote deve ser 1.
maxConcurrentCalls No Padrão do host: 16 Tarefas máximas de processamento de evento único simultâneas por ouvinte em uma única instância. Quando omitido ou definido como 0, usa defaultMaxConcurrentCalls de host.json. Deve ser não-negativo. Não se aplica a invocações em lote.
targetPendingEventThreshold No Padrão do host: 16 Segmente eventos pendentes por instância para escalonamento baseado em destino. Quando omitido ou definido como 0, usa defaultTargetPendingEventThreshold de host.json. Deve ser não-negativo. Não altera o tamanho do lote nem a concorrência de invocação; o tempo de execução pode substituir o alvo de escala.

Para os padrões de todo o aplicativo, consulte Configurações de host.json de sontagem. Para formas de entrada do manipulador, consulte Tipos de vinculação.

Ponto de extremidade de sondagem

A configuração de conexão da função seleciona o prefixo para o endpoint de polling. Por exemplo, o prefixo "ConnectorNamespace" usa ConnectorNamespace__pollingEndpoint. Defina essa configuração em Valueslocal.settings.json para desenvolvimento local ou nas configurações do aplicativo para um aplicativo de função implantado, conforme mostrado nos exemplos de polling.

Recupere o endpoint de polling no portal do Namespace do Conector, ou derive-o do serviço gerado pollingEndpoints.receiveUri pela configuração do gatilho conforme segue. Substitua os marcadores de posição pelos valores dos seus recursos.

Requer CLI do Azure, jq, e sed.

triggerConfigId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/connectorGateways/<namespace-name>/triggerConfigs/<trigger-config-name>"
triggerConfig=$(az rest --method get \
    --url "${triggerConfigId}?api-version=2026-05-01-preview" \
    --query '{receiveUri:properties.pollingEndpoints.receiveUri,name:name}' \
    --output json)
receiveUri=$(printf '%s' "$triggerConfig" | jq -r '.receiveUri')
pollingEndpoint=$(printf '%s' "$receiveUri" |
    sed -E 's#/(api/)?trigger[Cc]onfigs/[^/]+/receive$##')
triggerConfigName=$(printf '%s' "$triggerConfig" | jq -r '.name')
printf '%s\n' "ConnectorNamespace__pollingEndpoint=$pollingEndpoint" \
    "OnNewEmailTriggerConfigName=$triggerConfigName"

Derive a configuração a partir do URI de Recepção gerado pelo serviço da seguinte forma:

Serviço pollingEndpoints.receiveUri <Connection>__pollingEndpoint
https://<connector-namespace-host>/api/triggerconfigs/<name>/receive https://<connector-namespace-host>
https://<host>/api/connectorGateways/<id>/triggerconfigs/<name>/receive https://<host>/api/connectorGateways/<id>

Preserve o identificador de host e gateway fornecido pelo serviço; não adivinhe um nome de host nem configure a URL de Recepção completa, um caminho de operação, uma base independente /api ou uma string de consulta.

A extensão usa esse endpoint com o nome de configuração do gatilho para construir URLs de operações de polling. Para as credenciais e políticas de acesso necessárias para chamar essas URLs, consulte Questionar autenticação.

Configuração do gatilho de polling

O nome da configuração do gatilho da função identifica a configuração a partir da qual será recebido eventos.

Pesquisa dos valores de configuração do gatilho

Valor de configuração Description
Conexão A conexão gerenciada autorizada, como Office 365 Outlook ou SharePoint Online. Isso é separado da configuração de conexão da função, que identifica um prefixo de configurações de app.
Nome da operação A operação de gatilho do conector, como OnNewEmailV3 ou GetOnNewFileItems.
Parameters Valores exigidos pela operação, como uma pasta do Outlook ou um site SharePoint e biblioteca de documentos.
Nome da configuração do gatilho O nome desta configuração de gatilho de sondagem, referenciado diretamente pela função ou por meio de uma configuração de aplicativo.
Modo de entrega Como os eventos são oferecidos pelos serviços, por meio de votação ou modo webhook.

Crie uma configuração de gatilho de sondamento

  1. Se você ainda não tem um namespace de conectores, crie um namespace de conectores.

  2. Vá ao portal do Espaço de Nomes do Conector e então selecione seu espaço de nomes.

  3. No menu namespace, selecione Triggers e depois selecione Criar.

  4. Encontre o conector gerenciado que você quer usar e então selecione o evento que deve acionar a função.

  5. Na página de configuração do gatilho, crie uma conexão ou selecione uma conexão existente. Criar uma conexão requer uma autenticação única com o serviço externo.

  6. Forneça as entradas exigidas pelo evento. Por exemplo, o evento Office 365 Outlook novo e-mail exige que a pasta monitore novas mensagens.

  7. Para Tipo de destino, escolha Azure Functions.

  8. Para o modo de entrega, escolha Polling.

  9. Examine a configuração e selecione Criar.

Autenticação por questionamento

Para consulta, conceda uma política de acesso em nível de conexão à identidade gerenciada do aplicativo de função (implantada) ou à sua identidade de desenvolvedor (local). O host de Funções usa as credenciais Microsoft Entra dessa identidade para receber e confirmar eventos através do endpoint de votação. O acesso de conexão próprio do Espaço de Nomes do Conector é gerenciado automaticamente.

A política do chamador concede acesso à conexão do conector gerenciada, não ao namespace em si. Fazer login ou habilitar uma identidade gerenciada não concede automaticamente esse acesso ao chamador.

Ao contrário da entrega por webhook, o polling não requer uma URL pública de callback ou uma chave de sistema do aplicativo de função porque o aplicativo de função recupera eventos do namespace em vez de receber callbacks.

As configurações de autenticação nas subseções seguintes usam o prefixo ConnectorNamespace, correspondendo aos exemplos de gatilhos. Se sua função usar um prefixo diferente para configuração de conexão, use esse prefixo em vez disso.

Conceder políticas de acesso

Use qualquer um dos métodos para conceder ao chamador de sondagem acesso à conexão. Você precisa de permissão para gerenciar as políticas de acesso na conexão. Use o ID principal (objeto) do chamador, não o ID do aplicativo (cliente).

  1. Vá ao portal do Espaço de Nomes do Conector e então selecione seu espaço de nomes.
  2. Abra Conexões e selecione a conexão do conector gerenciada usada pela configuração do gatilho de sondamento.
  3. Abra a aba Políticas de Acesso da conexão.
  4. Adicione uma política de acesso para a identidade do chamador. Para desenvolvimento local, use o ID de objeto da sua conta de desenvolvedor. Para um aplicativo de função implantado, use o ID principal (objeto) da identidade gerenciada que seu aplicativo utiliza.
  5. Verifique se o chamador possui uma política de acesso na conexão.

Desenvolvimento local

  1. Faça login com sua identidade de desenvolvedor, por exemplo, executando az login. Esta é a conta Microsoft Entra que a extensão usa para autenticar solicitações de votação localmente.
  2. Conceda uma política de acesso na conexão do conector gerenciado para essa identidade. Fazer login sozinho não concede acesso à conexão.
  3. Defina as configurações de conexão em Valueslocal.settings.json. Omita ConnectorNamespace__credential usar credenciais de desenvolvedor.

Aplicativo de função implantado

  1. Habilite uma identidade gerenciada atribuída pelo sistema no aplicativo de funções ou atribua uma identidade gerenciada atribuída pelo usuário a ela.
  2. Conceda uma política de acesso na conexão do conector gerenciado para essa identidade.
  3. Configure as seguintes configurações de autenticação nas configurações do aplicativo de funções:
Configurações de aplicativo Value
ConnectorNamespace__credential managedidentity
ConnectorNamespace__clientId O ID de cliente da identidade gerenciada atribuída pelo usuário a ser usada para consultas. Definido somente ao usar uma identidade atribuída pelo usuário.

Alternativamente, defina ConnectorNamespace__managedIdentityResourceId para o ID de recurso da identidade atribuída pelo usuário em vez de definir ConnectorNamespace__clientId. Para uma identidade atribuída pelo sistema, omita ambos os seletores.

Uso em pesquisas

O host de Funções se conecta de saída ao Namespace do Conector para sondar eventos e reconhecer invocações bem-sucedidas. A extensão passa os eventos para sua função; você não escreve um ciclo de sontamento.

A entrega é pelo menos uma vez. Invocações falhadas não são reconhecidas, e eventos podem ser reentregues após o término do bloqueio gerenciado pelo serviço. Torne o processamento idempotente.

Se você usar ConnectorEvent<T>.MessageId para deduplicação, defina o limite para a configuração do namespace e do trigger; não presuma que os IDs das mensagens sejam únicos entre os gatilhos.

Defina DeliveryMode = ConnectorTriggerDeliveryMode.Poll em [ConnectorTrigger], e forneça as Connection propriedades e TriggerConfigName . Veja os exemplos de pesquisas.

Para propriedades de atributo, valores suportados e padrão, consulte Polling propriedades de atributo.

Defina delivery_mode=func.DeliveryMode.POLL em @app.connector_trigger, e forneça connection e trigger_config_name. Veja os exemplos de pesquisas.

O host recebe um evento por invocação, a menos que cardinality=func.Cardinality.MANY habilite o batching. Para lotes brutos, use typing.List[str] ou typing.List[bytes]; as anotações SDK suportadas forneçam uma lista de modelos. Para opções, valores suportados e padrãos, consulte Decoradores de pesquisa.

Defina deliveryMode: 'Poll', e forneça connection e triggerConfigName nas opções de registro. Veja os exemplos de pesquisas.

O host recebe um evento por invocação, a menos que cardinality: 'many' habilite o batching. Auxiliares nomeados e genéricos combinam os itens de payload de todos os eventos em um único contexto. Os manipuladores diretos app.connectorTrigger , em vez disso, recebem o array de eventos externo. Para opções, valores suportados e valores padrão, consulte Opções de registro de consulta.

Dimensionamento e simultaneidade

Entrega por Webhook

No modo webhook, o Espaço de Nomes do Conector envia solicitações HTTP para o endpoint de callback da extensão. Gatilhos de conectores escalam como gatilhos HTTP, de acordo com o comportamento e os limites de escalonamento HTTP do plano de hospedagem. Para detalhes, veja Escalonamento orientado por eventos no Azure Functions.

Execução das pesquisas

No modo de polling, o Gatilho do Conector utiliza escalonamento baseado em alvo baseado no backlog estimado de eventos para a configuração do gatilho no Namespace do Conector. O alvo de escalabilidade é independente da concorrência de processamento por instância e do tamanho do lote. Para a equação de escala, configurações e orientações de ajuste, veja Escalada baseada em alvo de conectores gerenciados.

Modo Webhook

Registration

Use a função genérica connectorTrigger para uma operação que não tenha um registro 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 registro genérico define o tipo de item como unknownpadrão. Valide a carga útil antes de acessar propriedades específicas da operação. Configure o conector, operação, parâmetros operacionais, função de destino e autenticação de retorno de chamada na configuração do gatilho no Azure Connector Namespace.

Registration

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

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

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

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

Decoradores

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 operacionais, função de destino e autenticação de retorno de chamada na configuração do gatilho no Azure Connector Namespace.

Attributes

Ao contrário do sondamento, a entrega por webhook não requer propriedades adicionais sobre o [ConnectorTrigger] atributo porque webhook é o modo padrão de entrega. Você também pode definir DeliveryMode = ConnectorTriggerDeliveryMode.Webhook explicitamente. Propriedades específicas de Polling não se aplicam à entrega por webhook.

Configuração do gatilho do Webhook

A URL de callback da configuração do gatilho identifica a função de destino.

Valores de configuração do gatilho Webhook

Valor de configuração Description
Conexão A conexão gerenciada autorizada, como Office 365 Outlook ou SharePoint Online.
Nome da operação A operação de gatilho do conector, como OnNewEmailV3 ou GetOnNewFileItems.
Parameters Valores exigidos pela operação, como uma pasta do Outlook ou um site SharePoint e biblioteca de documentos.
URL de Callback O endpoint webhook da extensão Connector para a função de destino. Veja autenticação por Webhook.
Nome da função O nome da função registrada no código do seu app.
Authentication A configuração de autenticação usada para chamar o aplicativo de funções.

O functionName valor da string de consulta na URL de callback deve corresponder ao nome da função registrada. Nomes válidos de funções de webhook contêm de 1 a 128 letras, números, sublinhados ou hífens.

Crie uma configuração de gatilho de webhook

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

Configurar o gatilho

Uma configuração de gatilho 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
Conexão A conexão gerenciada autorizada, como Office 365 Outlook ou SharePoint Online.
Nome da operação A operação de gatilho do conector, como OnNewEmailV3 ou GetOnNewFileItems.
Parameters Valores exigidos pela operação, como uma pasta do Outlook ou um site SharePoint e biblioteca de documentos.
URL de Callback O endpoint webhook da extensão Connector para a função de destino. Veja autenticação por Webhook.
Nome da função O nome da função registrada no código do seu app.
Authentication A configuração de autenticação usada para chamar o aplicativo de funções.

O functionName valor da string de consulta na URL de callback da configuração do gatilho deve corresponder ao nome da função registrada. 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 gerenciado. Você escolhe o nome da função no seu código, e a configuração do gatilho mapeia a operação para essa função. Os exemplos neste artigo usam estes mapeamentos:

Evento de conector Nome da operação Nome da função
Novo e-mail Office 365 Outlook OnNewEmailV3 OnNewEmail
Novo arquivo SharePoint Online GetOnNewFileItems OnSharepointNewFile
Nova mensagem do canal do Microsoft Teams OnNewChannelMessage OnNewChannelMessage
Evento de conector selecionado A operação selecionada na configuração do gatilho OnConnectorEvent
Evento de conector Nome da operação Nome da função
Novo e-mail Office 365 Outlook OnNewEmailV3 OnNewEmail
Novo arquivo SharePoint Online GetOnNewFileItems OnSharepointNewFile
Evento de conector selecionado A operação selecionada na configuração do gatilho OnConnectorEvent

Criar uma configuração de gatilho

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

Antes que a extensão possa receber um evento, crie estes recursos e configurações:

  1. Um espaço de nomes de conector.
  2. Uma conexão gerenciada de conector autorizada para acessar o serviço externo.
  3. Uma configuração de gatilho que seleciona o evento do conector, parâmetros de operação e modo de entrega.

Para a entrega por webhook, a configuração do gatilho também inclui a URL de callback e a autenticação de callback.

Configurações de gatilho são recursos de Namespace de Conectores que você também pode implantar via ARM ou Bicep.

Os exemplos do CLI do Azure abaixo usam um aplicativo de funções implantado. Implante o aplicativo com a extensão e a função de destino antes de executá-los.

O exemplo a seguir no Bash usa CLI do Azure e jq para criar um gatilho Office 365 Outlook novo e-mail. Substitua os valores provisórios para seus recursos e conexã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 monitorar. A URL de retorno 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.

Autenticação por Webhook

O Namespace do Conector envia eventos para o aplicativo de funções, em vez de o aplicativo de função consultar o namespace. Por padrão, o host de Funções autentica esses callbacks validando a chave de sistema da extensão do Connector, chamada connector_extension.

O Namespace do Conector gerencia automaticamente o acesso à sua conexão de conectores gerenciada. Ao contrário do sondamento, a identidade do aplicativo de função não precisa de uma política de acesso à conexão apenas para receber callbacks de webhook; a tecla do sistema autoriza essas solicitações ao aplicativo de funções.

Webhook callback URL

App implantado

Use o endpoint de callback da extensão, sem uma chave na URL:

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

O functionName valor deve corresponder ao nome da função registrada: o [Function] atributo em C#, o @app.function_name decorador em Python ou o registro do gatilho em Node.js.

Para um aplicativo implantado usando autenticação padrão, use a tecla de sistema da connector_extension extensão Connector, não uma tecla de função individual. Após implantar o aplicativo de funções com a extensão, recupere a chave do sistema:

az functionapp keys list \
    --resource-group <RESOURCE_GROUP> \
    --name <FUNCTION_APP_NAME> \
    --query "systemKeys.connector_extension" \
    --output tsv

Na configuração do gatilho, armazene a chave em notificationDetails.authentication, separadamente da URL de callback:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

Ao entregar um evento, o Connector Namespace adiciona a chave como parâmetro code query-string. Manter a chave separada da URL de retorno salva permite que o portal a mascare como um segredo. Não inclua a chave na URL de callback salva nem a envie ao controle de versão.

Configurações de gatilhos existentes que incluem a chave na URL de retorno continuam funcionando. Quando você edita e salva uma configuração de gatilho existente, a chave se move para notificationDetails.authentication.

As teclas do sistema não podem ser escopadas por gatilho e exigem rotação coordenada entre o aplicativo de funções e o Espaço de Nomes do Conector. Para callbacks baseados em identidade sem chave compartilhada, consulte Autenticação integrada.

Desenvolvimento de webhooks locais

Os callbacks Webhook devem alcançar seu host de Funções em execução a partir do namespace do Conector. Quando você executa localmente:

  1. Inicie o aplicativo de funções com o Azure Functions Core Tools, habilitando a autorização:

    func start --enableAuth
    

    Importante

    Use sempre --enableAuth ao expor seu app via um túnel de desenvolvimento. Sem ele, seu endpoint de função fica completamente sem autenticação na internet pública.

  2. Use um túnel de desenvolvimento da Microsoft para encaminhar um endpoint HTTPS público para a porta host local das Funções. Defina a visibilidade da porta do túnel como Pública para que o Namespace do Conector possa alcançá-la.

  3. Construa a URL de callback com o nome de host do túnel e o nome da função registrada, e use-a na configuração do gatilho do webhook. Por exemplo, uma porta de encaminhamento de túnel 7071 para a OnNewFile função usa uma URL como:

    https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFile
    

    Para um host local que armazena segredos em Azurite, recupere sua connector_extension chave de sistema usando estes comandos do PowerShell. Definido $connStr para a conhecida cadeia de conexão Azurite:

    $connStr = "<azurite-connection-string>"
    
    # Find the most recent host.json blob
    $blobs = az storage blob list --container-name azure-webjobs-secrets --connection-string $connStr -o json | ConvertFrom-Json
    $blobName = ($blobs | Where-Object { $_.name -match '(^|/)host\.json$' } | Sort-Object { $_.properties.lastModified } | Select-Object -Last 1).name
    
    # Download and parse
    az storage blob download --container-name azure-webjobs-secrets --name $blobName --connection-string $connStr --file host-keys.json --no-progress
    $keys = Get-Content host-keys.json | ConvertFrom-Json
    $connectorKey = ($keys.systemKeys | Where-Object { $_.name -eq "connector_extension" }).value
    Remove-Item -LiteralPath host-keys.json
    

    Armazene a chave de sistema do connector_extension host local separadamente em notificationDetails.authentication, usando o QueryString formato de autenticação mostrado acima.

  4. Mantenha o host e o túnel funcionando durante os testes. Atualize a configuração do gatilho se o nome do host do túnel mudar.

Autenticação interna

Para callbacks de webhook sem chaves compartilhadas, use a autenticação integrada do App Service (também chamada Easy Auth) com identidade gerenciada. Essa configuração é independente da linguagem de programação da função.

O Espaço de Nomes do Conector usa sua identidade gerenciada atribuída pelo sistema ou pelo usuário para solicitar um token de Microsoft Entra ID para cada callback. A autenticação embutida valida o token e a identidade do chamador antes que a solicitação chegue ao host de Funções. Para uma implementação de ponta a ponta sem segredos de cliente, consulte o exemplo de autenticação embutida.

Esta seção aborda a autenticação do namespace para o aplicativo de funções. O Namespace do Conector gerencia automaticamente o acesso à sua conexão de conectores gerenciada. Para autenticação para serviços upstream, consulte a visão geral dos conectores Azure.

Configuração do aplicativo de funções

Importante

Essa configuração requer autenticação em todo o aplicativo de funções, não apenas /runtime/webhooks/connector, e restringe o acesso à identidade de callback do namespace. As funções HTTP existentes que requerem teclas de função continuam a exigir essas chaves além da autenticação em nível de app. Antes de aplicar essa configuração a um aplicativo existente, certifique-se de que os clientes de API e as sondas de saúde possam satisfazer a política de autenticação e autorização em nível de aplicativo e quaisquer requisitos de chave em nível de função. Caso contrário, as solicitações podem falhar com HTTP 401 ou 403. Se o aplicativo precisar aceitar outros chamadores, adapte a política de autorização em vez de copiar essa lista de permitidos sem alterações. Para opções de política, consulte Configurar autorização Microsoft Entra.

Configure a autenticação integrada por meio do recurso ARM doauthsettingsV2 aplicativo de funções ou seu equivalente no Bicep. O exemplo usa as seguintes configurações de chave:

Setting Purpose
platform.enabled: true Habilita autenticação integrada.
globalValidation.requireAuthentication: true Requer autenticação antes que as solicitações cheguem ao host de Funções.
globalValidation.unauthenticatedClientAction: Return401 Retorna HTTP 401 para callbacks não autenticados em vez de redirecionar para uma página de login.
identityProviders.azureActiveDirectory.enabled: true Habilita a validação do token Microsoft Entra.
registration.clientId O ID do aplicativo (cliente) do registro do aplicativo Microsoft Entra que representa o aplicativo funcional.
registration.openIdIssuer A URL do emissor do seu tenant: https://login.microsoftonline.com/{tenantId}/v2.0.
validation.allowedAudiences O ID do cliente e o URI de identificador do aplicativo Entra. Os tokens devem conter um público permitido na aud reivindicação.
validation.defaultAuthorizationPolicy.allowedPrincipals.identities Os IDs de objeto (principal) permitiram chamar o aplicativo de funções. O exemplo permite apenas a identidade gerenciada de callback do namespace. Adapte esta política se seu aplicativo tiver outros chamadores. Um token válido com uma oid reivindicação não na lista de permitidos é negado com HTTP 403.

As registration configurações de e validation nesta tabela estão sob identityProviders.azureActiveDirectory.

O exemplo também atribui uma identidade gerenciada atribuída ao usuário ao aplicativo de função e a federa ao registro do aplicativo Entra. A autenticação embutida usa essa credencial de identidade federada para obter asserções de cliente sem armazenar um segredo de cliente. O exemplo define a configuração OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID do aplicativo para o ID de cliente da identidade do aplicativo da função e define registration.clientSecretSettingName para o nome dessa configuração.

A identidade do aplicativo de função usada para federação é separada da identidade de callback do namespace. A identidade do namespace é o chamador permitido por allowedPrincipals.identities.

Após a autenticação embutida for configurada para validar callbacks, desative a verificação redundante da chave de sistemahost.json:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

Use Anonymous somente quando outra camada de autenticação validar as solicitações antes que cheguem ao host de Funções. Essa configuração não habilita a validação do token por si só.

Configuração do namespace do conector

Habilite uma identidade gerenciada atribuída pelo sistema no Namespace do Conector ou anexe uma identidade atribuída pelo usuário a ela. Na configuração notificationDetails.authenticationdo gatilho, defina:

Property Value
type ManagedServiceIdentity
audience O ID de cliente do registro do app Entra, correspondendo a um público aceito pelo aplicativo de funções.
identity O ID do recurso da identidade gerenciada atribuída pelo usuário anexado. Omita esta propriedade para uma identidade atribuída pelo sistema.

O namespace usa essa identidade para obter um token e o envia no cabeçalho do Authorization: Bearer <token> callback. O iss token identifica o locatário, aud identifica o aplicativo de destino e oid identifica a identidade gerenciada do namespace.

O namespace gerencia automaticamente seu próprio acesso à conexão do conector gerenciado. Esse acesso é separado da autorização de callback, que você configura por meio da autenticação integrada no aplicativo de funções.

Fluxo de autenticação e validação

  1. O Namespace do Conector obtém um token para o público configurado usando sua identidade gerenciada por callback.
  2. O namespace envia o token com o evento para o endpoint do webhook da extensão.
  3. A autenticação embutida valida a assinatura, expiração, emissor e público do token, e verifica se ele oid corresponde a uma identidade permitida. Tokens ausentes ou inválidos recebem HTTP 401; tokens válidos de uma identidade não incluída na lista de permissões recebem HTTP 403.
  4. Somente solicitações autorizadas chegam ao host de Funções. Com a verificação redundante de chave do sistema desativada, a extensão invoca a função de destino e vincula o corpo do evento ao seu parâmetro.

Sua função não precisa de código de aplicativo para realizar essas verificações de acesso.

Uso do Webhook

O Espaço de Nomes do Conector envia eventos para o endpoint webhook da extensão, onde o functionName valor de query string seleciona a função. A extensão vincula o corpo do evento ao seu parâmetro de função; você não implementa um manipulador HTTP.

O nome da função deve corresponder ao nome do seu [Function] atributo. Callbacks podem incluir x-ms-* cabeçalhos que identificam a configuração do gatilho, conexão, tipo de evento e ID de correlação, mas esses cabeçalhos não estão disponíveis para sua função através do Gatilho do Conector.

Use [ConnectorTrigger] sem propriedades de consulta. Webhook é o padrão quando você omite DeliveryModeo . Veja os exemplos de webhooks.

Sua função pode receber o payload de eventos usando qualquer um dos tipos de binding .NET suportados.

A extensão aceita HTTP POST e PUT solicitações com o tipo de application/json conteúdo. Um corpo de requisição não vazio deve conter JSON válido. As solicitações estão sujeitas ao limite de corpo de requisição do host Functions e aos limites de serviço a montante; a extensão não impõe um limite separado de tamanho de carga útil.

Para configurar o limite de corpo de requisição do host, defina a configuração do app em bytes FUNCTIONS_REQUEST_BODY_SIZE_LIMIT e reinicie o host. Isso não é uma host.json configuração e não altera os downloads de saída vinculada do Poll, que usam extensions.connector.maxLinkedOutputSizeInBytes. Limites maiores não garantem tamanhos de carga útiles suportados; considerem buffering, memória de trabalho e limites de upstream.

Uso do Webhook

O ajudante genérico recebe um ConnectorTriggerContext<T>. Sua payload propriedade contém o envelope de callback normalizado, items contém os itens de evento e rawPayload preserva a entrada analisada antes da normalização. Registros específicos de conectores fornecem arrays nomeados, como emails, records, ou messages.

Cada invocação lida com um callback, que pode conter múltiplos itens de payload. Para uma operação sem registro específico do conector, o tipo de item TypeScript é padrão para unknown. Valide a carga útil antes de acessar propriedades específicas da operação. Para registros digitados suportados, consulte a referência de extensão do conectorNode.js.

Uso do Webhook

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

Cada invocação trata de um callback. Os bindings de SDK suportados fornecem seus itens de payload como uma lista; use uma anotação como list[office365.GraphClientReceiveMessage]. Para as anotações específicas de operação suportadas, consulte o mapeamento de assinatura de operação.

A extensão aceita HTTP POST e PUT solicitações com o tipo de application/json conteúdo. Um corpo de requisição não vazio deve conter JSON válido. As solicitações estão sujeitas ao limite de corpo de requerimento do host das Funções, e aos limites de serviço upstream.

Metadata

O gatilho Connector atualmente não expõe cabeçalhos de callback ou outros metadados de requisições como dados de vinculação. A extensão define um contrato de dados de vinculação vazio, então a função recebe apenas o corpo da solicitação JSON em um tipo de vinculação suportado pela linguagem selecionada.