Use conectores gerenciados no Azure Functions

Ao usar conectores gerenciados, suas funções podem reagir a eventos e operações de chamada em serviços como Microsoft 365, Microsoft Teams, SharePoint e muitos sistemas de terceiros sem precisar escrever código de configuração de webhook ou gerenciar tokens OAuth. O Azure Functions se integra ao Azure Connector Namespace para fornecer um gatilho e um SDK que permitem que você se concentre na lógica de negócios, enquanto o Azure Connector Namespace cuida de webhooks, autenticação e novas tentativas.

Como os conectores aprimoram Funções

Um namespace de conectores adiciona duas capacidades ao modelo de programação de Funções:

• Gatilhos de conector
  Uma função é executada quando ocorre um evento em um serviço externo, como um novo e-mail no Microsoft 365, um arquivo adicionado ao SharePoint ou uma mensagem postada no Teams. O runtime expõe uma associação connectorTrigger que recebe callbacks de webhook do namespace do conector.
• Ações do Connector SDK
  O código da sua função invoca operações de conectores por meio de clientes do SDK. O SDK cobre conectores gerenciados como Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint e OneDrive. Conectores gerenciados que ainda não possuem modelos SDK podem ser chamados como endpoints HTTP.

Você pode usar conectores gerenciados junto com gatilhos e vinculações clássicas de Funções, como HTTP, timer, queue, Barramento de Serviço, Event Grid e Durable Functions.

Visualizar disponibilidade

Quando usar conectores

Use conectores quando suas funções precisam interagir principalmente com serviços externos, em vez de rodar lógica personalizada complexa. Considere estas maneiras de usar conectores gerenciados em seus aplicativos de função:

• Reagir a eventos externos
  Seu app deve lidar com eventos gerados por serviços conectados externamente (novos e-mails, convites de calendário, arquivos, itens da lista, atividade do Teams), mas você não quer gastar esforço codificando registros de webhooks, validação de handshake e atualizações OAuth. Considere um caso em que sua função é executada para processar novos e-mails entregues em uma pasta Office 365 Outlook monitorada, classifica a mensagem, chama a Conector do Office 365 para enriquecimento e sinaliza ou move o e-mail. Todo esse trabalho distribuído é feito pelo aplicativo sem jamais se preocupar com tokens de atualização, manipulados pelo namespace do conector.

• Substituir clientes de serviço personalizados
  O código da sua função já chama APIs do Microsoft 365 ou de terceiros por meio de clientes HTTP personalizados, o que exige que você gerencie segredos, escopos e políticas de repetição em várias conexões, o que pode rapidamente se transformar em um ônus de manutenção. Você pode, em vez disso, usar os clientes tipados nos SDKs de conectores diretamente no seu código de função e deixar os conectores gerenciados cuidarem das conexões sozinhos.

• Aproveite uma implantação de aplicativo existente
  Você já construiu um projeto de aplicativo de funções orientado a eventos com pipeline de implantação e ferramentas de monitoramento. Você pode usar conectores gerenciados para adicionar uma nova função externa baseada em gatilhos de serviço no mesmo projeto e aproveitar a infraestrutura existente. Por exemplo, um aplicativo de funções que antes dependia de filas de mensagens ou Logic Apps agora pode reagir diretamente à atividade do Teams e se conectar ao Office 365 para verificações dentro da organização e consultas de gerenciadores.

• Fluxos de trabalho autônomos
  Você está criando fluxos de trabalho nos quais uma função recebe um evento, raciocina com um modelo de IA e, em seguida, executa ações em um serviço externo por meio de uma operação de conector. Você pode aproveitar o runtime de agentes sem servidor para programar o fluxo de trabalho de agente, e ainda aproveitar gatilhos baseados no conector gerenciados e os SDKs de conector gerenciados.

• Controle centrado no código com integração gerenciada
  Você quer conectores gerenciados para simplificar a comunicação de entrada e saída com um serviço externo, mas prefere um modelo de programação centrado em código e controle total sobre a orquestração, incluindo ramificações, o gerenciamento da autenticação entre as etapas e a reutilização das suas bibliotecas existentes.

  Dica

  Quando a carga de trabalho é pura orquestração entre conectores, sem código personalizado, o Logic Apps Standard continua sendo a escolha mais simples. Para mais informações, veja Relação com outras opções de integração com o Azure.

Relação com outras opções de integração Azure

Conectores gerenciados no Azure Functions são aditivos. A escolha certa depende de quanto código personalizado a carga de trabalho exige e se a equipe prefere um designer visual ou código.

Um único aplicativo de funções pode combinar todos os três padrões. Você pode adicionar um gatilho de conector a um aplicativo existente acionado por HTTP e adotar clientes SDK de forma incremental.

Pacotes e pré-requisitos

Cada linguagem compatível tem um pequeno conjunto de pacotes que incluem a associação de gatilho e os clientes de SDK do conector.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector --prerelease
dotnet add package Azure.Connectors.Sdk --prerelease

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

pip install "azure-functions>=2.2.0b4"
pip install azurefunctions-extensions-connectors

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

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

Gatilhos baseados em conectores

