Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 de Conectores amplia essas integrações por meio de conectores gerenciados no Namespace Azure Conectores, permitindo que suas funções recebam eventos de sistemas de negócios e plataformas de dados como Office 365 Outlook, SharePoint Online, Microsoft Teams e Dataverse.
Para conectores gerenciados da Microsoft e de terceiros disponíveis, consulte a referência de conectores.
Note
Os conectores gerenciados suportam os planos de hospedagem Flex Consumption, Dedicated e Elastic Premium para aplicativos Linux Function em todas as regiões. A disponibilidade para aplicativos para Windows é limitada hoje.
Flex Consumption é o plano de hospedagem recomendado para funções acionadas pelo conector.
Note
O Connector Trigger não é suportado atualmente para esta linguagem.
| Para | Usar |
|---|---|
| Executar uma função em resposta a um evento em um serviço conectado | Gatilho do Conector, fornecido pela Extensão do Conector |
| Executar uma ação em um serviço conectado a partir do código de função | SDK de conectores Azure, disponível para .NET, Node.jse Python |
Você pode usar ambos juntos: o Gatilho do Conector inicia sua função, e o SDK executa ações nos serviços conectados. Se você precisar apenas executar ações, use o SDK sem a Extensão do Conector.
Para mais informações sobre conectores gerenciados, quando utilizá-los e disponibilidade de recursos, consulte Use managed connectors in Azure Functions.
Gatilho de Conector no Azure Functions
Uma função acionada por conector utiliza os seguintes componentes:
| Component | Responsabilidade |
|---|---|
| Espaço de nomes do conector | Os hosts gerenciavam conexões de conectores e configurações de disparo. |
| Conexão gerenciada por conector | Autentica para o serviço externo e gerencia a conectividade específica do serviço. |
| Configuração de gatilho | Seleciona o evento do conector, parâmetros de operação e modo de entrega. |
| Extensão do Azure Functions Connector | Recebe eventos do Namespace do Conector, invoca a função e vincula o corpo do evento ao parâmetro da função. |
| Azure Connectors SDK (opcional) | Oferece modelos opcionais de payload fortemente tipado e clientes para invocar operações gerenciadas de conectores, como enviar um e-mail ou criar um arquivo SharePoint. |
Um conector gerenciado pode suportar múltiplos eventos, e cada evento que você deseja monitorar precisa de sua própria configuração de gatilho. Por exemplo, o conector de Office 365 Outlook suporta eventos como a chegada de um novo e-mail, um e-mail sendo sinalizado, um evento de calendário sendo criado ou um evento de calendário sendo modificado. Crie uma configuração de gatilho separada para cada evento que você deseja usar para executar uma função.
Para exemplos de código, consulte Exemplos de gatilhos de conector e Uso de SDKs de conectores no seu código.
Escolha um modo de entrega
Conectores gerenciados suportam webhook e entrega de sondamento. Escolha um modo com base na latência, capacidade de processamento, rede e necessidades de autenticação do seu cenário:
| Feature | Sondagem | Webhook |
|---|---|---|
| Entrega de eventos e latência | O host de Funções recupera eventos por meio de solicitações de sondagem de saída. Os eventos esperam até que o anfitrião faça a votação para eles. | O Espaço de Nomes do Conector envia eventos para o endpoint de callback do aplicativo de função assim que ele os detecta do serviço de origem, sem esperar que o aplicativo faça a consulta. Isso 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 conforme a capacidade de processamento fica disponível. Combine limites de escala-saída de aplicativos com configurações de concorrência de sondagem para limitar o processamento simultâneo e proteger bancos de dados ou APIs posteriores. 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 do aplicativo. Limites de escala podem levar a callbacks limitados ou falhados quando a demanda 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. Você pode restringir o acesso de entrada ao aplicativo de funções enquanto permite solicitações de saída para o endpoint de sondagem do Connector Namespace. | O Namespace do Conector deve ser capaz de alcançar o endpoint de callback do aplicativo. As restrições de entrada devem permitir essas solicitações. |
| Autenticação de identidade gerenciada | O host de Funções pode usar a identidade gerenciada atribuída pelo sistema ou pelo usuário do aplicativo de funções para receber e reconhecer eventos. Conceda a essa identidade uma política de acesso na conexão do conector gerenciada. | Para callbacks autenticados com Microsoft Entra ID, o Connector Namespace usa sua identidade gerenciada. Configure a autenticação integrada do App Service no aplicativo da função receptora para validar os tokens. A autenticação padrão por webhook usa a chave de sistema de extensão do Conector. |
Dependendo do seu plano de hospedagem, você pode restringir o acesso de entrada ao aplicativo de função usando endpoints privados ou restrições de acesso de entrada, incluindo restrições baseadas em IP ou de endpoint de serviço, sem impedir o sondamento. O aplicativo ainda deve ser capaz de fazer solicitações HTTPS de saída para o endpoint de sondagem do Connector Namespace. Separadamente, a identidade gerenciada configurada do aplicativo de função deve ter uma política de acesso na conexão do conector gerenciado.
O modo de entrega de eventos controla como os eventos chegam ao host de Funções a partir do Namespace do Conector, não como o conector gerenciado detecta mudanças 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 escalonamento da pesquisa é 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 sondamento e as configurações de ajuste, consulte Escalonamento baseado em alvo de conectores gerenciados.
Ambos os modos usam [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 de worker isolado .NET. Para informações sobre versões suportadas de .NET em versões de runtime do Azure Functions, veja 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 sua função só precisar executar ações em serviços externos e não precisar ser acionada por eventos, use apenas o SDK dos Azure Connectors. Você não precisa do pacote de extensão Connector.
Adicione o SDK do Azure Connectors:
dotnet add package Azure.Connectors.Sdk
Para conectores populares, o SDK fornece clientes fortemente tipados para invocar ações de conectores a partir de suas funções; consulte a referência do SDK do Azure Connectors para .NET API.
Instalar a extensão
Use Node.js 24 ou posterior. Ambos os modos de entrega usam assistentes de registro 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"
Esses pacotes oferecem a seguinte funcionalidade:
-
@azure/functions fornece o registro base
connectorTrigger, que recebe a entrada do gatilho como um tipo genérico que padrão éunknown. - @azure/functions-extensions-connectors envolve a entrada em um contexto de gatilho de conector normalizado e fornece contextos tipados para operações de conectores suportadas.
- @azure/connectors, o SDK Azure Connectors para Node.js, fornece os modelos de carga útil usados por esses contextos e clientes para chamar operações de conectores.
Configure o pacote de extensões no arquivohost.json . O pacote fornece a extensão host do Conector para ambos os modos de entrega:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
SDK de Azure Connectors
Se sua função só precisar executar ações em serviços externos e não precisar ser acionada por eventos, instale apenas o SDK Azure Connectors para Node.js. Você não precisa dos pacotes de gatilho do Conector.
npm install "@azure/connectors@latest"
O SDK fornece clientes fortemente tipados para invocar ações de conectores a partir de suas funções.
Para versões atuais de pacotes e projetos completos, veja os exemplos de conectores do Azure Functions para TypeScript.
Ambos os modos de entrega utilizam o @app.connector_trigger decorador. Para exemplos, veja Exemplos de gatilhos de conectores.
Instalar a extensão
Adicione os seguintes pacotes ao requirements.txt:
azure-functions>=2.4.0
azurefunctions-extensions-connectors>=1.0.0
Note
Para versões de 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
stroubytes, ou lotes de sondagem atyping.List[str]outyping.List[bytes]. - O pacote azurefunctions-extensions-connectors integra o Azure Connectors SDK para Python e registra conversores para anotações específicas do SDK de operação suportadas. Por exemplo,
emails: list[office365.GraphClientReceiveMessage], ondeoffice365é importado deazurefunctions.extensions.connectors, recebe objetos do modelo de email para a operação Office 365 OutlookOnNewEmailV3.
Configure o pacote de extensões no arquivohost.json . O pacote fornece a extensão host do Conector para ambos os modos de entrega:
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle",
"version": "[4.*, 5.0.0)"
}
}
SDK de Azure Connectors
Se sua função só precisar executar ações em serviços externos e não precisar ser acionada por eventos, instale apenas o SDK Azure Connectors para Python. Você não precisa dos pacotes de gatilho do Conector.
python -m pip install "azure-connectors>=1.0.0"
O SDK fornece clientes fortemente tipados para invocar ações de conectores a partir de suas funções.
Para versões atuais de pacotes e projetos completos, veja os exemplos de conectores Azure Functions para Python.
configurações de host.json
A extensão Connector não exige configurações específicas de cada conector no arquivo host.json quando você usa os valores padrão.
As seções a seguir mostram as configurações opcionais para cada modo de entrega.
Modo de votação
Configure as configurações opcionais de sondagem em host.jsonextensions.connector arquivo. Por exemplo, a seguinte configuração limita o atraso entre as sondagens quando nenhum evento está disponível a um segundo:
{
"version": "2.0",
"extensions": {
"connector": {
"maxPollingInterval": "00:00:01"
}
}
}
| Property | Padrão | Description |
|---|---|---|
defaultMaxBatchSize |
1 |
Eventos máximos por invocação quando a função não especifica uma substituição positiva de tamanho de lote. Os valores válidos são de 1 a 32. Valores maiores que 1 exigem que o lotamento seja habilitado. |
defaultMaxConcurrentCalls |
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 positivo. Não se aplica a invocações em lote. |
defaultTargetPendingEventThreshold |
16 |
Segmente eventos pendentes por instância para escalonamento 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 de invocação. |
maxPollingInterval |
"00:00:30" |
Atraso máximo entre as pesquisas 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) |
Bytes máximos baixados por evento vinculado de saída. Deve ser positivo. Isso não se aplica às respostas de pesquisas inline. Isso é uma guarda de download que não é uma garantia de tamanho de carga suportada. |
Sobrescrituras positivas por função têm precedência sobre os padrões correspondentes do host. O runtime pode substituir o alvo de escalamento 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 do idioma, consulte Modo de votação.
Eventos de saída vinculada são baixados pelo host e normalizados para a forma normal da carga útil. Eles são invocados um evento por vez atrás de um limitador em todo o host, mesmo quando a vinculação permite o batching.
Aumentar maxLinkedOutputSizeInBytes pode esgotar a memória do hospedeiro ou do trabalhador. Valide a carga de trabalho no tamanho da sua hospedagem antes de aumentá-la; o padrão não estabelece um limite de tamanho de carga útil suportado.
Modo Webhook
A autenticação padrão por chave de sistema não requer configurações específicas de conector em host.json. Se a autenticação integrada do App Service validar callbacks, você pode definir extensions.connector.system.webhookAuthorizationLevel como Anonymous para desativar a verificação redundante da chave de sistema.
Use Anonymous somente quando outra camada de autenticação validar as solicitações antes que cheguem ao host de Funções. Para detalhes de configuração e um exemplo completo, consulte Autenticação embutida.
Usando SDKs de Conector no seu código
O Connector SDK permite que sua função chame operações de conector como ações de saída. A superfície cliente usa o mesmo conector gerenciado subjacente no Namespace de Conectores que aciona o uso, de modo que um único conector gerenciado pode alimentar tanto gatilhos de entrada quanto chamadas de saída para a mesma conta de serviço.
Autenticar callbacks de webhook de entrada não concede ao aplicativo de funções permissão para fazer chamadas de SDK de saída. Para uma função acionada por webhook que também faz chamadas de SDK, conceda à identidade gerenciada (implantada) ou à identidade do desenvolvedor (local) da função uma política de acesso a cada conexão de conector gerenciado usada por essas chamadas.
Para sondamento, a identidade gerenciada do aplicativo de função ou a identidade do desenvolvedor já precisa de uma política de acesso à conexão. Se o cliente SDK usar essa mesma identidade e conexã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 quanto as de webhook devem passar uma credencial ao cliente SDK, conforme mostrado abaixo.
Em .NET, cada conector envia um cliente tipado (por exemplo, Office365Client, Office365UsersClient, TeamsClient) em Azure.Connectors.Sdk.{Service}. O construtor cliente recebe a URL de runtime da conexão e uma credencial.
O padrão a seguir é do exemplo do Teams para pesquisa de usuário por email 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, registra-o como TokenCredentialum , e o passa para o construtor de cada cliente SDK através de sp.GetRequiredService<TokenCredential>(). Localmente, a credencial pode usar seu login de desenvolvedor; no Azure, ela pode usar a identidade gerenciada do aplicativo de funções. Defina AZURE_CLIENT_ID para o ID do cliente de uma identidade gerenciada atribuída pelo usuário anexada ao aplicativo de funções. Deixe-o sem configuração para uma identidade atribuída pelo sistema ou login de desenvolvedor local.
As configurações de *_CONNECTION_RUNTIME_URL apontam para o ponto de extremidade de runtime por conexão no namespace do conector. Injete os clientes na sua função e chame métodos tipados, como UserProfileAsync, GetEmailsAsync ou FlagAsync. Você também pode chamar clientes do SDK de gatilhos não conectores (por exemplo, um gatilho HTTP que é colocado no Teams).
O trecho simplificado a seguir do exemplo de e-mail-para-equipes usa o injetado Office365Client para sinalizar um e-mail para acompanhamento. Chame este auxiliar a partir do código de processamento da sua função com o ID da mensagem do e-mail:
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 a URL de runtime por conexão e uma credencial para o construtor do cliente. Para autenticação do Microsoft Entra ID, use 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 a URL de runtime por conexão e uma credencial, como DefaultAzureCredential from @azure/identity, para o construtor do cliente. Aguarde as operações do SDK.