Visão geral da Extensão do Conector para 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 de Conectores amplia estas integrações através de conectores geridos no Namespace Azure Conectores, permitindo que as suas funções recebam eventos de sistemas empresariais e plataformas de dados como Office 365 Outlook, SharePoint Online, Microsoft Teams e Dataverse.

Para conectores Microsoft e geridos por terceiros disponíveis, consulte a referência de conectores.

Note

Os conectores geridos suportam os planos de alojamento Flex Consumption, Dedicated e Elastic Premium para aplicações Linux Function em todas as regiões. A disponibilidade para aplicações Windows é limitada atualmente.

Flex Consumption é o plano de alojamento recomendado para funções acionadas pelo conector.

Note

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

Para Use
Executar uma função em resposta a um evento num serviço ligado Gatilho do Conector, fornecido pela Extensão do Conector
Executar uma ação num serviço ligado a partir do código de função Azure Conectores SDK, disponível para .NET, Node.jse Python

Pode usar ambos em conjunto: o Connector Trigger inicia a sua função e o SDK executa ações nos serviços ligados. Se apenas precisar de executar ações, utilize o SDK sem a Extensão do Conector.

Para mais informações sobre conectores geridos, quando utilizá-los e disponibilidade de funcionalidades, consulte Utilizar conectores geridos no Funções do Azure.

Connector Trigger em Funções do Azure

Uma função acionada por um conector utiliza estes componentes:

Component Responsabilidade
Espaço de nomes do conector Os anfitriões geriam ligações de conectores e configurações de triggers.
Ligação gerida por conector Autentica-se ao serviço externo e gere a conectividade específica do serviço.
Configuração do acionador Seleciona o evento do conector, parâmetros de operação e modo de entrega.
Funções do Azure Connector Extension Recebe eventos do Espaço de Nomes do Conector, invoca a função e vincula o corpo do evento ao parâmetro da função.
Azure Connectors SDK (opcional) Fornece modelos opcionais de carga útil fortemente tipada e clientes para invocar operações de conectores geridos, como enviar um email ou criar um ficheiro SharePoint.

Um conector gerido pode suportar múltiplos eventos, e cada evento que pretende monitorizar necessita da sua própria configuração de trigger. Por exemplo, o conector de Office 365 Outlook suporta eventos como a chegada de um novo email, um email a ser sinalizado, a criação de um evento no calendário ou a modificação de um evento no calendário. Crie uma configuração de trigger separada para cada evento que pretende usar para executar uma função.

Para exemplos de código, consulte Exemplos de Gatilhos de Conector e Utilização de SDKs de Conectores no seu código.

Escolha um modo de entrega

Os conectores geridos suportam a entrega por webhook e sondagens. Escolha um modo com base na latência, capacidade de processamento, rede e necessidades de autenticação do seu cenário:

Feature Votação Webhook
Entrega de eventos e latência O anfitrião de Funções recupera eventos através de pedidos de sondagem de saída. Os eventos aguardam até que o anfitrião faça uma sondagem para eles. O Espaço de Nomes do Conector envia eventos para o endpoint de callback da aplicação de funções assim que os detege do serviço de origem, sem esperar que a aplicação faça a sondagem. Isto reduz a latência de entrega para processamento sensível ao tempo.
Capacidade de processamento e proteção a jusante O host recupera mais eventos à medida que a capacidade de processamento fica disponível. Combine limites de escala-out da aplicação com definições de concorrência de sondagens para vincular o processamento simultâneo e proteger bases de dados ou APIs posteriores. Os eventos pendentes permanecem em fila no Namespace do Conector, sujeitos aos seus limites de retenção de eventos. Os eventos chegam independentemente da capacidade de processamento disponível da aplicação. Os limites de escala podem levar a callbacks limitados ou falhados quando a procura excede a capacidade; eventos podem ser perdidos se a entrega não for bem-sucedida dentro dos limites de retentativa do serviço.
Rede de entrada Não é necessário um endpoint de callback de entrada. Pode restringir o acesso de entrada à aplicação de funções permitindo pedidos de saída para o endpoint de sondagem do Namespace do Connector. O Espaço de Nomes do Conector deve conseguir aceder ao endpoint de callback da aplicação. As restrições de entrada devem permitir esses pedidos.
Autenticação de identidade gerenciada O anfitrião de Funções pode usar a identidade gerida atribuída pelo sistema ou pelo utilizador da aplicação de funções para receber e reconhecer eventos. Conceda a essa identidade uma política de acesso na ligação do conector gerida. Para callbacks autenticados com Microsoft Entra ID, o Espaço de Nomes do Conector utiliza a sua identidade gerida. Configure a autenticação integrada do Serviço de Aplicação na aplicação da função receptora para validar os tokens. A autenticação webhook predefinida utiliza em vez disso a chave do sistema de extensão do Conector.