Um gatilho baseado em conector gerenciado executa a função quando ocorre um evento no serviço conectado. O namespace do conector entrega o evento ao aplicativo de função via HTTPS usando o ponto de extremidade de webhook da extensão do conector:

POST /runtime/webhooks/connector?functionName={FunctionName}&code={connector_extension_key}

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

A configuração do gatilho no namespace do conector armazena essa URL de retorno de chamada e envia a chave do sistema em cada retorno de chamada. O runtime Functions valida a chave antes de executar sua função. Para uma configuração sem usar segredos compartilhados, você pode colocar a autenticação interna do Serviço de Aplicativo à frente do aplicativo de funções e validar um token de identidade gerenciada do namespace do conector. Veja exemplo .NET: autenticação embutida com identidade gerenciada para o padrão completo.

As cargas de solicitação carregam o corpo do evento mais um conjunto de x-ms-* cabeçalhos que identificam a configuração do gatilho, a conexão, o tipo de evento e uma ID de correlação. Quando o conector gerenciado tem um modelo SDK, o runtime desserializa diretamente o payload nesse modelo. Para conectores gerenciados sem SDKs de cliente, sua função recebe o corpo JSON bruto.

O exemplo a seguir mostra uma função que é acionada quando um novo email chega em uma caixa de correio Office 365 Outlook. O registro do gatilho é por idioma; a configuração do gatilho no namespace do conector é a mesma em todos os casos.

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

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

    public OnNewEmail(ILogger<OnNewEmail> logger) => _logger = logger;

    [Function("OnNewEmail")]
    public IActionResult Run(
        [ConnectorTrigger()] Office365OnNewEmailTriggerPayload payload)
    {
        var emails = payload?.Body?.Value ?? [];
        foreach (var email in emails)
        {
            _logger.LogInformation(
                "Received email from {From} with subject '{Subject}'.",
                email.From, email.Subject);
        }

        return new OkResult();
    }
}

import azure.functions as func
import json
import logging

app = func.FunctionApp()

@app.function_name(name="OnNewEmail")
@app.connector_trigger(arg_name="payload")
def on_new_email(payload: str) -> None:
    data = json.loads(payload)
    emails = data.get("body", {}).get("value", [])
    for email in emails:
        logging.info(
            "Received email from %s with subject '%s'.",
            email.get("from"), email.get("subject"))

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

app = func.FunctionApp()

@app.function_name(name="OnNewEmail")
@app.connector_trigger(arg_name="email")
def on_new_email(email: office365.ClientReceiveMessage) -> None:
    logging.info(
        "Received email from %s with subject '%s'.",
        email.from_, email.subject)

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

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        for (const email of context.emails) {
            invocationContext.log(
                `Received email from '${email.from}' with subject '${email.subject}'.`,
            );
        }
    },
});

import { app, InvocationContext } from '@azure/functions';

app.connectorTrigger('OnNewItem', {
    handler: async (payload: unknown, context: InvocationContext) => {
        const data = typeof payload === 'string' ? JSON.parse(payload) : payload;
        const items: Record<string, unknown>[] = (data as any)?.body?.value ?? [];
        for (const item of items) {
            context.log(`Item ID: ${item.Id}`);
        }
    },
});

Você cria a configuração do gatilho no namespace do conector usando a CLI do Azure, ARM ou Bicep. Essa etapa faz parte da plataforma de conectores e está documentada no conjunto de conteúdo de conectores. O Functions não vem com seus próprios comandos de configuração para registro de gatilhos.

Autentique suas funções em um namespace de conectores

O modelo padrão de autenticação usa uma chave de sistema compartilhada (connector_extension) que o namespace do conector apresenta em cada callback. No entanto, o escopo das chaves compartilhadas não pode ser definido por gatilho e exige rodízio coordenado entre o aplicativo de funções e o namespace do conector. Para cargas de trabalho de produção, use em vez disso a autenticação integrada do App Service (também chamada de Easy Auth) com uma identidade gerenciada.

Nesse padrão, o namespace do conector usa a própria identidade gerenciada atribuída pelo usuário ou pelo sistema para solicitar um token do Entra ID para cada retorno de chamada. O aplicativo de funções valida esse token, incluindo o público-alvo, o emissor e a ID do objeto do chamador antes que qualquer solicitação chegue ao host do Functions. Sem chaves compartilhadas, sem segredos do cliente, em qualquer lugar.

Para um exemplo de funcionamento de ponta a ponta, veja este repositório: functions-connectors-net-builtinauth.

Configuração do aplicativo de funções

A autenticação interna é executada no limite de trabalho do Serviço de Aplicativo, antes que o runtime do Functions obtenha a solicitação. Você o configura por meio da authsettingsV2 propriedade ARM ou equivalente em Bicep.

O aplicativo de funções também precisa de uma identidade gerenciada atribuída pelo usuário federada ao registro do aplicativo Entra. A autenticação interna usa essa FIC ( credencial de identidade federada ) para criar declarações de cliente para o aplicativo Entra sem armazenar um segredo do cliente. O padrão bicep define clientSecretSettingName como uma configuração de aplicativo que contém a ID do cliente do MI atribuída pelo usuário, informando a autenticação interna para usar FIC em vez de um segredo.

