Connector Trigger for Funções do Azure

Funções do Azure fornece extensões de trigger e binding que se integram com vários serviços, principalmente serviços Azure. A Extensão do Conector expande estas integrações para uma seleção muito mais ampla de serviços, incluindo sistemas empresariais e plataformas de dados.

Por exemplo, utilize o Connector Trigger para executar uma função quando um novo email chegar em Office 365 Outlook, um ficheiro for criado em SharePoint ou um registo for alterado no Salesforce. 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 mais informações sobre conectores geridos, quando utilizá-los e disponibilidade de funcionalidades, consulte Utilizar conectores geridos no Funções do Azure.

Note

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

Modos de entrega

Os conectores geridos suportam dois modos de entrega:

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

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 ligação, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint de sondagem.
  4. Configure credenciais do chamador, acesso à ligação e definições locais ou implementadas.
  5. Use um exemplo de sondagem abaixo, associando os seus connection valores triggerConfigName às suas definições.

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

Modos de entrega

Os conectores geridos suportam dois modos de entrega:

  • Polling: O host de Funções liga-se 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 Espaço de Nomes do Conector envia eventos para o endpoint de callback da extensão. Webhook é o padrão quando 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 ligação, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint de sondagem.
  4. Configure credenciais do chamador, acesso à ligação e definições locais ou implementadas.
  5. Use um exemplo de sondagem abaixo, associando os seus connection valores trigger_config_name às suas definições.

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

Modos de entrega

Os conectores geridos suportam dois modos de entrega:

  • Polling: O host de Funções liga-se de saída ao Namespace do Conector para receber eventos. Defina DeliveryMode = ConnectorTriggerDeliveryMode.Poll, e adicione as definições de ligação e a configuração do trigger em [ConnectorTrigger].
  • Webhook: O Espaço de Nomes do Conector envia eventos para o endpoint de callback da extensão. Webhook é o padrão quando 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 ligação, e crie uma configuração de gatilho de sondagem.
  3. Obtenha o endpoint de sondagem.
  4. Configure credenciais do chamador, acesso à ligação e definições locais ou implementadas.
  5. Use um exemplo abaixo, associando os seus Connection valores TriggerConfigName com as suas definições.

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

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 conector. Substitua o registo pela lógica de processamento da sua aplicação.

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

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

Office 365 Outlook

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

Este exemplo recebe lotes de até quatro eventos de conectores, cada um contendo um email, e é utilizado ConnectorEvent<T> para aceder à carga útil de cada evento e MessageId.

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 definições de ligação e o nome da configuração do gatilho na Values secção de local.settings.json:

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

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

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

Os nomes do prefixo e das definições são ilustrativos; se os alterar, atualize tanto as propriedades do atributo como as definições para corresponder. Para uma aplicação de funções implementada, adicione as mesmas definições às definições da aplicação da aplicação 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 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:

Este exemplo recebe um evento de conector contendo um ficheiro por invocação (o padrão) e o utiliza ConnectorEvent<T> para aceder ao 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 definições:

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

Os nomes do prefixo e das definições são ilustrativos; se os alterar, atualize tanto as propriedades do atributo como as definições para corresponder. Para uma aplicação de funções implementada, adicione as mesmas definições às definições da aplicação da aplicação 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 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 é executado quando uma nova mensagem é adicionada a um chat ou canal do Microsoft Teams. O questionamento utiliza ConnectorEvent<string> para receber o payload JSON bruto com metadados de entrega; a entrega por webhook vincula-se diretamente a string:

Este exemplo recebe um evento de conector por invocação (predefinido) e é utilizado ConnectorEvent<string> para aceder ao 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 definições:

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

Os nomes do prefixo e das definições são ilustrativos; se os alterar, atualize tanto as propriedades do atributo como as definições para corresponder. Para uma aplicação de funções implementada, adicione as mesmas definições às definições da aplicação da aplicação em vez de local.settings.json.

Para o exemplo completo de código, incluindo registo de infraestrutura e de triggers, consulte Gatilhos genéricos de conectores para .NET.

Mapeamentos de eventos de conectores

O nome da operação é definido pelo conector gerido. Escolhes o nome da função no teu código. Os exemplos de polling e webhook usam os mesmos nomes de eventos, operações e funções:

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

Os payloads Webhook podem conter múltiplos itens, dependendo da configuração do trigger.