Dependendo do seu plano de alojamento, pode restringir o acesso de entrada à aplicação de funções usando endpoints privados ou restrições de acesso de entrada, incluindo restrições baseadas em IP ou endpoint de serviço, sem impedir o sondamento. A aplicação deve continuar a conseguir fazer pedidos HTTPS de saída para o endpoint de sondagem do Connector Namespace. Separadamente, a identidade gerida configurada pela aplicação de funções deve ter uma política de acesso na ligação do conector gerido.

O modo de entrega de eventos controla como os eventos chegam ao host de Funções a partir do Espaço de Nomes do Conector, e não como o conector gerido deteta alterações no serviço de origem.

A entrega por Webhook escala como gatilhos HTTP, enquanto a entrega por sondagem utiliza escalabilidade baseada em alvo. A meta de escala de sondagem é independente da concorrência dos ouvintes e do tamanho do lote. Para detalhes sobre ambos os modos, consulte Escala e concorrência do Gatilho do Conector. Para a equação de escala de sondagem e as definições de ajuste, consulte Escalamento baseado em alvo de conectores geridos.

Ambos os modos utilizam [ConnectorTrigger] o parâmetro de função que recebe o corpo do evento e podem usar os mesmos modelos de carga útil. Para exemplos de ambos os modos de entrega, consulte os exemplos do Gatilho do Conector.

Instalar pacotes

Extensão do conector

O Connector Trigger suporta o modelo worker isolado .NET. Para informações sobre versões suportadas de .NET em versões de runtime do Funções do Azure, consulte Linguagens por versão de runtime.

Adicione a versão 1.0.0 ou posterior do pacote de extensão Connector ao seu projeto.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector

SDKs de Azure Connectors

Se a sua função só precisar de executar ações em serviços externos e não precisar de ser desencadeada por eventos, utilize apenas o SDK do Azure Connectors. Não precisa do pacote de extensão Connector.

Adicione o Azure Connectors SDK:

dotnet add package Azure.Connectors.Sdk

Para conectores populares, o SDK fornece clientes fortemente tipados para invocar ações de conetor a partir das suas funções; consulte a referência do Azure Connectors SDK para a API .NET.

Instalar a extensão

Use Node.js 24 ou posterior. Ambos os modos de entrega utilizam assistentes de registo de gatilhos com o mesmo nome ou genéricos.

Instale os pacotes usados pelo gatilho Connector:

npm install "@azure/functions@latest" "@azure/functions-extensions-connectors@latest" "@azure/connectors@latest"

Estes pacotes fornecem a seguinte funcionalidade:

Configure o pacote de extensões no ficheirohost.json . O bundle fornece a extensão host do Connector para ambos os modos de entrega:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

Se a sua função só precisar de executar ações em serviços externos e não precisar de ser acionada por eventos, instale apenas o SDK Azure Connectors para Node.js. Não precisas dos pacotes de gatilho do Connector.

npm install "@azure/connectors@latest"

O SDK fornece clientes fortemente tipados para invocar ações de conectores a partir das suas funções.

Para versões atuais de pacotes e projetos completos, consulte os exemplos de conectores Funções do Azure para TypeScript.

Ambos os modos de entrega utilizam o @app.connector_trigger decorador. Para exemplos, consulte Exemplos de Gatilhos do Conector.

Instalar a extensão

Adicione os seguintes pacotes à requirements.txt:

azure-functions>=2.4.0
azurefunctions-extensions-connectors>=1.0.0

Note

