Используйте управляемые соединители в Функции Azure

Используя управляемые коннекторы, ваши функции могут реагировать на события и операции вызовов в таких сервисах, как Microsoft 365, Microsoft Teams, SharePoint и многих сторонних системах без написания кода настройки вебхука или управления токенами OAuth. Функции Azure интегрируется с Azure Connector Namespace, предоставляя триггер и пакет SDK, которые позволяют сосредоточиться на бизнес-логике, в то время как Azure Connector Namespace берёт на себя обработку веб-перехватчиков, аутентификацию и повторные попытки.

Как разъёмы улучшают функции

Пространство имён коннекторов добавляет две возможности к модели программирования Functions:

• Триггеры разъёма
  Функция запускается, когда событие происходит во внешнем сервисе, например, новое письмо в Microsoft 365, добавленный файл в SharePoint или сообщение, опубликованное в Teams. Среда выполнения предоставляет привязку connectorTrigger, которая принимает обратные вызовы вебхука из пространства имён connector.
• Действия Connector SDK
  Ваш функциональный код вызывает операции коннектора через клиенты SDK. SDK охватывает управляемые коннекторы, такие как Microsoft 365 Outlook, Microsoft 365 Users, Teams, SharePoint и OneDrive. Управляемые коннекторы, у которых ещё нет SDK-моделей, могут называться HTTP-конечными точками.

Вы можете использовать управляемые коннекторы вместе с классическими триггерами и привязками Functions, такими как HTTP, таймер, очередь, служебная шина, Event Grid и Устойчивые функции.

Доступность предварительной версии

Когда следует использовать соединители

Используйте коннекторы, когда вашим функциям в основном нужно взаимодействовать с внешними сервисами, а не выполнять сложную пользовательскую логику. Рассмотрите следующие способы использования управляемых коннекторов в ваших функциональных приложениях:

• Реагировать на внешние события
  Ваше приложение должно обрабатывать события, инициируемые внешне подключенными сервисами (новые письма, приглашения в календаре, файлы, элементы списка, активность Teams), но вы не хотите тратить время и силы на регистрацию webhook, проверку подтверждения подключения и обновление токенов OAuth. Рассмотрим случай, когда ваша функция обрабатывает новые письма, доставленные в контролируемой папке Office 365 Outlook, классифицирует сообщение, вызывает соединитель Office 365 для обогащения и отмечает или перемещает письмо. Всю эту распределённую работу выполняет ваше приложение, и вам не нужно беспокоиться о токенах обновления: их обработку берёт на себя пространство имён вашего коннектора.

• Замена кастомных сервисных клиентов
  Ваш функциональный код уже вызывает Microsoft 365 или сторонние API через пользовательские HTTP-клиенты, что требует управления секретами, областью применения и повторных попыток во многих соединениях, что может быстро превратиться в нагрузку на обслуживание. Вместо этого вы можете использовать типизированные клиенты в SDK разъёмов напрямую в вашем функциональном коде, а управляемые коннекторы сами занимаются соединениями.

• Используйте существующее развертывание приложений
  Вы уже создали проект функционального приложения, управляемый событиями, с конвейером развертывания и инструментами мониторинга. Вы можете использовать управляемые коннекторы, чтобы добавить новую функцию на основе триггеров внешнего сервиса в том же проекте и воспользоваться существующей инфраструктурой. Например, функциональное приложение, которое раньше полагалось на очереди сообщений или логические приложения, теперь может напрямую реагировать на активность Teams и подключаться к Office 365 для проверок внутри организации и поиска менеджеров.

• Рабочие процессы агента
  Вы строите рабочие процессы, где функция получает событие, рассуждает с помощью модели ИИ, а затем возвращается во внешний сервис через коннекторную операцию. Вы можете использовать навыки Функции Azure для программирования агентного рабочего процесса, одновременно используя управляемые триггеры на основе коннекторов и управляемые SDK для коннекторов.

