Use conectores geridos no Funções do Azure

Ao usar conectores geridos, as 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 escrever código de configuração de webhook ou gerir tokens OAuth. O Funções do Azure integra-se com o Azure Connector Namespace para fornecer um acionador e um SDK que lhe permite concentrar-se na lógica de negócio, enquanto o Azure Connector Namespace trata de webhooks, autenticação e novas tentativas.

De que forma os conectores potenciam as funções

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

• Acionadores de conector
  Uma função é executada quando ocorre um evento num serviço externo, como um novo email no Microsoft 365, um ficheiro adicionado ao SharePoint ou uma mensagem publicada no Teams. O ambiente de execução expõe uma associação connectorTrigger que recebe chamadas de retorno de webhook do espaço de nomes do conector.
• Ações do SDK do Conector
  O seu código da função invoca operações do conector através de clientes do SDK. O SDK cobre conectores geridos como Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint e OneDrive. Os conectores geridos que ainda não têm modelos no SDK podem ser invocados como pontos finais HTTP.

Pode utilizar conectores geridos juntamente com gatilhos e associações clássicos do Functions, como HTTP, temporizador, fila, Service Bus, Event Grid e Durable Functions.

Disponibilidade de pré-visualizações

Quando usar conectores

Usa conectores quando as tuas funções precisam principalmente de interagir com serviços externos em vez de correr lógica personalizada complexa. Considere estas formas de usar conectores geridos nas suas aplicações funcionais:

• Reagir a eventos externos
  A sua aplicação tem de gerir eventos gerados por serviços ligados externamente (novos emails, convites de calendário, ficheiros, itens da lista, atividade no Teams), mas não quer gastar o esforço a codificar registos de webhooks, validação de handshake e atualizações OAuth. Considere um caso em que a sua função é executada para processar novos emails entregues numa pasta de Office 365 Outlook monitorizada, classifica a mensagem, chama a conector do Office 365 para enriquecimento e sinaliza ou move o email. Todo este trabalho distribuído é realizado pela sua aplicação sem nunca ter de se preocupar com os tokens de renovação, que são tratados pelo espaço de nomes do seu conector.

• Substituir clientes de serviços personalizados
  O código da sua função já faz chamadas ao Microsoft 365 ou a APIs de terceiros através de clientes HTTP personalizados, o que exige gerir segredos, âmbitos e políticas de repetição em múltiplas ligações, podendo rapidamente tornar-se um ónus de manutenção. Pode, em vez disso, usar os clientes tipados nos SDKs de conectores diretamente no seu código de função e deixar que os conectores geridos tratem das ligações por si próprios.

• Tire partido de uma implementação existente de uma aplicação
  Já criaste um projeto de aplicação de funções orientado a eventos com um pipeline de implementação e ferramentas de monitorização. Pode usar conectores geridos para adicionar uma nova função externa baseada em gatilhos de serviço no mesmo projeto e tirar partido da infraestrutura existente. Por exemplo, uma aplicação de funções que antes dependia de filas de mensagens ou Aplicações Lógicas pode agora reagir diretamente à atividade do Teams e ligar-se ao Office 365 para verificações dentro da organização e consultas de gestores.

• Fluxos de trabalho agenciais
  Estás a criar fluxos de trabalho em que uma função recebe um evento, raciocina recorrendo a um modelo de IA e depois executa uma ação num serviço externo através de uma operação do conector. Pode tirar partido do runtime serverless de agentes para programar o seu fluxo de trabalho agêntico, continuando a beneficiar de acionadores baseados em conectores geridos e de SDKs de conectores geridos.

• Abordagem centrada no código com integração gerida
  Queres conectores geridos para simplificar a comunicação de entrada e saída com serviços externos, mas preferes um modelo de programação centrada no código e controlo total sobre a orquestração, incluindo ramificações, gestão da autenticação entre etapas e reutilização das bibliotecas existentes.

  Dica

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

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

Os conectores geridos no Funções do Azure são cumulativos. A escolha certa depende da quantidade de código personalizado que a carga de trabalho precisa e se a equipa prefere um designer visual ou código.

Uma única aplicação de função pode combinar os três padrões. Pode adicionar um gatilho de conetor a uma aplicação existente acionada por HTTP e adotar clientes do SDK de forma incremental.

Pacotes e pré-requisitos

Cada linguagem suportada tem um pequeno conjunto de pacotes que incorporam a ligação de gatilhos e os clientes 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

Acionadores baseados em conectores

Um accionador gerido baseado num conector executa a sua função quando ocorre um evento no serviço conectado. O namespace do conector entrega o evento para a sua aplicação de funções via HTTPS usando o endpoint 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 trigger no espaço de nomes do seu conector armazena esse URL de callback e apresenta a chave do sistema em cada callback. O runtime das Funções valida a chave antes de executar a sua função. Para uma configuração sem segredos partilhados, pode colocar a autenticação integrada do App Service à frente da aplicação de funções e validar um token de identidade gerida proveniente do namespace do conector. Veja exemplo .NET: autenticação incorporada com identidade gerida para o padrão completo.