Para versões Python anteriores à 3.13, use azure-functions>=1.27.0b1 em vez disso.

  • A biblioteca núcleo de Python Azure-functions fornece o decorador e pode vincular eventos únicos brutos a str ou bytes, ou lotes de sondagem a typing.List[str] ou typing.List[bytes].
  • O pacote azurefunctions-extensions-connectors integra o SDK Azure Connectors para Python e regista conversores para anotações específicas de SDK de operação suportadas. Por exemplo, emails: list[office365.GraphClientReceiveMessage], onde office365 é importado de azurefunctions.extensions.connectors, recebe objetos do modelo de email para a operação Office 365 OutlookOnNewEmailV3.

Configure o pacote de extensões no ficheirohost.json . O bundle fornece a extensão host do Connector para ambos os modos de entrega:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  }
}

Azure Connectors SDK

Se a sua função só precisar de executar ações em serviços externos e não precisar de ser acionada por eventos, instale apenas o SDK Azure Connectors para Python. Não precisas dos pacotes de gatilho do Connector.

python -m pip install "azure-connectors>=1.0.0"

O SDK fornece clientes fortemente tipados para invocar ações de conectores a partir das suas funções.

Para versões atuais de pacotes e projetos completos, consulte os exemplos de conectores Funções do Azure para Python.

configurações host.json

A extensão Connector não requer definições específicas de cada conector no ficheirohost.json quando utiliza as predefinições.

As secções seguintes mostram as definições opcionais para cada modo de entrega.

Modo de sondagem

Configure as definições opcionais de sondagem em host.jsonextensions.connector ficheiro. Por exemplo, a seguinte configuração limita o atraso entre sondagens quando não há eventos disponíveis a um segundo:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "maxPollingInterval": "00:00:01"
    }
  }
}
Property Predefinição Description
defaultMaxBatchSize 1 Eventos máximos por invocação quando a função não especifica uma sobreposição positiva do tamanho do lote. Os valores válidos são de 1 a 32. Valores superiores a 1 requerem que o lote esteja ativado.
defaultMaxConcurrentCalls 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. Deve ser positivo. Não se aplica a invocações em lote.
defaultTargetPendingEventThreshold 16 Segmente eventos pendentes por instância para escalamento baseado em alvo quando o tempo de execução não fornece um alvo de concorrência. Deve ser positivo. Independente do tamanho do lote e da concorrência da invocação.
maxPollingInterval "00:00:30" Atraso máximo entre sondagens quando não há eventos disponíveis. Deve ser pelo menos um segundo. Não controla com que frequência o conector verifica o serviço de origem.
maxLinkedOutputSizeInBytes 104857600 (100 MiB) Máximo de bytes descarregados por evento ligado de saída. Deve ser positivo. Não se aplica às respostas de sondagens em linha. Isto é um guardrail de download, não uma garantia de tamanho de carga útil suportada.

As sobreposições positivas por função têm precedência sobre as correspondentes predefinições do host. O tempo de execução pode substituir o alvo de escala sem alterar o tamanho do lote ou a concorrência do ouvinte. Os lotes são processados um de cada vez por ouvinte. Para as opções específicas de idioma, consulte Modo de sondagem.

Os eventos de saída ligada são descarregados pelo host e normalizados para a forma normal da carga útil. São invocados um evento de cada vez atrás de um limitador a nível de host, mesmo quando a ligação permite o batching.

Aumentar maxLinkedOutputSizeInBytes pode esgotar a memória do hospedeiro ou do trabalhador. Valide a carga de trabalho com base no tamanho do seu alojamento antes de aumentá-lo; o padrão não estabelece um limite de tamanho de carga útil suportado.

Modo Webhook

A autenticação por chave de sistema predefinida não requer definições específicas do conector em host.json. Se a autenticação integrada do App Service validar callbacks, pode definir extensions.connector.system.webhookAuthorizationLevel para Anonymous desativar a verificação redundante da chave do sistema.

Use Anonymous apenas quando outra camada de autenticação validar pedidos antes de chegarem ao anfitrião de Funções. Para detalhes de configuração e um exemplo completo, consulte Autenticação incorporada.

Utilizar SDKs de Conectores no seu código