• Управление на основе кода с управляемой интеграцией
  Вам нужны управляемые коннекторы для упрощения входящей и исходящей связи с внешними сервисами, но вы предпочитаете модель программирования, ориентированную на код, и полный контроль над оркестрацией, включая ветвления, управление аутентификацией между шагами и повторное использование существующих библиотек.

  Tip

  Когда рабочая нагрузка сводится к чистой оркестрации между коннекторами без собственного кода, Logic Apps Standard остаётся самым простым выбором. Для получения дополнительной информации см. раздел «Связь с другими вариантами интеграции Azure».

Связь с другими параметрами интеграции Azure

Управляемые соединители в Функции Azure являются дополнительными. Правильный выбор зависит от того, сколько пользовательского кода требуется для рабочей нагрузки и предпочитает ли команда визуальный дизайнер или код.

Одно приложение-функция может объединить все три шаблона. Вы можете добавить триггер-коннектор в существующее приложение с HTTP-триггером и поэтапно внедрять клиенты SDK.

Пакеты и предварительные требования

Каждый поддерживаемый язык имеет небольшой набор пакетов, которые включают клиенты SDK для привязки триггера и коннектора.

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

Триггеры на основе соединителя

Управляемый триггер на основе коннектора запускает вашу функцию, когда событие происходит в подключённом сервисе. Пространство имён соединителя передаёт событие вашему приложению-функции через HTTPS, используя конечную точку веб-перехватчика расширения соединителя:

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

Конфигурация триггера в пространстве имён коннектора хранит этот URL обратного вызова и показывает системный ключ при каждом обратном вызове. Среда выполнения Functions проверяет ключ перед запуском вашей функции. Для настройки без общих секретов можно разместить встроенную аутентификацию App Service перед функциональным приложением и проверить управляемый идентификационный токен из пространства имён коннектора. См. пример .NET: встроенная аутентификация с управляемой идентичностью для полного шаблона.

Полезные данные запроса содержат текст события и набор заголовков, определяющих конфигурацию триггера x-ms-* , соединение, тип события и идентификатор корреляции. Когда управляемый коннектор имеет модель SDK, среда выполнения десериализует полезную нагрузку напрямую в эту модель. Для управляемых коннекторов без клиентских SDK ваша функция получает необработанное тело JSON.