Os payloads do pedido incluem o corpo do evento e um conjunto de x-ms-* cabeçalhos que identificam a configuração do disparador, a ligação, o tipo de evento e um ID de correlação. Quando o conector gerido tem um modelo do SDK, o ambiente de execução desserializa a carga útil diretamente nesse modelo. Para conectores geridos sem SDKs de cliente, a sua função recebe o corpo JSON bruto.

O exemplo seguinte mostra uma função que é ativada quando um novo email chega a uma caixa de correio Office 365 Outlook. O registo do acionador é por idioma; a configuração do acionador no espaço de nomes 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}`);
        }
    },
});

Crias a configuração do gatilho no espaço de nomes 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údos dos conectores. O Functions não fornece os seus próprios comandos de configuração para o registo de gatilhos.

Autentica as tuas funções num espaço de nomes de conectores

O modelo de autenticação por defeito utiliza uma chave de sistema partilhada (connector_extension) que o espaço de nomes do conector apresenta em cada callback. No entanto, as chaves partilhadas não podem ser delimitadas ao nível de cada acionador e exigem uma rotação coordenada entre a aplicação de funções e o espaço de nomes do conector. Para cargas de trabalho de produção, utilize antes a autenticação incorporada do App Service (também conhecida como Easy Auth) com uma identidade gerida.

Neste padrão, o espaço de nomes do conector utiliza a sua própria identidade gerida atribuída pelo sistema ou pelo utilizador para solicitar um token Entra ID para cada callback. A aplicação de funções valida esse token, incluindo o seu destinatário, emissor e o ID de objeto do autor da chamada, antes de qualquer pedido chegar ao host do Functions. Sem chaves partilhadas, sem segredos de clientes, em lado nenhum.

Para um exemplo funcional completo, veja este repositório: functions-connectors-net-builtinauth.

Configuração do aplicativo de função

A autenticação incorporada ocorre no limite do processo de trabalho do App Service, antes de o ambiente de execução do Functions receber o pedido. Configura-o através da authsettingsV2 propriedade ARM ou do respetivo equivalente em Bicep.

A aplicação de funções também necessita de uma identidade gerida atribuída pelo utilizador , federada ao registo da aplicação Entra. A autenticação incorporada utiliza essa credencial de identidade federada (FIC) para criar asserções de cliente para a aplicação Entra sem armazenar um segredo do cliente. O padrão bíceps define clientSecretSettingName uma configuração de aplicação que contém o ID de cliente do MI atribuído pelo utilizador, indicando à autenticação incorporada para usar FIC em vez de um secreto.

Como a autenticação integrada já valida todos os pedidos, pode desativar a verificação redundante da chave de sistema em host.json, que teria o seguinte aspeto como fragmento JSON:

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

Configuração do espaço de nomes do conector

O namespace do conector tem de ter uma identidade gerida, atribuída pelo sistema ou pelo utilizador, ativada e associada. 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 utilizador ou omita identity uma identidade atribuída pelo sistema. Especifique também authentication.audience = <entra-app-client-id> para que o ambiente de execução do conector saiba que público solicitar no token.

O runtime do conector utiliza essa identidade gerida para gerar um token Entra ID em cada callback. Neste token, iss (emissor) é o seu inquilino, aud (público) é o ID do cliente da aplicação Entra, e oid (ID do objeto) é o ID principal da identidade. A autenticação incorporada valida os três.

O recurso do espaço de nomes do conector também precisa de acesso à conexão, tal como uma ligação office365. Conceda este acesso através de uma política de acesso que liste o ID principal da identidade gerida. O ficheiro Bicep de exemplo mostra a configuração completa para a identidade do namespace e para a política de acesso da ligação.

O que é aplicado

A autenticação incorporada valida os tokens por ordem:

1. Presença de token - Token em falta ou expirado → 401
2. Assinatura - Verificada com base no JWKS do emissor para o seu tenant
3. iss (emissor) - Tem de corresponder openIdIssuer
4. aud (audiência) - Tem de estar dentro allowedAudiences
5. oid (ID de objeto/principal) - Deve corresponder a uma das identidades em allowedPrincipals.identities. Alguma outra identidade → 403

Como esta verificação corre na extremidade do App Service, o seu código de função nunca vê um pedido que não tenha vindo da identidade gerida do namespace do conector. Não precisas de qualquer 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 em Serviço de Aplicações do Azure e Funções do Azure
• Configurar o Serviço de Aplicativo ou o aplicativo Funções do Azure para usar a entrada 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 recursos do Azure

Usar conectores no teu código

O SDK do conector permite que a sua função chame operações do 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 desencadeia o uso, pelo que um único conector gerido pode alimentar tanto os gatilhos de entrada como 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

• Amostras de conectores do Funções do Azure (índice canónico)
• Exemplo .NET de ponta a ponta: e-mail → pesquisa de utilizador → Teams
• Exemplo .NET: autenticação incorporada com identidade gerida
• Repositório da extensão do conector do Funções do Azure
• Mapeamento de operações para assinaturas do Funções do Azure
• Descrição geral dos conectores do Azure
• O que é o Azure Connector Namespace?
• Ambiente de execução de agentes serverless no Funções do Azure