A entrega de sondagens ativa splitOnsempre , pelo que cada evento em fila contém um item dividido. No entanto, o modo de sondagem pode agrupar eventos numa única invocação de funções ao definir IsBatched = true. Para configuração em lote, consulte Atributos.

Tipos de vinculaçã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 este tipo quando não estiver disponível um modelo SDK fortemente tipado ou quando quiser desserializar a carga útil por si mesmo.
Modelo SDK de Conectores Desserializa o corpo do evento JSON num modelo específico de operação a partir de Azure.Connectors.Sdk, como Office365OnNewEmailTriggerPayload ou SharePointOnlineOnNewFileItemsTriggerPayload.
POCO JSON-desserializável Desserializa o corpo do evento JSON num tipo .NET cuja forma corresponde à carga útil do conector, utilizando o serializador de trabalho configurado.
ConnectorEvent<T> Envolve um tipo de carga útil suportado em Data. MessageId contém o identificador de entrega para sondagem e é null para entrega por webhook.

Parâmetros da matriz

Os parâmetros do array têm significados diferentes em cada modo de entrega.

Para sondamento, 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 (padrã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 os eventos do conector, não os itens dentro da carga útil de um evento. O batching não altera o tipo de payload dentro de cada evento. A coleção de Body.Value um payload SDK é separada do array externo de eventos fornecido a uma invocação em lote.

Para webhook, use T[] para desserializar o corpo do array JSON de um único callback numa matriz de itens de payload. Isto não é um conjunto de eventos entregues separadamente. A entrega por Webhook processa um callback por invocação; IsBatched aplica-se apenas ao sondamento.

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.

Para encontrar quais operações de conector suportam cargas úteis fortemente tipadas para JavaScript e TypeScript, consulte a referência da extensão de conectorNode.js.

Office 365 Outlook

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

Este exemplo recebe até quatro eventos de conectores por invocação. O assistente fornece os emails desses eventos numa só 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, consulte Office 365 Outlook triggers para TypeScript.

SharePoint Online

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

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece os seus registos de propriedades do ficheiro 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 registos de propriedades de ficheiro para records a GetOnNewFileItems operação. O auxiliar preserva os campos fornecidos pelo conector sem os converter num esquema de ficheiro fixo. Para exemplos adicionais, consulte os gatilhos do SharePoint Online para TypeScript.

Microsoft Teams

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

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece a sua carga útil de mensagens sob 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 Microsoft Teams triggers para TypeScript.

Carga útil genérica do conector

Use o assistente genérico quando uma operação não tiver um registo nomeado. Aceda context.rawPayload quando o seu código precisa de processar o próprio payload original.

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece os seus itens de carga sob 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 define por predefinição o seu tipo de item para unknown. Valide os itens antes de aceder às propriedades específicas da operação. context.rawPayload preserva a entrada analisada antes da normalização, incluindo o array de eventos externo para sondeamento 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 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.

Para encontrar quais operações de conector suportam cargas úteis fortemente tipadas para JavaScript e TypeScript, consulte a referência da extensão de conectorNode.js.

Office 365 Outlook

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

Este exemplo recebe até quatro eventos de conectores por invocação. O assistente fornece os emails desses eventos numa só 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 seguinte executa-se quando um ficheiro é criado na biblioteca de documentos SharePoint Online configurada:

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece os seus registos de propriedades do ficheiro 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 registos de propriedades de ficheiro para records a GetOnNewFileItems operação. O auxiliar preserva os campos fornecidos pelo conector sem os converter num esquema de ficheiro fixo.

Microsoft Teams

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

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece a sua carga útil de mensagens sob 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 assistente genérico quando uma operação não tiver um registo nomeado. Aceda context.rawPayload quando o seu código precisa de processar o próprio payload original.

Este exemplo recebe um evento de conector por invocação, o predefinido. O ajudante fornece os seus itens de carga sob 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 os itens antes de aceder às propriedades específicas da operação. context.rawPayload preserva a entrada analisada antes da normalização, incluindo o array de eventos externo para sondeamento em lote.

Configurações locais de sondagem

Adicione os nomes de configuração do endpoint de sondagem e dos triggers a 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 definições. Cada triggerConfigName expressão resolve para a configuração correspondente da aplicação. Para definições implementadas e permissões de ligação, consulte Interrogar autenticação.

Para outro exemplo de registo nas urnas, consulte a amostraNode.js sondagens.

Examples

Os exemplos Office 365 Outlook e SharePoint Online utilizam conversores fornecidos por azurefunctions-extensions-connectors. O exemplo genérico recebe JSON bruto sem anotação de SDK. Estes exemplos registam apenas informações básicas de carga útil; substitua o registo 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 seguinte executa-se quando um novo email chega à caixa de correio Office 365 Outlook configurada:

Este exemplo recebe até quatro eventos de conectores por invocação. O conversor fornece os emails 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 ligação suporta a OnNewEmailV3 operação. Para código completo, infraestrutura e registo de triggers para ambos os modos, consulte Office 365 Outlook triggers para Python.

SharePoint Online

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

Este exemplo recebe um evento de conector por invocação, o predefinido. O conversor fornece os seus registos de propriedades de ficheiro 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 ligação suporta a GetOnNewFileItems operação e preserva as propriedades do ficheiro em dynamic_properties. Para código completo, infraestrutura e registo de triggers 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 cadeias JSON brutas quando uma operação não tiver um conversor tipado suportado, ou quando quiser analisar o JSON por si próprio.

Este exemplo recebe um evento de conector por invocação, o predefinido, como uma cadeia 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 conectores para Python.

Para sondagens locais, 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 definições. Cada trigger_config_name expressão resolve para a configuração correspondente da aplicação. Para definições implementadas e permissões de ligação, consulte Interrogar autenticação.

Tipos de vinculação

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

Registration Entrada do manipulador
app.connectorTrigger de @azure/functions Recebe a entrada original do trigger sem normalização do auxiliar. O tipo de entrada TypeScript é predefinido para unknown; para sondagens em lote, utilize um tipo de array como unknown[].
connectorTrigger de @azure/functions-extensions-connectors Recebe a ConnectorTriggerContext<T> com normalizado payload e items, analisado rawPayload, e toJSON() serialização. O tipo de item TypeScript é predefinido para unknown.
Ajudantes nomeados, tais 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 SDK suportado.

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

Defina cardinality: 'many' para ativar o batching de invocação. Um array no contexto ou um tipo de array TypeScript por si só não permite o batching. maxBatchSize Conta os eventos do conector, não os itens no array normalizado. Cada invocação de webhook gere 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 o payload antes de aceder às propriedades quando a sua forma não for conhecida. Para registos tipados suportados e tipos de carga útil SDK, consulte a referência da extensão do conectorNode.js.

Tipos de vinculaçã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 Aceite como anotação, mas o conversor bruto não analisa cadeias JSON em dicionários. Para analisar JSON bruto, associe 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. Importar List de typing para estas anotações.
Anotação do SDK do Conector Suportado Utiliza um conversor registado por azurefunctions-extensions-connectors para desserializar a carga útil numa lista de modelos SDK específicos para operações.

Para ligações SDK, anote o parâmetro com o tipo de ligação suportado ou uma lista desse tipo, como list[office365.GraphClientReceiveMessage]. As ligações SDK suportadas retornam listas tanto para invocações de evento único como em lote. Para sondagens em lote, o conversor achata os eventos de transporte e os seus itens de carga útil numa única lista.

Defina cardinality=func.Cardinality.MANY o decorador para ativar o lote de invocação. Uma anotação de lista, por si só, não ativa o agrupamento. A definição de tamanho do lote conta os eventos do conector, não os itens dentro da carga útil de um evento ou o número de modelos na lista retornada.

O acesso à ligação e a autorização de callback são separados. O Espaço de Nomes do Conector gere automaticamente o seu próprio acesso à ligação do conetor gerido. Configure o acesso da aplicação de funções de acordo com o seu modo de entrega.

Modo de sondagem

Attributes

O ConnectorTrigger atributo suporta as seguintes propriedades quando DeliveryMode está definido como ConnectorTriggerDeliveryMode.Poll:

Property Required Predefinição Description
DeliveryMode Sim, para votações ConnectorTriggerDeliveryMode.Webhook Defina para ConnectorTriggerDeliveryMode.Poll usar a sondagem.
Connection Yes null Identifica o prefixo de configuração para o endpoint de sondagem do Espaço de Nomes do Conector e as definições de identidade. Por exemplo, "ConnectorNamespace" seleciona ConnectorNamespace__pollingEndpoint.
TriggerConfigName Yes null O nome da configuração do gatilho de sondamento no Espaço de Nomes do Conector. Forneça o nome diretamente ou utilize uma expressão de definição de aplicação 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 do conector por invocação, de 1 a 32. Quando omitido ou definido como 0, usa a definição do defaultMaxBatchSize host, que predefine para 1 salvo configuração 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 em simultâneo por ouvinte numa única instância, incluindo preparação, invocação e reconhecimento. O valor deve ser não negativo. Quando omitido ou definido como 0, usa a definição do defaultMaxConcurrentCalls host, que predefine para 16 salvo configuração de outra forma em host.json. Aplica-se apenas quando IsBatched é false. Invocações em lote processam um lote de cada vez por ouvinte.
TargetPendingEventThreshold No 16 Número desejado de eventos pendentes de conectores por instância para escalamento baseado em destino. O valor deve ser não negativo. Quando omitido ou definido como 0, usa a definição do defaultTargetPendingEventThreshold host, que predefine para 16 salvo configuração de outra forma em host.json. O tempo de execução pode sobrepor este alvo de escala. Esta propriedade não altera o tamanho do lote nem a concorrência de invocação.

Para valores predefinidos para toda a aplicação, consulte Definições de sondagem host.json. O tamanho do lote conta os eventos do conector, não os itens dentro da carga útil de um evento.

Decoradores de votação

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

Parameter Required Predefinição Description
arg_name Yes None Identifica o parâmetro da função que recebe o payload.
delivery_mode Sim, para votações func.DeliveryMode.WEBHOOK Defina para func.DeliveryMode.POLL usar a sondagem. As cordas "Poll" e "Webhook" também são suportadas.
connection Yes None Identifica o prefixo de definições para o endpoint de sondagem e as definições de identidade. Por exemplo, "ConnectorNamespace" seleciona ConnectorNamespace__pollingEndpoint.
trigger_config_name Yes None Identifica a configuração do gatilho de polling. Forneça o nome diretamente ou utilize uma expressão de definição de aplicação como "%OnNewEmailTriggerConfigName%".
cardinality No func.Cardinality.ONE Defina como func.Cardinality.MANY ou "many" para ativar o batching de invocação. As 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 do conector 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 concorrentes por ouvinte numa única instância. Quando omitido ou definido como 0, usa defaultMaxConcurrentCalls de host.json. O valor 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 escalamento baseado em destino. Quando omitido ou definido como 0, usa defaultTargetPendingEventThreshold de host.json. O valor 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 valores predefinidos para toda a aplicação, consulte Definições de sondagem host.json. Para formas de parâmetros e anotações de SDK, consulte Tipos de ligação.

Opções de registo nas urnas

Defina deliveryMode: 'Poll' num assistente nomeado, o assistente genérico connectorTrigger , ou app.connectorTrigger, e configure a configuração da ligação de sondagem e do gatilho:

Option Required Predefinição Description
deliveryMode Sim, para votações 'Webhook' Defina para 'Poll' usar a sondagem.
connection Yes None Identifica o prefixo de definições para o endpoint de sondagem e as definições de identidade. Por exemplo, 'ConnectorNamespace' seleciona ConnectorNamespace__pollingEndpoint.
triggerConfigName Yes None Identifica a configuração do gatilho de polling. Forneça o nome diretamente ou utilize uma expressão de definição de aplicação como '%OnNewEmailTriggerConfigName%'.
cardinality No 'one' Defina para 'many' ativar o batching de invocação. As invocações em lote são processadas uma de cada vez por ouvinte.
maxBatchSize No Padrão do host: 1 Eventos máximos do conector 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 concorrentes por ouvinte numa única instância. Quando omitido ou definido como 0, usa defaultMaxConcurrentCalls de host.json. O valor 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 escalamento baseado em destino. Quando omitido ou definido como 0, usa defaultTargetPendingEventThreshold de host.json. O valor 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 valores predefinidos para toda a aplicação, consulte Definições de sondagem host.json. Para formas de entrada do manipulador, consulte Tipos de ligação.

Ponto final de sondagem

A configuração de ligação da função seleciona o prefixo para o endpoint de sondagem. Por exemplo, o prefixo "ConnectorNamespace" usa ConnectorNamespace__pollingEndpoint. Defina esta definição em Valueslocal.settings.json para desenvolvimento local ou nas definições de aplicação para uma aplicação de função implementada, conforme mostrado nos exemplos de sondagens.

Obtenha o endpoint de polling no portal do Connector Namespace, ou derive-o do serviço gerado pollingEndpoints.receiveUri pela configuração do trigger da seguinte forma. 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 definição a partir do URI de Receçã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 o URL de Receção completo, um caminho de operação, uma base autónoma /api ou uma cadeia de consulta.

A extensão utiliza este endpoint com o nome da configuração do trigger para construir URLs de operações de sondagem. Para as credenciais e políticas de acesso necessárias para chamar estes URLs, consulte Sondagem da autenticação.

Configuração do gatilho de sondagem

O nome da configuração do trigger da função identifica a configuração a partir da qual receber eventos.

Consulta dos valores de configuração dos gatilhos

Valor de configuração Description
Ligação A ligação gerida autorizada, como Office 365 Outlook ou SharePoint Online. Isto é independente da configuração de ligação da função, que identifica um prefixo de configurações de aplicação.
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.
Nome da configuração do gatilho O nome desta configuração de gatilho de polling, referenciado diretamente pela função ou através de uma configuração de aplicação.
Modo de entrega Como os eventos são entregues a partir dos serviços, através de sondagens ou em modo webhook.

Criar uma configuração de gatilho de sondagem

  1. Se ainda não tens um namespace de conectores, cria um namespace de conectores.

  2. Vai ao portal do Espaço de Nomes do Conector e depois seleciona o teu espaço de nomes.

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

  4. Encontra o conector gerido que queres usar e depois seleciona o evento que deverá desencadear a função.

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

  6. Forneça os contributos exigidos pelo evento. Por exemplo, o evento de Office 365 Outlook novo email exige que a pasta monitorize novas mensagens.

  7. Para o tipo de destino, escolha Funções do Azure.

  8. Para o modo de entrega, escolha Polling.

  9. Reveja a configuração e, em seguida, selecione Criar.

Autenticação por sondagem

Para sondagens, conceda uma política de acesso ao nível de ligação à identidade gerida da aplicação de função (implementada) ou à sua identidade de programador (local). O anfitrião de Funções utiliza as credenciais Microsoft Entra desta identidade para receber e confirmar eventos através do endpoint de sondagem. O acesso à ligação próprio do Espaço de Nomes do Conector é gerido automaticamente.

A política do chamador concede acesso à ligação do conector gerida, não ao namespace em si. Iniciar sessão ou ativar uma identidade gerida não concede automaticamente este acesso ao chamador.

Ao contrário da entrega por webhook, o polling não requer um URL público de callback nem uma chave de sistema da aplicação funcional, porque a aplicação de funções recupera eventos do namespace em vez de receber callbacks.

As definições de autenticação nas subsecções seguintes usam o prefixo ConnectorNamespace, correspondendo aos exemplos de gatilho. Se a sua função usar um prefixo de configuração de ligação diferente, use esse prefixo em vez disso.

Conceder políticas de acesso

Use qualquer um dos métodos para conceder ao chamador de sondagem acesso à ligação. Precisa de permissão para gerir as políticas de acesso na ligação. Use o ID principal (objeto) do chamador, não o ID da aplicação (cliente).

  1. Vai ao portal do Espaço de Nomes do Conector e depois seleciona o teu espaço de nomes.
  2. Abra Ligações e selecione a ligação do conector gerido usada pela configuração do gatilho de sondagem.
  3. Abra o separador Políticas de Acesso da ligação.
  4. Adicione uma política de acesso para a identidade do chamador. Para desenvolvimento local, utilize o ID de objeto da sua conta de programador. Para uma aplicação de funções implementada, utilize o ID principal (de objeto) da identidade gerida que a sua aplicação utiliza.
  5. Verifique se o chamador tem uma política de acesso na ligação.

Desenvolvimento local

  1. Inicie sessão com a sua identidade de desenvolvedor, por exemplo, executando az login. Esta é a conta Microsoft Entra que a extensão utiliza para autenticar pedidos de sondagens localmente.
  2. Conceda uma política de acesso à ligação do conector gerido para essa identidade. Iniciar sessão sozinho não concede acesso à ligação.
  3. Defina as definições de ligação em Valueslocal.settings.json. Omitir ConnectorNamespace__credential usar credenciais de programador.

Aplicação de funções implementada

  1. Ative uma identidade gerida atribuída pelo sistema na aplicação de funções ou atribua-lhe uma identidade gerida atribuída pelo utilizador.
  2. Conceda uma política de acesso à ligação do conector gerido para essa identidade.
  3. Configure as seguintes definições de autenticação nas definições da aplicação de funções:
Definição da aplicação Valor
ConnectorNamespace__credential managedidentity
ConnectorNamespace__clientId O ID de cliente da identidade gerida atribuída pelo utilizador a utilizar para sondagens. Definir apenas quando usar uma identidade atribuída pelo utilizador.

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

Utilização nas sondagens

O host de Funções liga-se de saída ao Namespace do Conector para interrogar eventos e reconhecer invocações bem-sucedidas. A extensão transmite os eventos para a sua função; não escreve um ciclo de sondagens.

A entrega é pelo menos uma vez. As invocações falhadas não são reconhecidas e os eventos podem ser reentregues após expirar o bloqueio gerido pelo serviço. Tornar o processamento idempotente.

Se usar ConnectorEvent<T>.MessageId para deduplicação, defina-o para a configuração do namespace e do trigger; não assuma que os IDs das mensagens são únicos entre os triggers.

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

Para propriedades de atributos, valores suportados e valores predefinidos, consulte Sondagem de propriedades de atributos.

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

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

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

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

Dimensionamento e simultaneidade

Entrega por Webhook

No modo webhook, o Espaço de Nomes do Conector envia pedidos HTTP para o endpoint de callback da extensão. Os gatilhos do conector escalam como os gatilhos HTTP, de acordo com o comportamento e os limites de escalabilidade HTTP do plano de alojamento. Para mais detalhes, consulte Escalamento orientado por eventos no Funções do Azure.

Execução das sondagens

No modo de sondagem, o Gatilho do Conector utiliza escalonamento baseado no alvo baseado no atraso estimado de eventos para a configuração do gatilho no Espaço de Nomes do Conector. O alvo de escalamento é independente da concorrência de processamento por instância e do tamanho do lote. Para a equação de escala, definições de configuração e orientações de ajustamento, consulte Escalada baseada em alvo de conectores geridos.

Modo Webhook

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.

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.

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.

Attributes

Ao contrário do polling, a entrega por webhook não requer propriedades adicionais sobre o [ConnectorTrigger] atributo porque webhook é o modo de entrega predefinido. Também podes definir DeliveryMode = ConnectorTriggerDeliveryMode.Webhook explicitamente. As propriedades específicas de sondagens não se aplicam à entrega por webhook.

Configuração de disparador de Webhook

O URL de callback da configuração do trigger identifica a função de destino.

Valores de configuração do gatilho Webhook

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. Consulte autenticação Webhook.
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 cadeia de consulta no URL de callback deve corresponder ao nome da função registada. Os nomes válidos das funções de webhook contêm de 1 a 128 letras, números, sublinhados ou hífens.

Criar uma configuração de gatilho webhook

Crie uma configuração de trigger usando o CLI do Azure ou o portal 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. Consulte autenticação Webhook.
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 OnSharepointNewFile
Nova mensagem do canal do Microsoft Teams OnNewChannelMessage OnNewChannelMessage
Evento do conector selecionado A operação selecionada na configuração do trigger OnConnectorEvent
Evento de conector Nome da operação Nome da função
Novo Office 365 Outlook email OnNewEmailV3 OnNewEmail
Novo ficheiro SharePoint Online GetOnNewFileItems OnSharepointNewFile
Evento do conector selecionado A operação selecionada na configuração do trigger OnConnectorEvent

Criar uma configuração de gatilho

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

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

  1. Um espaço de nomes de conectores.
  2. Uma ligação de conector gerida autorizada a aceder ao 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 trigger inclui também o URL de callback e a autenticação de callback.

As configurações de trigger são recursos de Namespace de Conectores que também pode implementar através de ARM ou Bicep.

Os exemplos do CLI do Azure abaixo utilizam uma aplicação de funções implementada. Implemente a aplicação com a extensão e a função de destino antes de as executar.

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.

Autenticação por Webhook

O Espaço de Nomes do Conector envia eventos para a aplicação de funções, em vez de a aplicação de funções interrogar o namespace. Por predefinição, o host de Funções autentica estes callbacks validando a chave de sistema da extensão Connector, denominada connector_extension.

O Espaço de Nomes do Conector gere automaticamente o acesso à sua ligação de conectores gerida. Ao contrário do sondamento, a identidade da aplicação de funções não necessita de uma política de acesso à ligação apenas para receber callbacks de webhook; a chave do sistema autoriza esses pedidos à aplicação de funções.

Webhook callback URL

Aplicação implementada

Utilize o endpoint de callback da extensão, sem uma chave no URL:

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

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

Para uma aplicação implementada usando autenticação predefinida, utilize a chave de sistema da connector_extension extensão Connector, não uma tecla de função individual. Após implementar a aplicação 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 trigger, armazene a chave em notificationDetails.authentication, separadamente do 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 Espaço de Nomes do Conector adiciona a chave como code parâmetro query string. Manter a chave separada do URL de callback guardado permite ao portal mascará-la como um segredo. Não inclua a chave na URL de callback guardada nem a confirme no controlo de versão.

As configurações de gatilhos existentes que incluem a chave no URL de retorno continuam a funcionar. Quando edita e guarda uma configuração de trigger existente, a chave passa para notificationDetails.authentication.

As chaves do sistema não podem ser definidas por trigger e requerem rotação coordenada entre a aplicação de funções e o Espaço de Nomes do Conector. Para callbacks baseados em identidade sem chave partilhada, consulte Autenticação incorporada.

Desenvolvimento de webhooks locais

Os callbacks Webhook devem chegar ao seu host de Funções em execução a partir do Namespace do Conector. Quando corre localmente:

  1. Inicie a aplicação de funções com o Funções do Azure Core Tools, permitindo autorização:

    func start --enableAuth
    

    Importante

    Use sempre --enableAuth ao expor a sua aplicação através de um túnel de desenvolvimento. Sem ele, o endpoint da sua função fica completamente não autenticado na internet pública.

  2. Utilize 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 para Pública para que o Espaço de Nomes do Conector possa aceder a ela.

  3. Construa o URL de callback com o nome de host do túnel e o nome da função registada, e utilize-o na configuração do trigger do webhook. Por exemplo, uma porta de encaminhamento de túnel 7071 para a OnNewFile função utiliza um URL como:

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

    Para um host local que armazena segredos em Azurite, recupere a sua connector_extension chave do sistema utilizando estes comandos do PowerShell. Defina $connStr para a conhecida cadeia de ligaçã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, utilizando o QueryString formato de autenticação mostrado acima.

  4. Mantenha o host e o túnel a funcionar durante o teste. Atualize a configuração do trigger se o nome do host do túnel mudar.

Autenticação incorporada

Para callbacks webhook sem chaves partilhadas, utilize autenticação integrada do App Service (também chamada Easy Auth) com identidade gerida. Esta configuração é independente da linguagem de programação da função.

O Espaço de Nomes do Conector utiliza a sua identidade gerida atribuída pelo sistema ou pelo utilizador para solicitar um token Microsoft Entra ID para cada callback. A autenticação incorporada valida o token e a identidade do chamador antes de o pedido chegar ao host de Funções. Para uma implementação de ponta a ponta sem segredos de cliente, consulte o exemplo de autenticação incorporado.

Esta secção abrange a autenticação do namespace para a aplicação de funções. O Espaço de Nomes do Conector gere automaticamente o acesso à sua ligação de conectores gerida. Para autenticação dos serviços upstream, consulte a visão geral dos conectores Azure.

Configuração do aplicativo de função

Importante

Esta configuração requer autenticação em toda a aplicação 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 ao nível da aplicação. Antes de aplicar esta configuração a uma aplicação existente, certifique-se de que os clientes da API e as sondas de saúde conseguem satisfazer a política de autenticação e autorização ao nível da aplicação e quaisquer requisitos de chave ao nível da função. Caso contrário, os pedidos podem falhar com HTTP 401 ou 403. Se a aplicação tiver de aceitar outros chamadores, adapte a política de autorização em vez de copiar esta lista de permissões sem alterações. Para opções de política, consulte Configurar autorização Microsoft Entra.

Configure a autenticação integrada através do recurso ARM daauthsettingsV2 aplicação de funções ou do seu equivalente no Bicep. O exemplo utiliza as seguintes definições-chave:

Setting Purpose
platform.enabled: true Ativa autenticação incorporada.
globalValidation.requireAuthentication: true Requer autenticação antes que os pedidos cheguem ao host de Funções.
globalValidation.unauthenticatedClientAction: Return401 Devolve HTTP 401 para callbacks não autenticados em vez de redirecionar para uma página de iniciativa.
identityProviders.azureActiveDirectory.enabled: true Ativa a validação do token Microsoft Entra.
registration.clientId O ID da aplicação (cliente) do registo da aplicação Microsoft Entra que representa a aplicação funcional.
registration.openIdIssuer O URL do emissor do seu locatário: https://login.microsoftonline.com/{tenantId}/v2.0.
validation.allowedAudiences O ID do cliente e o identificador URI da aplicação Entra. Os tokens devem ter uma audiência permitida na aud reivindicação.
validation.defaultAuthorizationPolicy.allowedPrincipals.identities Os IDs do objeto (principal) permitiram chamar a aplicação da função. O exemplo permite apenas a identidade gerida de callback do namespace. Adapte esta política se a sua aplicação tiver outros chamadores. Um token válido com uma oid reivindicação não incluída na lista de permissões é negado com HTTP 403.

As registration definições e validation nesta tabela estão em identityProviders.azureActiveDirectory.

O exemplo também atribui uma identidade gerida atribuída pelo utilizador à aplicação de funções e federa-a ao registo da aplicação Entra. A autenticação incorporada utiliza esta credencial de identidade federada para obter asserções de cliente sem armazenar um segredo de cliente. O exemplo define a definição OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID da aplicação para o ID de cliente da identidade da função e define registration.clientSecretSettingName o nome dessa definição.

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

Depois de a autenticação incorporada estar configurada para validar callbacks, desative a verificação redundante da chave do sistemahost.json:

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

Use Anonymous apenas quando outra camada de autenticação validar pedidos antes de chegarem ao anfitrião de Funções. Esta configuração não ativa a validação do token por si só.

Configuração do Espaço de Nomes do Conector

Ative uma identidade gerida atribuída pelo sistema no Espaço de Nomes do Conector, ou associe uma identidade atribuída pelo utilizador a ela. Na configuração notificationDetails.authenticationdo trigger , defina:

Property Valor
type ManagedServiceIdentity
audience O ID de cliente do registo da aplicação Entra, correspondendo a um público aceite pela aplicação funcional.
identity O ID do recurso da identidade gerida atribuída pelo utilizador anexado. Omita esta propriedade para uma identidade atribuída pelo sistema.

O namespace utiliza essa identidade para obter um token e envia-o no cabeçalho do Authorization: Bearer <token> callback. O iss token identifica o inquilino, aud identifica a aplicação de destino e oid identifica a identidade gerida do namespace.

O namespace gere automaticamente o seu próprio acesso à ligação do conector gerido. Este acesso é separado da autorização de callback, que configura através da autenticação integrada na aplicação de funções.

Fluxo de autenticação e validação

  1. O Espaço de Nomes do Conector obtém um token para a audiência configurada utilizando a sua identidade gerida por callback.
  2. O namespace envia o token com o evento para o endpoint webhook da extensão.
  3. A autenticação incorporada valida a assinatura, expiração, emissor e audiência do token, e verifica se corresponde oid a uma identidade permitida. Tokens em falta 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. Apenas os pedidos autorizados chegam ao anfitrião das Funções. Com a verificação redundante da chave de sistema desativada, a extensão invoca a função de destino e associa o corpo do evento ao seu parâmetro.

A sua função não precisa de código de aplicação para realizar estas verificações de acesso.

Utilização 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; não implementa um manipulador HTTP.

O nome da função deve corresponder ao nome do seu [Function] atributo. Os callbacks podem incluir x-ms-* cabeçalhos que identificam a configuração do trigger, a ligação, o tipo de evento e o ID de correlação, mas estes cabeçalhos não estão disponíveis para a sua função através do Connector Trigger.

Use [ConnectorTrigger] sem propriedades de sondagem. Webhook é o padrão quando omite DeliveryMode. Veja os exemplos de webhooks.

A sua função pode receber o payload de eventos utilizando qualquer um dos tipos de ligação .NET suportados.

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. Os pedidos estão sujeitos ao limite de corpo de pedido do host das Funções 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 do corpo do pedido do host, defina a definição da aplicação em bytes FUNCTIONS_REQUEST_BODY_SIZE_LIMIT e reinicie o host. Isto não é uma host.json configuração e não altera os downloads de saída ligada do Poll, que usam extensions.connector.maxLinkedOutputSizeInBytes. Limites maiores não garantem tamanhos de carga útil suportados; consideram buffering, memória de trabalho e limites a montante.

Utilização do Webhook

O ajudante genérico recebe um ConnectorTriggerContext<T>. A 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. Registos específicos de conectores fornecem arrays nomeados, como emails, records, ou messages.

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

Utilização do Webhook

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.

Cada invocação trata de um callback. Os bindings do SDK suportados fornecem os seus itens de payload como uma lista; utilize 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 pedidos com o tipo de application/json conteúdo. Um corpo de pedido não vazio deve conter JSON válido. Os pedidos estão sujeitos ao limite de corpo do pedido do host das Funções e aos limites de serviço a montante.

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.