Como a autenticação interna já valida todas as solicitações, você pode desativar a verificação redundante da chave do sistema em host.json, que teria a seguinte aparência neste fragmento JSON:

{
    ...
    "extensions": {
        "connector": {
            "system": {
                "webhookAuthorizationLevel": "Anonymous"
            }
        }
    }
}

Configuração do namespace do conector

O namespace do conector deve ter uma identidade gerenciada atribuída pelo sistema ou pelo usuário habilitada e anexada. Ao criar a configuração do trigger, especifique authentication.type = ManagedServiceIdentity e authentication.identity = <resource-id-of-managed-identity> para uma identidade atribuída pelo usuário ou omita identity uma identidade atribuída pelo sistema. Também especifique authentication.audience = <entra-app-client-id> para que o runtime do conector saiba qual público solicitar no token.

O runtime do conector usa essa identidade gerenciada para gerar um token do Entra ID em cada retorno de chamada. Nesse token, iss (emissor) é o locatário, aud (audiência) é a ID do cliente do aplicativo Entra e oid (ID do objeto) é a ID principal da identidade. A autenticação interna valida os três.

O recurso de namespace do conector também precisa de acesso à conexão, como uma conexão office365. Conceda esse acesso por meio de uma política de acesso que lista o ID principal da identidade gerenciada. O arquivo bicep de exemplo mostra a configuração completa tanto para a identidade do namespace quanto para a política de acesso à conexão.

O que é imposto

A autenticação integrada valida tokens na ordem:

1. Presença de token – token ausente ou expirado → 401
2. Assinatura - verificada com base no JWKS do emissor para seu locatário
3. iss (emissor) – Deve corresponder openIdIssuer
4. aud (audiência) – deve estar em allowedAudiences
5. oid (ID da entidade/objeto) - deve corresponder a uma das identidades em allowedPrincipals.identities. Qualquer outra identidade → 403

Como essa verificação é executada na borda do Serviço de Aplicativo, o código da função jamais vê uma solicitação que não tenha vindo da identidade gerenciada do namespace do conector. Você não precisa de nenhum código de aplicação para a verificação de acesso.

Fluxo de autenticação

┌─────────────────────────────────────────────────────────────────┐
│  Connector namespace  (westcentralus)                           │
│  • System-assigned or user-assigned managed identity enabled    │
│  • Trigger config: authentication.type = ManagedServiceIdentity │
│                    authentication.audience = <Entra app ID>     │
│                    callbackUrl = https://<func>/runtime/…       │
└────────────────────────┬───────────────────────────────────────┘
                         │
                         │  POST callbackUrl
                         │  Authorization: Bearer <AAD token>
                         │     iss = your tenant
                         │     aud = Entra app clientId
                         │     oid = managed identity principalId
                         ▼
┌──────────────────────────────────────────────────────────────┐
│  Function App  (any region)                                  │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ Built-in authentication  (App Service edge)          │   │
│   │   • Validates signature, iss, aud, exp               │   │
│   │   • Checks oid ∈ allowedPrincipals.identities        │   │
│   │   → No token  → 401                                  │   │
│   │   → Wrong oid → 403                                  │   │
│   └────────────────────┬─────────────────────────────────┘   │
│                        │ pass                                │
│                        ▼                                     │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ /runtime/webhooks/connector                          │   │
│   │   (webhookAuthorizationLevel = Anonymous)            │   │
│   └────────────────────┬─────────────────────────────────┘   │
│                        ▼                                     │
│   ┌──────────────────────────────────────────────────────┐   │
│   │ Your function(payload)                               │   │
│   └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                         ▲
                         │ FIC (federated identity credential)
         ┌───────────────┴────────────────┐
         │  Entra app registration         │
         │  (federated to function-app MI) │
         └─────────────────────────────────┘

Conteúdo relacionado

• Autenticação e autorização no Serviço de Aplicativo do Azure e Azure Functions
• Configurar seu app de Serviço de Aplicativo ou Azure Functions para usar as credenciais do Microsoft Entra
• Configuração baseada em arquivo na autenticação do Serviço de Aplicativo do Azure
• Federação de identidade de carga de trabalho no Microsoft Entra ID
• Identidades gerenciadas para os recursos do Azure

Usando conectores em seu código

O SDK do conector permite que sua função chame operações do conector como ações de saída. A superfície cliente usa o mesmo conector gerenciado subjacente no namespace do conector que dispara o uso, logo, um único conector gerenciado pode alimentar tanto os gatilhos de entrada quanto as chamadas de saída para a mesma conta de serviço.

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();

Artigos relacionados

• Exemplos de conectores do Azure Functions (índice canônico)
• Exemplo .NET de ponta a ponta: e-mail → pesquisa de usuário → Teams
• .NET exemplo: autenticação interna com identidade gerenciada
• Repositório da extensão do conector do Azure Functions
• Mapeamento de assinaturas de operações para o Azure Functions
• Visão geral dos conectores do Azure
• O que é o namespace do conector Azure?
• Runtime de agentes sem servidor no Azure Functions