В следующем примере показана функция, которая запускается при поступлении нового сообщения электронной почты в почтовый ящик Office 365 Outlook. Регистрация триггера осуществляется по языкам; Конфигурация триггера в пространстве имён соединителя одинакова во всех случаях.

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}`);
        }
    },
});

Вы создаёте конфигурацию триггера в пространстве имён соединителя с помощью Azure CLI, ARM или Bicep. Этот шаг является частью платформы коннекторов и описан в документации по коннекторам. Functions не поставляется с собственными командами конфигурации для регистрации триггеров.

Аутентифицируйте свои функции в пространстве имён коннектора

Модель аутентификации по умолчанию использует общий системный ключ (connector_extension), который пространство имён коннектора передаёт при каждом обратном вызове. Однако область действия общих ключей нельзя ограничить отдельными триггерами, и они требуют скоординированной ротации ключей между приложением-функцией и пространством имён коннектора. Для производственных нагрузок используйте встроенную аутентификацию App Service (также называемую Easy Auth) с управляемой идентификацией.

В этом шаблоне пространство имен коннектора использует собственную управляемую идентичность, назначаемую системой, или управляемую идентичность, назначаемую пользователем, чтобы запрашивать токен Entra ID при каждом обратном вызове. Приложение-функция проверяет этот токен, в том числе его аудиторию, эмитент и идентификатор объекта вызывающей стороны, прежде чем какой-либо запрос достигнет узла Functions. Нет общих ключей, без секретов клиента, нигде.

Для примера сквозной работы см. этот репозиторий: functions-connectors-net-builtinauth.

Конфигурация приложения функций

Встроенная аутентификация выполняется на уровне границы рабочего процесса App Service, прежде чем запрос поступает в среду выполнения Azure Functions. Вы настраиваете его через authsettingsV2 свойство ARM или его эквивалент в Bicep.

Приложению-функции также требуется управляемое удостоверение, назначаемое пользователем, федеративное для регистрации приложения Entra. Встроенная аутентификация использует эти учетные данные федеративного удостоверения (FIC) для создания утверждений клиента для приложения Entra без хранения секрета клиента. Шаблон bicep задает clientSecretSettingName параметр приложения, содержащий идентификатор клиента, назначаемый пользователем, указывая встроенную проверку подлинности для использования FIC вместо секрета.

Поскольку встроенная аутентификация уже проверяет каждый запрос, вы можете отключить резервную проверку host.jsonсистемного ключа , которая будет выглядеть как этот фрагмент JSON:

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

Конфигурация пространства имён разъёмов

В вашем пространстве имён соединителя должна быть включённая и прикреплённая системой или пользователем управляемая идентичность. При создании конфигурации триггера укажите authentication.type = ManagedServiceIdentity и authentication.identity = <resource-id-of-managed-identity> для идентификатора, назначаемого пользователем, или опустите identity для идентификатора, назначаемого системой. Также укажите authentication.audience = <entra-app-client-id>, чтобы среда выполнения коннектора знала, какую аудиторию указывать при запросе токена.

Время выполнения коннектора использует эту управляемую идентичность для генерации токена Entra ID при каждом обратном вызове. В этом токене iss (эмитент) — ваш арендатор, aud (аудитория) — идентификатор клиента приложения Entra, а oid (object ID) — основной идентификатор идентичности. Встроенная аутентификация проверяет все три.

Ресурс пространства имён connector также нуждается в доступе к соединению, например, к office365 соединению. Предоставьте этот доступ через политику доступа, в которой перечислены основные идентификаторы управляемой идентичности. Пример файла biceps показывает полную конфигурацию как идентичности пространства имён, так и политики доступа к соединению.

Что применяется принудительно

Встроенная аутентификация проверяет токены в следующем порядке:

1. Присутствие маркера — отсутствующий или истекший срок действия маркера → 401
2. Подпись — проверяется по JWKS издателя для вашего арендатора
3. iss (издатель) — должно соответствовать openIdIssuer
4. aud (аудитория) — должен находиться в allowedAudiences
5. oid (идентификатор объекта или участника безопасности) — должен соответствовать одному из идентификаторов в allowedPrincipals.identities. Любой другой идентификатор → 403

Поскольку эта проверка выполняется на периферии App Service, ваш функциональный код никогда не видит запрос, который не пришёл из управляемой идентичности пространства имён connector. Для проверки доступа вам не нужен код приложения.

Поток аутентификации

┌─────────────────────────────────────────────────────────────────┐
│  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) │
         └─────────────────────────────────┘

Связанный контент

• Аутентификация и авторизация в Служба приложений Azure и Функции Azure
• Настройте сервис приложений или приложение Функции Azure для использования входа в Microsoft Entra
• Конфигурация на основе файлов в проверке подлинности Службы приложений Azure
• Федерация удостоверений рабочей нагрузки в Microsoft Entra ID
• Управляемые удостоверения для ресурсов Azure

Использование соединителей в коде

Connector SDK позволяет вашей функции вызывать операции с разъёмом как исходящие действия. Клиентская поверхность использует тот же управляемый разъём в пространстве имён разъёмов, который запускает использование, поэтому один управляемый разъём может питать как входящие, так и исходящие вызовы для одной и той же сервисной учетной записи.

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

Связанные статьи

• Примеры коннекторов Функции Azure (канонический указатель)
• Сквозной пример .NET: email → поиск пользователя → Teams
• пример .NET: встроенная проверка подлинности с помощью управляемого удостоверения
• Репозиторий расширения коннектора Функции Azure
• Сопоставление сигнатур операций с Функции Azure
• Обзор соединителей Azure
• Что такое пространство имен соединителя Azure?
• Навыки, размещённые в Функции Azure