O Connector SDK permite que a sua função chame operações de conector como ações de saída. A superfície cliente utiliza o mesmo conector gerido subjacente no Espaço de Nomes do Conector que os triggers utilizam, pelo que um único conector gerido pode alimentar tanto os triggers de entrada como as chamadas de saída da mesma conta de serviço.

Autenticar callbacks de webhook de entrada não concede à aplicação de funções permissão para fazer chamadas de SDK de saída. Para uma função ativada por webhook que também faz chamadas ao SDK, conceda à identidade gerida da aplicação (implementada) ou identidade de programador (local) uma política de acesso a cada ligação de conectores geridos usada por essas chamadas.

Para o sondamento, a identidade gerida da aplicação de funções ou a identidade do programador já necessita de uma política de acesso à ligação. Se o cliente SDK usar essa mesma identidade e ligação, a política existente também permite chamadas SDK; não é necessária atribuição adicional de política de acesso.

Tanto as funções de polling como as de webhook devem passar uma credencial ao cliente SDK, conforme mostrado abaixo.

No .NET, cada conector inclui um cliente com tipo definido (por exemplo, Office365Client, Office365UsersClient, TeamsClient) em Azure.Connectors.Sdk.{Service}. O construtor cliente recolhe o URL de execução da ligação e uma credencial.

O seguinte padrão é retirado do exemplo do Teams de pesquisa de utilizador por e-mail de ponta a ponta:

using Azure.Core;
using Azure.Identity;
using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365Users;
using Azure.Connectors.Sdk.Teams;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions
{
    ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID")
});

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddSingleton<TokenCredential>(credential);

        services.AddSingleton(sp => new Office365Client(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new Office365UsersClient(
            new Uri(Environment.GetEnvironmentVariable("OFFICE365USERS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));

        services.AddSingleton(sp => new TeamsClient(
            new Uri(Environment.GetEnvironmentVariable("TEAMS_CONNECTION_RUNTIME_URL")!),
            sp.GetRequiredService<TokenCredential>()));
    })
    .Build();

host.Run();

Este exemplo cria um DefaultAzureCredential, regista-o como um TokenCredential, e passa-o para o construtor de cada cliente SDK através sp.GetRequiredService<TokenCredential>()de . Localmente, a credencial pode usar o seu login de programador; no Azure, pode usar a identidade gerida da aplicação funcional. Definir AZURE_CLIENT_ID para o ID de cliente de uma identidade gerida atribuída pelo utilizador associada à aplicação de funções. Deixe-o sem definir para uma identidade atribuída pelo sistema ou início de sessão por programador local.

As definições *_CONNECTION_RUNTIME_URL apontam para o endpoint de tempo de execução por conexão no espaço de nomes do conector. Introduza os clientes na sua função e chame métodos com tipo definido, como UserProfileAsync, GetEmailsAsync ou FlagAsync. Também pode chamar clientes do SDK a partir de acionadores que não sejam conectores (por exemplo, um acionador HTTP que faz publicações no Teams).

O excerto simplificado seguinte do exemplo email-para-equipas utiliza o injetado Office365Client para sinalizar um email para seguimento. Chame este assistente a partir do código de processamento da sua função com o ID da mensagem do email:

using Azure.Connectors.Sdk.Office365;
using Azure.Connectors.Sdk.Office365.Models;

public class ProcessEmail(Office365Client office365Client)
{
    public async Task FlagEmailAsync(string messageId)
    {
        await office365Client.FlagAsync(
            messageId: messageId,
            input: new UpdateEmailFlag { Flag = new { flagStatus = "flagged" } },
            originalMailboxAddress: null,
            cancellationToken: default);
    }
}

Em Python, azure-connectors fornece clientes tipados como Office365Client e TeamsClient. Passe o URL de execução por ligação e uma credencial ao construtor do cliente. Para autenticação do Microsoft Entra ID, utilize uma credencial assíncrona como azure.identity.aio.DefaultAzureCredential. Aguarde as operações do SDK.

Em Node.js, @azure/connectors fornece clientes tipados como Office365Client e TeamsClient. Passe o URL de execução por ligação e uma credencial, como DefaultAzureCredential from @azure/identity, ao construtor do cliente. Aguarde as operações do SDK.