Connector Trigger for Azure Functions

Azure Functions oferuje rozszerzenia wyzwalaczy i wiązań, które integrują się z różnymi usługami, głównie usługami Azure. Rozszerzenie Connector rozszerza te integracje na znacznie szerszy zakres usług, w tym systemy biznesowe i platformy danych.

Na przykład użyj wyzwalacza łącznika, aby uruchomić funkcję, gdy w Office 365 Outlook nadejdzie nowy e-mail, plik zostanie utworzony w SharePoint lub rekord zmieni się w Salesforce. Wyzwalacz otrzymuje zdarzenia z zarządzanego złącza w przestrzeni nazw Azure Connector. Aby poznać dostępne złącza zarządzane, zobacz odniesienie do złączy.

Aby uzyskać więcej informacji o zarządzanych konektorach, kiedy ich używać oraz dostępności funkcji, zobacz Używanie zarządzanych konektorów w Azure Functions.

Note

Connector Trigger nie jest obecnie obsługiwany dla tego języka.

Metody dostawy

Złącza zarządzane obsługują dwa tryby dostarczania:

  • Odpytywanie: Host Functions łączy się wychodząco z przestrzenią nazw łącznika, aby odbierać zdarzenia. Ustaw deliveryMode: 'Poll', podaj connection i triggerConfigName w opcjach rejestracji.
  • Webhook: Przestrzeń nazw łącznika wysyła zdarzenia do końcowego wywołania zwrotnego rozszerzenia. Webhook jest domyślnie ustawiony, gdy pominiesz deliveryMode.

Oba tryby obsługują nazwane pomocniki, takie jak connectors.office365.onNewEmail oraz ogólny connectorTrigger pomocnik. Aby uzyskać pomoc w wyborze trybu, zobacz Wybór trybu dostarczania.

Wprowadzenie

Postępuj zgodnie ze ścieżką konfiguracji dla swojego trybu dostarczania:

  1. Zainstaluj pakiety Node.js i skonfiguruj pakiet rozszerzeń.
  2. Utwórz lub ponownie użyj przestrzeni nazw i połączenia oraz utwórz konfigurację wyzwalacza odpytywania.
  3. Pobierz punkt końcowy do ankietowania.
  4. Skonfiguruj dane uwierzytelniające dzwoniącego, dostęp do połączenia oraz ustawienia lokalne lub wdrożone.
  5. Użyj przykładu ankiety poniżej, dopasowując je connection i triggerConfigName wartości do swoich ustawień.

Odpytywanie nie wymaga publicznego punktu końcowego wywołania zwrotnego ani klucza systemowego. Dla dostarczania webhook funkcja docelowa i endpoint callback muszą być gotowe przed utworzeniem konfiguracji wyzwalacza.

Metody dostawy

Złącza zarządzane obsługują dwa tryby dostarczania:

  • Odpytywanie: Host Functions łączy się wychodząco z przestrzenią nazw łącznika, aby odbierać zdarzenia. Ustaw delivery_mode=func.DeliveryMode.POLL, a podanie connection i trigger_config_name na @app.connector_trigger.
  • Webhook: Przestrzeń nazw łącznika wysyła zdarzenia do końcowego wywołania zwrotnego rozszerzenia. Webhook jest domyślny, gdy pominiesz delivery_mode na @app.connector_trigger.

Aby uzyskać pomoc w wyborze trybu, zobacz Wybór trybu dostarczania.

Wprowadzenie

Postępuj zgodnie ze ścieżką konfiguracji dla swojego trybu dostarczania:

  1. Zainstaluj pakiety Python i skonfiguruj pakiet rozszerzeń.
  2. Utwórz lub ponownie użyj przestrzeni nazw i połączenia oraz utwórz konfigurację wyzwalacza odpytywania.
  3. Pobierz punkt końcowy do ankietowania.
  4. Skonfiguruj dane uwierzytelniające dzwoniącego, dostęp do połączenia oraz ustawienia lokalne lub wdrożone.
  5. Użyj przykładu ankiety poniżej, dopasowując je connection i trigger_config_name wartości do swoich ustawień.

Odpytywanie nie wymaga publicznego punktu końcowego wywołania zwrotnego ani klucza systemowego. Dla dostarczania webhook funkcja docelowa i endpoint callback muszą być gotowe przed utworzeniem konfiguracji wyzwalacza.

Metody dostawy

Złącza zarządzane obsługują dwa tryby dostarczania:

  • Odpytywanie: Host Functions łączy się wychodząco z przestrzenią nazw łącznika, aby odbierać zdarzenia. Ustaw DeliveryMode = ConnectorTriggerDeliveryMode.Poll, a następnie dodaj ustawienia połączenia i konfigurację wyzwalaczy na [ConnectorTrigger].
  • Webhook: Przestrzeń nazw łącznika wysyła zdarzenia do końcowego wywołania zwrotnego rozszerzenia. Webhook jest domyślny, gdy pominiesz DeliveryMode atrybut.[ConnectorTrigger]

Aby uzyskać pomoc w wyborze trybu, zobacz Wybór trybu dostarczania.

Wprowadzenie

Postępuj zgodnie ze ścieżką konfiguracji dla swojego trybu dostarczania:

  1. Zainstaluj rozszerzenie.
  2. Utwórz lub ponownie użyj przestrzeni nazw i połączenia oraz utwórz konfigurację wyzwalacza odpytywania.
  3. Pobierz punkt końcowy do ankietowania.
  4. Skonfiguruj dane uwierzytelniające dzwoniącego, dostęp do połączenia oraz ustawienia lokalne lub wdrożone.
  5. Użyj poniższego przykładu, dopasowując go Connection i TriggerConfigName wartości do swoich ustawień.

Odpytywanie nie wymaga publicznego punktu końcowego wywołania zwrotnego ani klucza systemowego. Dla dostarczania webhook funkcja docelowa i endpoint callback muszą być gotowe przed utworzeniem konfiguracji wyzwalacza.

Examples

Przykłady Office 365 Outlook i SharePoint Online wykorzystują silnie typowane payloady z Azure Connectors SDK. Dla operacji łączących, które nie mają jeszcze silnie typowanych ładunków, przypisz się do string otrzymania surowego ładunku JSON. Te przykłady celowo rejestrują tylko podstawowe informacje o ładunku, aby skupić się na definiowaniu funkcji wyzwalanych przez konektor. Zastąp logowanie logiką przetwarzania aplikacji.

Aby znaleźć, które operacje łącznikowe obsługują silnie typowane ładunki dla .NET, zobacz mapowanie sygnatur Operacje na Azure Functions.

Tryb dostarczania odpytywania obsługuje również opcjonalne właściwości atrybutu [ConnectorTrigger] . Opisy, obsługiwane wartości i domyślne wartości znajdziesz w sekcji właściwości atrybutów polling.

Office 365 Outlook

Poniższy przykład pojawia się, gdy nowy e-mail pojawia się w skonfigurowanej skrzynce Office 365 Outlook:

Ten przykład otrzymuje partie do czterech zdarzeń łącznikowych, z których każde zawiera jeden e-mail, i służy ConnectorEvent<T> do dostępu do ładunku każdego zdarzenia oraz MessageId.

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

namespace Office365App;

public sealed class O365Functions(ILogger<O365Functions> logger)
{
    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewEmailTriggerConfigName%",
            IsBatched = true,
            MaxBatchSize = 4,
            TargetPendingEventThreshold = 16)]
        ConnectorEvent<Office365OnNewEmailTriggerPayload>[] emails)
    {
        foreach (var email in emails)
        {
            var messageCount = email.Data.Body?.Value?.Count ?? 0;
            logger.LogInformation(
                "Poll event {MessageId}: received {MessageCount} new email message(s).",
                email.MessageId,
                messageCount);
        }
    }
}

Do lokalnego rozwoju dołącz ustawienia połączenia i nazwę konfiguracji wyzwalacza w Values sekcji local.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}

Właściwości atrybutów odnoszą się do następujących ustawień:

  • Connection = "ConnectorNamespace" Określa prefiks ustawień. Rozszerzenie odczytuje punkt końcowy odpytywania z ConnectorNamespace__pollingEndpoint. Aby dowiedzieć się, jak uzyskać punkt końcowy oraz informacje o wymaganych poświadczeniach i politykach dostępu, zobacz punkt końcowy odpytywania.
  • TriggerConfigName = "%OnNewEmailTriggerConfigName%" rozwiązuje wartość OnNewEmailTriggerConfigName ustawienia. Ustaw jej wartość na nazwę konfiguracji wyzwalacza odpytywania w przestrzeni nazw łącznika.

Nazwy prefiksu i ustawień są ilustracyjne; jeśli je zmienisz, zaktualizuj zarówno właściwości atrybutu, jak i ustawienia, aby pasowały. Dla wdrożonej aplikacji funkcyjnej dodaj te same ustawienia do ustawień aplikacji funkcyjnej zamiast local.settings.json.

Typ Office365OnNewEmailTriggerPayload jest definiowany w Azure.Connectors.Sdk.Office365.Models przestrzeni nazw.

Pełny przykład kodu, w tym infrastruktura i rejestracja wyzwalaczy, znajduje się w Office 365 Outlook wyzwalaczach dla .NET.

SharePoint Online

Poniższy przykład uruchamia się, gdy plik zostanie utworzony w skonfigurowanej bibliotece dokumentów SharePoint Online:

Ten przykład otrzymuje jedno zdarzenie łącznika zawierające jeden plik na wywołanie (domyślnie) i używa ConnectorEvent<T> go do dostępu do jego ładunku oraz MessageId.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.SharePointOnline.Models;

namespace SharePointApp;

public sealed class SharePointFunctions(ILogger<SharePointFunctions> logger)
{
    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewFileTriggerConfigName%")]
        ConnectorEvent<SharePointOnlineOnNewFileItemsTriggerPayload> file)
    {
        var fileCount = file.Data.Body?.Value?.Count ?? 0;
        logger.LogInformation(
            "Poll event {MessageId}: received {FileCount} new SharePoint file(s).",
            file.MessageId,
            fileCount);
    }
}

Dla rozwoju lokalnego uwzględnij te wartości w obiekcie Values wlocal.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}

Właściwości atrybutów odnoszą się do następujących ustawień:

  • Connection = "ConnectorNamespace" Określa prefiks ustawień. Rozszerzenie odczytuje punkt końcowy odpytywania z ConnectorNamespace__pollingEndpoint. Aby dowiedzieć się, jak uzyskać punkt końcowy oraz informacje o wymaganych poświadczeniach i politykach dostępu, zobacz punkt końcowy odpytywania.
  • TriggerConfigName = "%OnNewFileTriggerConfigName%" rozwiązuje wartość OnNewFileTriggerConfigName ustawienia. Ustaw jej wartość na nazwę konfiguracji wyzwalacza SharePoint w przestrzeni nazw łącznika.

Nazwy prefiksu i ustawień są ilustracyjne; jeśli je zmienisz, zaktualizuj zarówno właściwości atrybutu, jak i ustawienia, aby pasowały. Dla wdrożonej aplikacji funkcyjnej dodaj te same ustawienia do ustawień aplikacji funkcyjnej zamiast local.settings.json.

Typ SharePointOnlineOnNewFileItemsTriggerPayload jest definiowany w Azure.Connectors.Sdk.SharePointOnline.Models przestrzeni nazw.

Pełny przykład kodu, w tym infrastruktura i rejestracja wyzwalaczy, znajduje się w artykule SharePoint Online triggers for .NET.

Złącze bez silnie typowanego ładunku

Niektóre zdarzenia łączące nie mają jeszcze silnie wpisanego ładunku .NET. Poniższy przykład uruchamia się, gdy do czatu lub kanału Microsoft Teams zostanie dodana nowa wiadomość. Odpytywanie służy ConnectorEvent<string> do odbierania surowego ładunku JSON z metadanymi dostarczania; dostawa webhook wiąże się bezpośrednio z string:

Ten przykład otrzymuje jedno zdarzenie łącznika na wywołanie (domyślnie) i używa ConnectorEvent<string> go do dostępu do ładunku JSON oraz MessageId.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;

namespace TeamsApp;

public sealed class TeamsFunctions(ILogger<TeamsFunctions> logger)
{
    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage(
        [ConnectorTrigger(
            DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
            Connection = "ConnectorNamespace",
            TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%")]
        ConnectorEvent<string> message)
    {
        logger.LogInformation(
            "Poll event {MessageId}: received a Teams payload of {PayloadLength} characters.",
            message.MessageId,
            message.Data.Length);
    }
}

Dla rozwoju lokalnego uwzględnij te wartości w obiekcie Values wlocal.settings.json:

{
  "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
  "OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}

Właściwości atrybutów odnoszą się do następujących ustawień:

  • Connection = "ConnectorNamespace" Określa prefiks ustawień. Rozszerzenie odczytuje punkt końcowy odpytywania z ConnectorNamespace__pollingEndpoint. Aby dowiedzieć się, jak uzyskać punkt końcowy oraz informacje o wymaganych poświadczeniach i politykach dostępu, zobacz punkt końcowy odpytywania.
  • TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%" rozwiązuje wartość OnNewTeamsMessageTriggerConfigName ustawienia. Ustaw jej wartość na nazwę konfiguracji wyzwalacza odpytywania Teams w przestrzeni nazw łącznika.

Nazwy prefiksu i ustawień są ilustracyjne; jeśli je zmienisz, zaktualizuj zarówno właściwości atrybutu, jak i ustawienia, aby pasowały. Dla wdrożonej aplikacji funkcyjnej dodaj te same ustawienia do ustawień aplikacji funkcyjnej zamiast local.settings.json.

Pełny przykład kodu, w tym infrastrukturę i rejestrację wyzwalaczy, znajdziesz w sekcji Generic connector triggers for .NET.

Mapowania zdarzeń łącznika

Nazwa operacji jest definiowana przez zarządzany konektor. Wybierasz nazwę funkcji w swoim kodzie. Przykłady polling i webhook używają tych samych nazw zdarzeń, operacji i funkcji:

Zdarzenie łącznika Nazwa operacji Nazwa funkcji
Nowy Office 365 Outlook mail OnNewEmailV3 OnNewEmail
Nowy plik SharePoint Online GetOnNewFileItems OnNewFile
Nowy czat lub wiadomość kanałowa Microsoft Teams WebhookNewMessageTrigger OnNewTeamsMessage

Ładunki Webhook mogą zawierać wiele elementów, w zależności od konfiguracji wyzwalacza.

Dostarczanie odpytów zawsze włącza splitOn, więc każde zdarzenie w kolejce zawiera jeden podzielony element. Jednak tryb odpytywania może grupować zdarzenia w jedno wywołanie funkcji, ustawiając IsBatched = true. Aby poznać konfigurację grupowania, zobacz Atrybuty.

Typy powiązań

Dla izolowanych funkcji roboczych .NET oba tryby dostarczania obsługują następujące typy parametrów:

Typ Description
string Otrzymuje ciało zdarzenia jako surowy JSON. Używaj tego typu, gdy mocno typowany model SDK nie jest dostępny lub gdy chcesz samodzielnie odserializować payload.
Model SDK Connector Deserializuje ciało zdarzenia JSON do modelu specyficznego dla operacji z Azure.Connectors.Sdk, takiego jak Office365OnNewEmailTriggerPayload lub SharePointOnlineOnNewFileItemsTriggerPayload.
JSON-deserializowalne POCO Deserializuje ciało zdarzenia JSON do typu .NET, którego kształt odpowiada ładunkowi łącznika, używając skonfigurowanego serializatora roboczego.
ConnectorEvent<T> Owija obsługiwany typ ładunku w Data. MessageId zawiera identyfikator dostawy do odpytywania i jest przeznaczony null do dostarczania przez webhook.

Parametry tablicy

Parametry tablicy mają różne znaczenia w każdym trybie dostarczania.

Dla pollingu określa IsBatched kształt parametru funkcji, gdzie T jest obsługiwanym typem ładunku zdarzenia:

IsBatched Typ parametru funkcji
false (domyślnie) T lub ConnectorEvent<T>
true T[] lub ConnectorEvent<T>[], nawet gdy MaxBatchSize = 1

Ustaw MaxBatchSize wartość od 1 do 32; bez grupowania efektywny rozmiar partii musi wynosić 1. Wielkość partii liczy zdarzenia łącznika, a nie elementy w ładunku zdarzenia. Grupowanie nie zmienia typu ładunku w każdym zdarzeniu. Kolekcja Body.Value ładunku SDK jest oddzielna od zewnętrznej tablicy zdarzeń dostarczanych do wsadowego wywołania.

Dla webhooku użyj T[] do deserializacji ciała JSON pojedynczego wywołania zwrotnego na tablicę elementów ładunku. To nie jest partia oddzielnie dostarczanych zdarzeń. Dostarczanie przez Webhook przetwarza jedno wywołanie zwrotne na wywołanie; IsBatched dotyczy tylko odpytywania.

Examples

Rozszerzenie Node.js connector zapewnia typowane konteksty dla operacji Office 365 Outlook, SharePoint Online oraz Microsoft Teams pokazane w tej sekcji. Te przykłady celowo rejestrują jedynie podstawowe informacje o ładunku, aby skupić się na definiowaniu funkcji wyzwalanych przez Connector. Zastąp logowanie logiką przetwarzania aplikacji.

Aby sprawdzić, które operacje łącznika obsługują silnie typowane ładunki dla JavaScript i TypeScript, zobacz Node.js rozszerzenie konektora.

Office 365 Outlook

Poniższy przykład pojawia się, gdy nowy e-mail pojawia się w skonfigurowanej skrzynce Office 365 Outlook:

Ten przykład otrzymuje do czterech zdarzeń łącznika na wywołanie. Pomocnik dostarcza e-maile z tych wydarzeń jako jedną listę.

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

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

Typ EmailTriggerContext ten wyświetla wiadomości jako tablicę typową emails .

Dodatkowe przykłady znajdziesz w Office 365 Outlook wyzwalaczach dla TypeScript.

SharePoint Online

Poniższy przykład uruchamia się, gdy plik zostanie utworzony w skonfigurowanej bibliotece dokumentów SharePoint Online:

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik dostarcza swoje rekordy file-property jako listę.

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

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (
        context: SharepointItemTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

Typ SharepointItemTriggerContext udostępnia rekordy właściwości pliku przez records operację GetOnNewFileItems . Pomocnik zachowuje pola dostarczone przez łącznik bez przekształcania ich w stały schemat pliku. Dodatkowe przykłady znajdziesz w sekcji wyzwalacze SharePoint Online dla TypeScript.

Microsoft Teams

Poniższy przykład pojawia się, gdy do kanału Microsoft Teams dodaje się nową wiadomość:

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik dostarcza swój ładunek wiadomości jako listę.

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

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (
        context: ChannelMessageTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

Typ ChannelMessageTriggerContext ten wyświetla wiadomości jako tablicę typową messages .

Dodatkowe przykłady znajdziesz w sekcji Microsoft Teams triggers for TypeScript.

Ogólny ładunek łącznika

Użyj ogólnego pomocnika, gdy operacja nie ma nazwanej rejestracji. Uzyskaj, context.rawPayload gdy Twój kod musi przetworzyć oryginalny ładunek.

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik podaje swoje elementy ładunku jako listę.

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

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

Kontekst ogólny domyślnie ustawia swój typ elementu na .unknown Zweryfikuj elementy przed uzyskaniem dostępu do właściwości specyficznych dla operacji. context.rawPayload Zachowuje przeanalizowane dane wejściowe przed normalizacją, w tym zewnętrzną tablicę zdarzeń dla odpytywania wsadowego.

Examples

Rozszerzenie Node.js connector dostarcza kontekstów specyficznych dla konektorów dla operacji Office 365 Outlook, SharePoint Online oraz Microsoft Teams pokazane w tej sekcji. Te przykłady celowo rejestrują jedynie podstawowe informacje o ładunku, aby skupić się na definiowaniu funkcji wyzwalanych przez Connector. Zastąp logowanie logiką przetwarzania aplikacji.

Aby sprawdzić, które operacje łącznika obsługują silnie typowane ładunki dla JavaScript i TypeScript, zobacz Node.js rozszerzenie konektora.

Office 365 Outlook

Poniższy przykład pojawia się, gdy nowy e-mail pojawia się w skonfigurowanej skrzynce Office 365 Outlook:

Ten przykład otrzymuje do czterech zdarzeń łącznika na wywołanie. Pomocnik dostarcza e-maile z tych wydarzeń jako jedną listę.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.office365.onNewEmail('OnNewEmail', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewEmailTriggerConfigName%',
    cardinality: 'many',
    maxBatchSize: 4,
    targetPendingEventThreshold: 16,
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

Kontekst obsługi obsługiwa udostępnia wiadomości przez tablicę emails .

SharePoint Online

Poniższy przykład uruchamia się, gdy plik zostanie utworzony w skonfigurowanej bibliotece dokumentów SharePoint Online:

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik dostarcza swoje rekordy file-property jako listę.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.records.length} new SharePoint file(s).`,
        );
    },
});

Kontekst obsługi udostępnia rekordy właściwości pliku dla records operacji GetOnNewFileItems . Pomocnik zachowuje pola dostarczone przez łącznik bez przekształcania ich w stały schemat pliku.

Microsoft Teams

Poniższy przykład pojawia się, gdy do kanału Microsoft Teams dodaje się nową wiadomość:

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik dostarcza swój ładunek wiadomości jako listę.

const {
    connectors,
} = require('@azure/functions-extensions-connectors');

connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.messages.length} new Teams message(s).`,
        );
    },
});

Kontekst obsługi obsługiwa udostępnia wiadomości przez tablicę messages .

Ogólny ładunek łącznika

Użyj ogólnego pomocnika, gdy operacja nie ma nazwanej rejestracji. Uzyskaj, context.rawPayload gdy Twój kod musi przetworzyć oryginalny ładunek.

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Pomocnik podaje swoje elementy ładunku jako listę.

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    deliveryMode: 'Poll',
    connection: 'ConnectorNamespace',
    triggerConfigName: '%GenericTriggerConfigName%',
    handler: async (context, invocationContext) => {
        invocationContext.log(`Received ${context.items.length} payload item(s).`);
    },
});

Zweryfikuj elementy przed uzyskaniem dostępu do właściwości specyficznych dla operacji. context.rawPayload Zachowuje przeanalizowane dane wejściowe przed normalizacją, w tym zewnętrzną tablicę zdarzeń dla odpytywania wsadowego.

Ustawienia lokalnego odpytywania

Dodaj nazwy końcowe i konfiguracyjne wyzwalacze do local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "OnNewTeamsMessageTriggerConfigName": "<teams-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

Wartość w przykładach connection: 'ConnectorNamespace' identyfikuje prefiks ustawień. Każde triggerConfigName wyrażenie rozwiązuje się z odpowiadającym mu ustawieniem aplikacji. Ustawienia wdrożenia i uprawnienia połączeń znajdziesz w sekcji Uwierzytelnianie odpytywania.

Inny przykład rejestracji w sondażu można znaleźć w próbceNode.js.

Examples

Przykłady Office 365 Outlook i SharePoint Online wykorzystują konwertery dostarczone przez azurefunctions-extensions-connectors. Przykład generyczny otrzymuje surowy JSON bez adnotacji SDK. Te przykłady rejestrują tylko podstawowe informacje o ładunku; zastąp logowanie logiką przetwarzania Twojej aplikacji.

Aby znaleźć, które operacje łącznika obsługują silnie typowane ładunki dla Python, zobacz Kluczowe koncepcje w rozszerzeniu konektora Python.

Office 365 Outlook

Poniższy przykład pojawia się, gdy nowy e-mail pojawia się w skonfigurowanej skrzynce Office 365 Outlook:

Ten przykład otrzymuje do czterech zdarzeń łącznika na wywołanie. Konwerter dostarcza e-maile z tych zdarzeń jako jedną listę.

import logging

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

app = func.FunctionApp()


@app.function_name(name="OnNewEmail")
@app.connector_trigger(
    arg_name="emails",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnNewEmailTriggerConfigName%",
    cardinality=func.Cardinality.MANY,
    max_batch_size=4,
    target_pending_event_threshold=16,
)
def on_new_email(
    emails: list[office365.GraphClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

Powiązanie GraphClientReceiveMessage wspiera tę operację OnNewEmailV3 . Pełną rejestrację kodu, infrastruktury i wyzwalaczy dla obu trybów znajdziesz w Office 365 Outlook wyzwalaczach dla Python.

SharePoint Online

Poniższy przykład uruchamia się, gdy plik zostanie utworzony w skonfigurowanej bibliotece dokumentów SharePoint Online:

Ten przykład otrzymuje jedno zdarzenie łącznika na każde wywołanie, co jest domyślne. Konwerter dostarcza swoje rekordy właściwości plików jako listę.

import logging

import azure.functions as func
import azurefunctions.extensions.connectors.sharepointonline as sharepoint

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(
    arg_name="files",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%OnSharepointNewFileTriggerConfigName%",
)
def on_sharepoint_new_file(files: list[sharepoint.Item]) -> None:
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

Powiązanie Item obsługuje GetOnNewFileItems operację i zachowuje właściwości pliku w dynamic_properties. Pełną rejestrację kodu, infrastruktury i wyzwalaczy dla obu trybów znajdziesz w sekcji SharePoint Online triggers for Python.

Ogólny ładunek łącznika

Użyj biblioteki azure-functions , aby otrzymywać zdarzenia jako surowe ciągi JSON, gdy operacja nie ma obsługiwanego typowanego konwertera lub gdy chcesz samodzielnie przeanalizować JSON.

Ten przykład otrzymuje jedno zdarzenie konektora na każde wywołanie, domyślnie, jako surowy ciąg JSON.

import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(
    arg_name="payload",
    delivery_mode=func.DeliveryMode.POLL,
    connection="ConnectorNamespace",
    trigger_config_name="%GenericTriggerConfigName%",
)
def on_connector_event(payload: str) -> None:
    logging.info("Received a connector event.")

Pełne przykłady znajdziesz w sekcji Generic connector triggers for Python.

Dla lokalnego odpytywania zdefiniuj nazwy konfiguracji punktów końcowych i wyzwalaczy poniżej Valueslocal.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
    "OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
    "OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
    "GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
  }
}

Wartość w przykładach connection="ConnectorNamespace" identyfikuje prefiks ustawień. Każde trigger_config_name wyrażenie rozwiązuje się z odpowiadającym mu ustawieniem aplikacji. Ustawienia wdrożenia i uprawnienia połączeń znajdziesz w sekcji Uwierzytelnianie odpytywania.

Typy powiązań

Oba tryby dostarczania obsługują następujące formy rejestracji i ładunku:

Registration Wejście do obsługi
app.connectorTrigger z @azure/functions Odbiera oryginalne wejście wyzwalające bez normalizacji pomocniczej. Domyślny typ wejścia TypeScript to ; unknowndla odpytywania zbiorowego użyj typu tablicy, takiego jak unknown[].
connectorTrigger z @azure/functions-extensions-connectors Otrzymuje a ConnectorTriggerContext<T> z normalizowanymi payload i items, parsowanymi rawPayloadoraz toJSON() serializacją. Typ elementu TypeScript domyślnie to .unknown
Nazwane pomocniki, takie jak connectors.office365.onNewEmail Odbierz znormalizowany kontekst z nazwaną tablicą, taką jak emails, records, lub messages, która jest aliasem.items TypeScript wyciąga wnioski o obsługiwanym typie elementu SDK.

Pomocniki przyjmują dane wejściowe obiektów lub łańcuchy JSON. Normalizują { body: item } i { body: { value: [...] } } obsypują. W przypadku odpytywania partii spłaszczają zewnętrzną tablicę kopert i ich elementów ładunku w jedną items tablicę, zachowując kolejność. rawPayload Zachowuje przeanalizowane dane wejściowe przed normalizacją, w tym zewnętrzną tablicę zdarzeń.

Ustaw cardinality: 'many' tak, aby włączyć grupowanie wywołań. Tablica w kontekście lub sama tablica TypeScript nie umożliwia grupowania. maxBatchSize Liczy zdarzenia łącznika, a nie elementy w znormalizowanej tablicy. Każde wywołanie webhooka obsługuje jedno wywołanie zwrotne, które może zawierać wiele elementów ładunku.

Typy TypeScript opisują oczekiwany ładunek, ale nie weryfikują ani nie transformują pól specyficznych dla operacji podczas wykonywania działania. Zweryfikuj ładunek przed uzyskaniem dostępu do właściwości, gdy jego kształt nie jest znany. Obsługiwane typowane rejestracje i typy ładunków SDK znajdziesz w Node.js extension extension.

Typy powiązań

Wyzwalacz Connector obsługuje następujące typy parametrów Python:

Typ Description
str Otrzymuje ciało zdarzenia jako ciąg JSON.
dict Akceptowane jako adnotacja, ale surowy konwerter nie parsuje ciągów JSON na słowniki. Aby analizować surowy JSON, powiąż i str użyj json.loads.
bytes Otrzymuje ciało zdarzenia jako surowe bajty.
typing.List[str] lub typing.List[bytes] Otrzymuje oddzielnie dostarczone zdarzenia łącznika jako listę, gdy odpytywanie używa cardinality=func.Cardinality.MANY. Importuj List z typing dla tych adnotacji.
Obsługiwana adnotacja SDK dla konektorów Używa konwertera zarejestrowanego przez azurefunctions-extensions-connectors do deserializacji ładunku na listę modeli SDK specyficznych dla operacji.

Dla powiązań SDK adnotuj parametr obsługiwanym typem powiązania lub listą tego typu, na przykład list[office365.GraphClientReceiveMessage]. Obsługiwane powiązania SDK zwracają listy zarówno dla wywołań pojedynczych zdarzeń, jak i wsadowych. W przypadku odpytywania partiowego konwerter spłaszcza zdarzenia transportowe i ich elementy ładunku w jedną listę.

Ustaw cardinality=func.Cardinality.MANY dekorator, aby włączyć grupowanie wywołań. Sama adnotacja listy nie umożliwia grupowania. Ustawienie rozmiaru partii liczy zdarzenia łącznika, a nie elementy w ładunku zdarzenia ani liczbę modeli na zwróconej liście.

Dostęp do połączenia i autoryzacja oddzwaniania są oddzielne. Przestrzeń nazw łącznika automatycznie obsługuje własny dostęp do zarządzanego połączenia łącznika. Skonfiguruj dostęp aplikacji funkcyjnej zgodnie z jej trybem dostarczania.

Tryb odpytywania

Attributes

Atrybut obsługuje ConnectorTrigger następujące właściwości, gdy DeliveryMode jest ustawiony na ConnectorTriggerDeliveryMode.Poll:

Właściwość Required Wartość domyślna Description
DeliveryMode Tak, do sondaży ConnectorTriggerDeliveryMode.Webhook Ustaw na użyj ConnectorTriggerDeliveryMode.Poll pollling.
Connection Yes null Identyfikuje prefiks konfiguracji dla punktów końcowych odpytywania i ustawień tożsamości dla przestrzeni nazw łącznika. Na przykład wybiera "ConnectorNamespace"ConnectorNamespace__pollingEndpoint.
TriggerConfigName Yes null Nazwa konfiguracji wyzwalacza odpytywania w przestrzeni nazw łącznika. Podaj nazwę bezpośrednio lub użyj wyrażenia ustawień aplikacji, takich jak "%OnNewEmailTriggerConfigName%".
IsBatched No false Czy każde wywołanie otrzymuje partię zdarzeń łącznika. Gdy false, każde wywołanie otrzymuje jedno zdarzenie. Ustaw na i true użyj parametru array, aby odbierać partie. Partie są przetwarzane pojedynczo na słuchacza.
MaxBatchSize No 1 Maksymalna liczba zdarzeń łącznika na wywołanie, od 1 do 32. Po pominięciu lub ustawieniu na 0, używa ustawienia hosta defaultMaxBatchSize , które domyślnie jest ustawione na 1host.json. Efektywny rozmiar partii musi wynosić 1 , gdy IsBatched jest .false
MaxConcurrentCalls No 16 Maksymalna liczba jednoczesnych zadań przetwarzania pojedynczego zdarzenia na nasłuchiwacz na jednej instancji, w tym przygotowanie, wywołanie i potwierdzenie. Musi być nieujemna. Po pominięciu lub ustawieniu na 0, używa ustawienia hosta defaultMaxConcurrentCalls , które domyślnie jest ustawione na 16host.json. Dotyczy tylko wtedy, gdy IsBatched ma wartość false. Wsadowe wywołania przetwarzają się po jednej partii na nasłuchiwacz.
TargetPendingEventThreshold No 16 Pożądana liczba oczekujących zdarzeń łącznika na instancję dla skalowania opartego na celu. Musi być nieujemna. Po pominięciu lub ustawieniu na 0, używa ustawienia hosta defaultTargetPendingEventThreshold , które domyślnie jest ustawione na 16host.json. Czas działania może nadpisać ten cel skalowania. Ta właściwość nie zmienia rozmiaru partii ani współbieżności wywołań.

Aby uzyskać domyślne ustawienia obowiązujące w całej aplikacji, zobacz ustawienia host.json ankiet. Wielkość partii liczy zdarzenia łącznika, a nie elementy w ładunku zdarzenia.

Dekoratorzy głosowań

Ustaw delivery_mode=func.DeliveryMode.POLL i @app.connector_trigger skonfiguruj połączenie odpytywania oraz konfigurację wyzwalaczów:

Parametr Required Wartość domyślna Description
arg_name Yes None Identyfikuje parametr funkcji, który odbiera ładunek.
delivery_mode Tak, do sondaży func.DeliveryMode.WEBHOOK Ustaw na użyj func.DeliveryMode.POLL pollling. Struny "Poll" i "Webhook" również są podparte.
connection Yes None Identyfikuje prefiks ustawień dla punktu końcowego odpytywania oraz ustawień tożsamości. Na przykład wybiera "ConnectorNamespace"ConnectorNamespace__pollingEndpoint.
trigger_config_name Yes None Identyfikuje konfigurację wyzwalacza odpytywania. Podaj nazwę bezpośrednio lub użyj wyrażenia ustawień aplikacji, takich jak "%OnNewEmailTriggerConfigName%".
cardinality No func.Cardinality.ONE Ustaw na lub func.Cardinality.MANY"many" aby włączyć grupowanie wywołań. Wsadowe wywołania są przetwarzane pojedynczo na słuchacza.
max_batch_size No Domyślny host: 1 Maksymalna liczba zdarzeń łącznika na wywołanie, od 1 do 32. Po pominięciu lub ustawieniu na 0, używa defaultMaxBatchSize z host.json. Bez grupowania efektywny rozmiar partii musi wynosić 1.
max_concurrent_calls No Domyślny host: 16 Maksymalna liczba jednoczesnych zadań przetwarzania pojedynczego zdarzenia na nasłuchiwaczu na jednej instancji. Po pominięciu lub ustawieniu na 0, używa defaultMaxConcurrentCalls z host.json. Musi być nieujemna. Nie dotyczy to wywołań zbiorczonych.
target_pending_event_threshold No Domyślny host: 16 Docelowe zdarzenia oczekujące na instancję dla skalowania opartego na celu. Po pominięciu lub ustawieniu na 0, używa defaultTargetPendingEventThreshold z host.json. Musi być nieujemna. Nie zmienia rozmiaru partii ani współbieżności wywołań; środowisko wykonania może nadpisać cel skalowania.

Aby uzyskać domyślne ustawienia obowiązujące w całej aplikacji, zobacz ustawienia host.json ankiet. Kształty parametrów i adnotacje SDK znajdziesz w sekcji Typy wiązań.

Opcje rejestracji do głosowania

Ustaw deliveryMode: 'Poll' na nazwanym pomocniku, ogólnym connectorTrigger pomocniku lub app.connectorTrigger, i skonfiguruj połączenie odpytywania oraz konfigurację wyzwalacza:

Option Required Wartość domyślna Description
deliveryMode Tak, do sondaży 'Webhook' Ustaw na użyj 'Poll' pollling.
connection Yes None Identyfikuje prefiks ustawień dla punktu końcowego odpytywania oraz ustawień tożsamości. Na przykład wybiera 'ConnectorNamespace'ConnectorNamespace__pollingEndpoint.
triggerConfigName Yes None Identyfikuje konfigurację wyzwalacza odpytywania. Podaj nazwę bezpośrednio lub użyj wyrażenia ustawień aplikacji, takich jak '%OnNewEmailTriggerConfigName%'.
cardinality No 'one' Ustaw na , 'many' aby włączyć grupowanie wywołań. Wsadowe wywołania są przetwarzane pojedynczo na słuchacza.
maxBatchSize No Domyślny host: 1 Maksymalna liczba zdarzeń łącznika na wywołanie, od 1 do 32. Po pominięciu lub ustawieniu na 0, używa defaultMaxBatchSize z host.json. Bez grupowania efektywny rozmiar partii musi wynosić 1.
maxConcurrentCalls No Domyślny host: 16 Maksymalna liczba jednoczesnych zadań przetwarzania pojedynczego zdarzenia na nasłuchiwaczu na jednej instancji. Po pominięciu lub ustawieniu na 0, używa defaultMaxConcurrentCalls z host.json. Musi być nieujemna. Nie dotyczy to wywołań zbiorczonych.
targetPendingEventThreshold No Domyślny host: 16 Docelowe zdarzenia oczekujące na instancję dla skalowania opartego na celu. Po pominięciu lub ustawieniu na 0, używa defaultTargetPendingEventThreshold z host.json. Musi być nieujemna. Nie zmienia rozmiaru partii ani współbieżności wywołań; środowisko wykonania może nadpisać cel skalowania.

Aby uzyskać domyślne ustawienia obowiązujące w całej aplikacji, zobacz ustawienia host.json ankiet. Aby uzyskać kształty wejściowe do obsługi użytkownika, zobacz Typy wiązań.

Punkt końcowy sondowania

Ustawienie połączenia funkcji wybiera prefiks dla punktu końcowego odpytywania. Na przykład prefiks "ConnectorNamespace" używa ConnectorNamespace__pollingEndpoint. Zdefiniuj to ustawienie w sekcji Values wlocal.settings.json dla lokalnego rozwoju lub w ustawieniach aplikacji dla wdrożonej aplikacji funkcyjnej, jak pokazano w przykładach ankiet.

Pobierz punkt końcowy odpytywania z portalu Przestrzeni Nazw Łącznika lub wyprowadź go z konfiguracji wyzwalacza wygenerowanej przez pollingEndpoints.receiveUri usługę w następujący sposób. Zamień symbole zastępcze na wartości zasobów.

Wymaga Azure CLI, jq, oraz sed.

triggerConfigId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/connectorGateways/<namespace-name>/triggerConfigs/<trigger-config-name>"
triggerConfig=$(az rest --method get \
    --url "${triggerConfigId}?api-version=2026-05-01-preview" \
    --query '{receiveUri:properties.pollingEndpoints.receiveUri,name:name}' \
    --output json)
receiveUri=$(printf '%s' "$triggerConfig" | jq -r '.receiveUri')
pollingEndpoint=$(printf '%s' "$receiveUri" |
    sed -E 's#/(api/)?trigger[Cc]onfigs/[^/]+/receive$##')
triggerConfigName=$(printf '%s' "$triggerConfig" | jq -r '.name')
printf '%s\n' "ConnectorNamespace__pollingEndpoint=$pollingEndpoint" \
    "OnNewEmailTriggerConfigName=$triggerConfigName"

Wyprowadź ustawienie z generowanego przez usługę URI Receive w następujący sposób:

Służba pollingEndpoints.receiveUri <Connection>__pollingEndpoint
https://<connector-namespace-host>/api/triggerconfigs/<name>/receive https://<connector-namespace-host>
https://<host>/api/connectorGateways/<id>/triggerconfigs/<name>/receive https://<host>/api/connectorGateways/<id>

Zachowaj identyfikator hosta i bramy dostarczany przez usługę; nie zgaduj nazwy hosta ani nie konfiguruj pełnego adresu odbiorcy URL, ścieżki operacji, samodzielnej bazy /api ani ciągu zapytania.

Rozszerzenie wykorzystuje ten punkt końcowy wraz z nazwą konfiguracji wyzwalacza do tworzenia adresów URL operacji odpytywania. Aby poznać dane uwierzytelniające i polityki dostępu potrzebne do wywołania tych adresów URL, zobacz Uwierzytelnianie odpytywania.

Konfiguracja wyzwalacza odpytywania

Nazwa konfiguracji wyzwalacza funkcji identyfikuje konfigurację, z której ma się odbierać zdarzenia.

Wartości konfiguracji wyzwalaczy odpytywania

Wartość konfiguracji Description
Połączenie Autoryzowane połączenie złącza zarządzanego, takie jak Office 365 Outlook lub SharePoint Online. Jest to oddzielne od ustawienia połączenia funkcji, które identyfikuje prefiks ustawień aplikacji.
Nazwa operacji Działanie wyzwalacza złącza, takie jak OnNewEmailV3 lub GetOnNewFileItems.
Parameters Wartości wymagane przez operację, takie jak folder Outlook lub strona SharePoint i biblioteka dokumentów.
Nazwa konfiguracji wyzwalacza Nazwa tej konfiguracji wyzwalacza odpytywania, odwoływana przez funkcję bezpośrednio lub przez ustawienie aplikacji.
Metoda dostawy Jak zdarzenia są dostarczane z usług, za pomocą ankiety lub trybu webhook.

Utwórz konfigurację wyzwalacza odpytywania

  1. Jeśli nie masz jeszcze przestrzeni nazw konektorów, stwórz przestrzeń nazw łącznika.

  2. Przejdź do portalu Connector Namespace, a następnie wybierz swoją przestrzeń nazw.

  3. W menu przestrzeni nazw wybierz Wyzwalacze, a następnie Stwórz.

  4. Znajdź zarządzane złącze, którego chcesz użyć, a następnie wybierz zdarzenie, które powinno uruchomić tę funkcję.

  5. Na stronie konfiguracji wyzwalacza utworz połączenie lub wybierz istniejące połączenie. Utworzenie połączenia wymaga jednorazowej uwierzytelnienia z usługą zewnętrzną.

  6. Dostarcz wymagane dane wejściowe podczas wydarzenia. Na przykład zdarzenie Office 365 Outlook nowej wiadomości e-mail wymaga od folderu monitorowania nowych wiadomości.

  7. Dla typu Destination wybierz Azure Functions.

  8. Dla trybu dostarczania wybierz Polling.

  9. Przejrzyj konfigurację i wybierz pozycję Utwórz.

Uwierzytelnianie odpytywania

Do odpytywania przyznaj politykę dostępu na poziomie połączenia do zarządzanej tożsamości aplikacji funkcyjnej (wdrożonej) lub swojej tożsamości dewelopera (lokalnej). Host Functions używa poświadczeń Microsoft Entra tej tożsamości do odbierania i potwierdzania zdarzeń przez punkt końcowy. Dostęp do własnego połączenia przestrzeni nazw łącznika jest obsługiwany automatycznie.

Polityka dzwoniącego przyznaje dostęp do połączenia z zarządzanym łącznikiem, a nie do samej przestrzeni nazw. Logowanie lub włączenie zarządzanej tożsamości nie przyznaje dzwoniącemu automatycznie tego dostępu.

W przeciwieństwie do dostarczania webhook, odpytywanie nie wymaga publicznego adresu URL wywołania zwrotnego ani klucza systemowego aplikacji funkcyjnej, ponieważ aplikacja funkcyjna pobiera zdarzenia z przestrzeni nazw, a nie odbiera wywołania zwrotne.

Ustawienia uwierzytelniania w poniższych podsekcjach używają prefiksu ConnectorNamespace, odpowiadającego przykładom wyzwalaczy. Jeśli Twoja funkcja używa innego prefiksu ustawiania połączenia, użyj właśnie tego.

Zasady przyznawania dostępu

Użyj dowolnej metody, aby przyznać wywołującemu dostęp do połączenia. Potrzebujesz uprawnień do zarządzania politykami dostępu w połączeniu. Użyj głównego (obiektowego) ID wywołującego, a nie jego aplikacji (klienta).

  1. Przejdź do portalu Connector Namespace, a następnie wybierz swoją przestrzeń nazw.
  2. Otwórz Połączenia i wybierz połączenie powiązania zarządzanego konektora używane przez konfigurację wyzwalacza odpytywania.
  3. Otwórz kartę Zasady dostępu połączenia.
  4. Dodaj politykę dostępu dla tożsamości dzwoniącego. Do lokalnego rozwoju użyj identyfikatora obiektu swojego konta deweloperskiego. Dla wdrożonej aplikacji funkcyjnej użyj identyfikatora podmiotu (obiektu) zarządzanej tożsamości, której używa Twoja aplikacja.
  5. Sprawdź, czy dzwoniący ma politykę dostępu do połączenia.

Rozwój lokalny

  1. Zaloguj się za pomocą swojej tożsamości deweloperskiej, na przykład uruchamiając .az login To jest konto Microsoft Entra, którego rozszerzenie używa do lokalnego uwierzytelniania żądań odpytywania.
  2. Nadaj politykę dostępu do połączenia powiązanego z zarządzanym łącznikiem dla tej tożsamości. Samo logowanie nie daje dostępu do połączenia.
  3. Zdefiniuj ustawienia połączenia poniżej Valueslocal.settings.json. Pomiń ConnectorNamespace__credential używanie danych uwierzytelniających dewelopera.

Aplikacja funkcyjna wdrożona

  1. Włącz zarządzaną tożsamość przypisaną przez system w aplikacji funkcji lub przypisz jej zarządzaną tożsamość przypisaną przez użytkownika.
  2. Nadaj politykę dostępu do połączenia powiązanego z zarządzanym łącznikiem dla tej tożsamości.
  3. Skonfiguruj następujące ustawienia uwierzytelniania w ustawieniach aplikacji funkcyjnej:
Ustawienia aplikacji Value
ConnectorNamespace__credential managedidentity
ConnectorNamespace__clientId ID klienta przypisanej przez użytkownika tożsamości zarządzanej do odpytywania (polling). Ustaw tylko przy użyciu tożsamości przypisanej przez użytkownika.

Alternatywnie, ustaw ConnectorNamespace__managedIdentityResourceId na ID zasobu przypisanej przez użytkownika tożsamości zamiast ustawiania ConnectorNamespace__clientId. Dla tożsamości przypisanej przez system pomiń oba selektory.

Wykorzystanie w sondażach

Host Functions łączy się z przestrzenią nazw łącznika, aby sprawdzać zdarzenia i potwierdzać pomyślne wywołania. Rozszerzenie przekazuje zdarzenia do Twojej funkcji; nie piszesz pętli odpytywania.

Dostawa odbywa się przynajmniej raz. Nieudane wywołania nie są potwierdzane, a zdarzenia mogą być ponownie dostarczone po wygaśnięciu blokady zarządzanej przez usługę. Zapewnij idempotentność przetwarzania.

Jeśli używasz ConnectorEvent<T>.MessageId do deduplikacji, ogranicz to do przestrzeni nazw i konfiguracji wyzwalaczy; nie zakładaj, że identyfikatory wiadomości są unikalne dla wszystkich wyzwalaczy.

Ustaw DeliveryMode = ConnectorTriggerDeliveryMode.Poll na [ConnectorTrigger], i podaj właściwości Connection oraz TriggerConfigName . Zobacz przykłady sondaży.

Właściwości atrybutów, obsługiwane wartości i domyślne wartości znajdziesz w sekcji Właściwości atrybutu Odpytywania.

Ustaw delivery_mode=func.DeliveryMode.POLL na @app.connector_trigger, a podaj connection i .trigger_config_name Zobacz przykłady sondaży.

Host otrzymuje jedno zdarzenie na wywołanie, chyba że cardinality=func.Cardinality.MANY włączono grupowanie. Dla surowych partii użyj typing.List[str] lub typing.List[bytes]; obsługiwane adnotacje SDK dostarczają listę modeli. Opcje, obsługiwane wartości i ustawienia domyślne znajdziesz w sekcji Dekoratorzy ankiet.

Ustaw deliveryMode: 'Poll', podaj connection i triggerConfigName w opcjach rejestracji. Zobacz przykłady sondaży.

Host otrzymuje jedno zdarzenie na wywołanie, chyba że cardinality: 'many' włączono grupowanie. Pomocniki nazwane i ogólne łączą elementy ładunku ze wszystkich zdarzeń w jeden kontekst. Bezpośrednie app.connectorTrigger handlery zamiast tego odbierają zewnętrzną tablicę zdarzeń. Opcje, obsługiwane wartości i ustawienia domyślne znajdziesz w sekcji Opcje rejestracji w odpytowaniu.

Skalowanie i współbieżność

Dostawa przez Webhook

W trybie webhook przestrzeń nazw łącznika wysyła żądania HTTP do punktu końcowego wywołania zwrotnego rozszerzenia. Wyzwalacze łącznika skalują się podobnie jak wyzwalacze HTTP, zgodnie z zachowaniem i limitami skalowania HTTP planu hostingowego. Szczegóły znajdziesz w sekcji Skalowanie sterowane zdarzeniami w Azure Functions.

Dostawa z ankiet

W trybie odpytywania wyzwalacz łącznika używa skalowania opartego na celach na podstawie szacowanego backlogu zdarzeń dla konfiguracji wyzwalacza w przestrzeni nazw łącznika. Cel skalowania jest niezależny od współbieżności przetwarzania dla każdej instancji oraz wielkości partii. Równanie skalowania, ustawienia konfiguracji i wskazówki dotyczące strojenia znajdziesz w sekcji Zarządzane konektory skalowanie oparte na celach.

Tryb Webhook

Registration

Użyj funkcji generycznej connectorTrigger dla operacji, która nie ma rejestracji specyficznej dla konektora:

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

connectorTrigger('OnConnectorEvent', {
    handler: async (
        context: ConnectorTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

Rejestracja generyczna domyślnie przypisuje typ przedmiotu do .unknown Zweryfikowaj ładunek przed uzyskaniem dostępu do właściwości specyficznych dla operacji. Konfiguruj konektor, operację, parametry operacyjne, funkcję docelową oraz uwierzytelnianie callback w konfiguracji trigger w przestrzeni nazw Azure Connector.

Registration

Użyj funkcji generycznej connectorTrigger dla operacji, która nie ma rejestracji specyficznej dla konektora:

const {
    connectorTrigger,
} = require('@azure/functions-extensions-connectors');

connectorTrigger('OnConnectorEvent', {
    handler: async (context, invocationContext) => {
        invocationContext.log(JSON.stringify(context.rawPayload));
    },
});

Ogólna rejestracja normalizuje obwiednię callback, ale nie waliduje specyficznego dla operacji kształtu ładunku. Zweryfikowaj ładunek przed uzyskaniem dostępu do właściwości specyficznych dla operacji. Konfiguruj konektor, operację, parametry operacyjne, funkcję docelową oraz uwierzytelnianie callback w konfiguracji trigger w przestrzeni nazw Azure Connector.

Decorators

Zastosowanie connector_trigger do funkcji, która otrzymuje ładunek zdarzenia:

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(arg_name="payload")
def on_connector_event(payload: str) -> None:
    # Process the raw JSON payload.
    pass

Wartość ta arg_name identyfikuje parametr funkcji, który otrzymuje ładunek danych. Konfiguruj konektor, operację, parametry operacyjne, funkcję docelową oraz uwierzytelnianie callback w konfiguracji trigger w przestrzeni nazw Azure Connector.

Attributes

W przeciwieństwie do odpytywania, dostarczanie webhook nie wymaga dodatkowych właściwości atrybutu [ConnectorTrigger] , ponieważ webhook jest domyślnym trybem dostarczania. Możesz też ustawić DeliveryMode = ConnectorTriggerDeliveryMode.Webhook to jawnie. Właściwości specyficzne dla ankiet nie mają zastosowania do dostarczania webhook.

Konfiguracja wyzwalacza elementu webhook

URL wywołania zwrotnego konfiguracji wyzwalacza identyfikuje funkcję docelową.

Wartości konfiguracji wyzwalacza Webhook

Wartość konfiguracji Description
Połączenie Autoryzowane połączenie złącza zarządzanego, takie jak Office 365 Outlook lub SharePoint Online.
Nazwa operacji Działanie wyzwalacza złącza, takie jak OnNewEmailV3 lub GetOnNewFileItems.
Parameters Wartości wymagane przez operację, takie jak folder Outlook lub strona SharePoint i biblioteka dokumentów.
Adres URL wywołania zwrotnego Rozszerzenie Connector, będące urządzeniem webhook dla funkcji docelowej. Zobacz uwierzytelnianie Webhook.
Nazwa funkcji Zarejestrowana nazwa funkcji w kodzie aplikacji.
Authentication Konfiguracja uwierzytelniania używana do wywoływania aplikacji funkcyjnej.

Wartość functionName ciągu zapytania w URL wywołania zwrotnego musi odpowiadać zarejestrowanej nazwie funkcji. Prawidłowe nazwy funkcji webhook zawierają od 1 do 128 liter, cyfr, podkreśleń lub myślników.

Utwórz konfigurację wyzwalacza webhook

Stwórz konfigurację wyzwalacza za pomocą Azure CLI lub portalu Connector Namespace.

Konfigurowanie wyzwalacza

Konfiguracja wyzwalacza w przestrzeni nazw Azure Connector kojarzy zewnętrzne zdarzenie usługi z callbackiem funkcji docelowej.

Wartości konfiguracji wyzwalacza

Wartość konfiguracji Description
Połączenie Autoryzowane połączenie złącza zarządzanego, takie jak Office 365 Outlook lub SharePoint Online.
Nazwa operacji Działanie wyzwalacza złącza, takie jak OnNewEmailV3 lub GetOnNewFileItems.
Parameters Wartości wymagane przez operację, takie jak folder Outlook lub strona SharePoint i biblioteka dokumentów.
Adres URL wywołania zwrotnego Rozszerzenie Connector, będące urządzeniem webhook dla funkcji docelowej. Zobacz uwierzytelnianie Webhook.
Nazwa funkcji Zarejestrowana nazwa funkcji w kodzie aplikacji.
Authentication Konfiguracja uwierzytelniania używana do wywoływania aplikacji funkcyjnej.

Wartość functionName stringu zapytania w URL-owym callback konfiguracji wyzwalającej musi odpowiadać zarejestrowanej nazwie funkcji. Poprawne nazwy funkcji zawierają od 1 do 128 liter, cyfr, podkreśleń lub łączników.

Nazwa operacji jest definiowana przez zarządzany konektor. Wybierasz nazwę funkcji w kodzie, a konfiguracja wyzwalacza przypisuje operację do tej funkcji. Przykłady w tym artykule wykorzystują następujące odwzorowania:

Zdarzenie łącznika Nazwa operacji Nazwa funkcji
Nowy Office 365 Outlook mail OnNewEmailV3 OnNewEmail
Nowy plik SharePoint Online GetOnNewFileItems OnSharepointNewFile
Nowa wiadomość kanału Microsoft Teams OnNewChannelMessage OnNewChannelMessage
Wybrane zdarzenie łącznika Operacja wybrana w konfiguracji wyzwalacza OnConnectorEvent
Zdarzenie łącznika Nazwa operacji Nazwa funkcji
Nowy Office 365 Outlook mail OnNewEmailV3 OnNewEmail
Nowy plik SharePoint Online GetOnNewFileItems OnSharepointNewFile
Wybrane zdarzenie łącznika Operacja wybrana w konfiguracji wyzwalacza OnConnectorEvent

Stwórz konfigurację wyzwalacza

Stwórz konfigurację wyzwalacza za pomocą Azure CLI lub portalu Connector Namespace.

Zanim rozszerzenie otrzyma zdarzenie, stwórz następujące zasoby i konfiguracje:

  1. Przestrzeń nazw Connector.
  2. Zarządzane połączenie złącza upoważnione do dostępu do usługi zewnętrznej.
  3. Konfiguracja wyzwalacza wybierająca zdarzenie łącznika, parametry operacyjne oraz tryb dostawy.

Dla dostarczania webhook konfiguracja wyzwalacza obejmuje również adres URL wywołania zwrotnego oraz uwierzytelnianie wywołania zwrotnego.

Konfiguracje wyzwalaczy to zasoby przestrzeni nazw łącznika, które można również wdrażać za pomocą ARM lub Bicep.

Poniższe przykłady Azure CLI używają wdrożonej aplikacji funkcjonalnej. Przed uruchomieniem wdroż aplikację z rozszerzeniem i funkcją docelową.

Poniższy przykład Bash wykorzystuje Azure CLI oraz jq do utworzenia Office 365 Outlook wyzwalacza nowej wiadomości e-mailowej. Zamień wartości zastępcze dla zasobów i połączenia:

resourceGroup="<RESOURCE_GROUP>"
namespaceName="<CONNECTOR_NAMESPACE>"
functionAppName="<FUNCTION_APP>"
functionName="OnNewEmail"
triggerName="<TRIGGER_NAME>"
connectionName="<CONNECTION_NAME>"
connectorName="office365"
operationName="OnNewEmailV3"
subscriptionId=$(az account show --query id --output tsv)

connectorKey=$(az functionapp keys list \
    --resource-group "$resourceGroup" \
    --name "$functionAppName" \
    --query "systemKeys.connector_extension" \
    --output tsv)

callbackUrl="https://${functionAppName}.azurewebsites.net/runtime/webhooks/connector?functionName=${functionName}"

notificationFile=$(mktemp)
trap 'rm -f "$notificationFile"' EXIT

jq -n \
    --arg callbackUrl "$callbackUrl" \
    --arg connectorKey "$connectorKey" \
    '{
        callbackUrl: $callbackUrl,
        authentication: {
            type: "QueryString",
            name: "code",
            value: $connectorKey
        }
    }' > "$notificationFile"

az connector-namespace trigger create \
    --resource-group "$resourceGroup" \
    --namespace "$namespaceName" \
    --name "$triggerName" \
    --connection-details "{connectionName:${connectionName},connectorName:${connectorName}}" \
    --operation-name "$operationName" \
    --parameters "[{name:folderPath,value:'Inbox'}]" \
    --notification-details "@$notificationFile" \
    --description "${connectorName} ${operationName} -> ${functionName}" \
    --metadata "{destinationType:functionApp,functionAppName:${functionAppName},functionAppResourceGroup:${resourceGroup},functionAppSubscriptionId:${subscriptionId},functionName:${functionName},recurrenceFrequency:Minute,recurrenceInterval:'5'}"

rm -f "$notificationFile"
trap - EXIT

Wartość ta --parameters jest specyficzna dla działania złącza. W tym przykładzie wybiera folderPath folder Outlook do monitorowania. URL callback nie zawiera klucza systemowego. Obiekt notificationDetails.authentication dodaje klucz jako sekret zapytania w ciągu zapytania, gdy Connector Namespace wywołuje tę funkcję.

Uwierzytelnianie webhook

Przestrzeń nazw łącznika wysyła zdarzenia do aplikacji funkcji, zamiast do niej odpytywać przestrzeń nazw. Domyślnie host Functions uwierzytelnia te wywołania zwrotne, weryfikując klucz systemowy rozszerzenia Connector, nazwany connector_extension.

Przestrzeń nazw łącznika automatycznie obsługuje dostęp do swojego zarządzanego połączenia łącznika. W przeciwieństwie do odpytywania, tożsamość aplikacji funkcyjnej nie potrzebuje polityki dostępu do połączenia wyłącznie po to, by otrzymywać zwroty webhook; klucz systemowy autoryzuje te żądania do aplikacji funkcyjnej.

URL wywołania zwrotnego Webhook

Wdrożona aplikacja

Użyj końcowego wywołania zwrotnego rozszerzenia, bez klucza w adresie URL:

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

Wartość functionName musi odpowiadać nazwie zarejestrowanej funkcji: atrybutowi [Function] w C#, dekoratorowi @app.function_name w Python lub rejestracji wyzwalacza w Node.js.

Dla wdrożonej aplikacji korzystającej z domyślnego uwierzytelniania użyj klucza connector_extension systemowego rozszerzenia Connector, a nie pojedynczego klawisza funkcyjnego. Po wdrożeniu aplikacji funkcyjnej za pomocą rozszerzenia pobierz klucz systemowy:

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

W konfiguracji wyzwalacza zapisz klucz w , notificationDetails.authenticationoddzielnie od adresu URL wywołania zwrotnego:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

Podczas dostarczania zdarzenia przestrzeń nazw łącznika dodaje klucz jako code parametr typu query-string. Oddzielenie klucza od zapisanego URL-a callback pozwala portalowi ukryć go jako sekret. Nie umieszczaj klucza w zapisanym URL wywołania zwrotnego ani nie zatwierdzaj go w kontroli wersji.

Istniejące konfiguracje wyzwalaczy, które zawierają klucz w URL-ie callback, nadal działają. Gdy edytujesz i zapisujesz istniejącą konfigurację wyzwalaczy, klucz przesuwa się do .notificationDetails.authentication

Klucze systemowe nie mogą być ograniczone dla każdego wyzwalacza i wymagają skoordynowanej rotacji między aplikacją funkcyjną a przestrzenią nazw łącznika. W przypadku wywołań zwrotnych opartych na tożsamości bez wspólnego klucza zobacz Wbudowane uwierzytelnianie.

Rozwój lokalnego webhooka

Wywołania zwrotne Webhook muszą docierać do działającego hosta Functions z przestrzeni nazw łącznika. Podczas uruchamiania lokalnie:

  1. Uruchom aplikację funkcyjną za pomocą Azure Functions Core Tools, umożliwiając autoryzację:

    func start --enableAuth
    

    Important

    Zawsze używaj --enableAuth , gdy udostępniasz aplikację przez tunel deweloperski. Bez niej Twój punkt końcowy funkcji jest całkowicie nieuwierzytelniony w publicznym internecie.

  2. Użyj tunelu deweloperskiego Microsoft, aby przekazać publiczny punkt końcowy HTTPS do lokalnego portu hosta Functions. Ustaw widoczność portu tunelu na Public, aby przestrzeń nazw łącznika mogła do niej dotrzeć.

  3. Zbuduj adres URL wywołania zwrotnego z nazwą hosta tunelu i zarejestrowaną nazwą funkcji i użyj go w konfiguracji wyzwalacza webhook. Na przykład port tunelu przekierowujący 7071 do OnNewFile funkcji używa adresu URL takiego:

    https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFile
    

    Dla lokalnego hosta, który przechowuje sekrety w Azurite, pobierz jego connector_extension klucz systemowy, korzystając z tych poleceń PowerShell. Ustaw $connStr na znany parametry połączenia Azurite:

    $connStr = "<azurite-connection-string>"
    
    # Find the most recent host.json blob
    $blobs = az storage blob list --container-name azure-webjobs-secrets --connection-string $connStr -o json | ConvertFrom-Json
    $blobName = ($blobs | Where-Object { $_.name -match '(^|/)host\.json$' } | Sort-Object { $_.properties.lastModified } | Select-Object -Last 1).name
    
    # Download and parse
    az storage blob download --container-name azure-webjobs-secrets --name $blobName --connection-string $connStr --file host-keys.json --no-progress
    $keys = Get-Content host-keys.json | ConvertFrom-Json
    $connectorKey = ($keys.systemKeys | Where-Object { $_.name -eq "connector_extension" }).value
    Remove-Item -LiteralPath host-keys.json
    

    Przechowuj klucz systemowy lokalnego hosta connector_extension oddzielnie w , notificationDetails.authenticationużywając powyższego formatu QueryString uwierzytelniania.

  4. Utrzymuj host i tunel aktywne podczas testowania. Zaktualizuj konfigurację wyzwalacza, jeśli zmieni się nazwa hosta tunelu.

Wbudowane uwierzytelnianie

Dla wywołań webhook bez wspólnych kluczy użyj wbudowanego uwierzytelniania App Service (zwanego także Easy Auth) z zarządzaną tożsamością. Ta konfiguracja jest niezależna od języka programowania funkcji.

Przestrzeń nazw łącznika używa swojej zarządzanej tożsamości przypisanej przez system lub użytkownika, aby zażądać tokena Microsoft Entra ID dla każdego wywołania zwrotnego. Wbudowane uwierzytelnianie weryfikuje token i tożsamość dzwoniącego zanim żądanie dotrze do hosta Functions. Aby uzyskać kompleksową implementację bez tajemnic klienta, zobacz wbudowany przykład uwierzytelniania.

Ta sekcja obejmuje uwierzytelnianie z przestrzeni nazw do aplikacji funkcyjnej. Przestrzeń nazw łącznika automatycznie obsługuje dostęp do swojego zarządzanego połączenia łącznika. Aby uzyskać uwierzytelnianie do usług upstream, zobacz przegląd konektorów Azure.

Konfiguracja aplikacji funkcjonalnej

Important

Ta konfiguracja wymaga uwierzytelniania w całej aplikacji funkcji, nie tylko /runtime/webhooks/connector, i ogranicza dostęp do tożsamości zwrotnej przestrzeni nazw. Istniejące funkcje HTTP wymagające kluczy funkcyjnych nadal wymagają tych kluczy oprócz uwierzytelniania na poziomie aplikacji. Przed zastosowaniem tej konfiguracji do istniejącej aplikacji upewnij się, że klienci API i sondy zdrowia spełniają politykę uwierzytelniania i autoryzacji na poziomie aplikacji oraz wszelkie wymagania dotyczące klucza na poziomie funkcji. W przeciwnym razie żądania mogą zakończyć się niepowodzeniem przy HTTP 401 lub 403. Jeśli aplikacja musi przyjmować innych dzwoniących, dostosuj politykę autoryzacji zamiast kopiować tę listę bez zmian. Opcje polityki znajdziesz w sekcji Konfiguracja autoryzacji Microsoft Entra.

Konfiguruj wbudowane uwierzytelnianie za pomocą zasobu ARM aplikacjiauthsettingsV2 funkcyjnej lub jego odpowiednika w Bicep. Przykład używa następujących ustawień kluczy:

Setting Purpose
platform.enabled: true Włącza wbudowane uwierzytelnianie.
globalValidation.requireAuthentication: true Wymaga uwierzytelnienia przed dotarciem żądań do hosta Functions.
globalValidation.unauthenticatedClientAction: Return401 Zwraca HTTP 401 dla nieautoryzowanych wywołań zwrotnych zamiast przekierowywać na stronę logowania.
identityProviders.azureActiveDirectory.enabled: true Włącza walidację tokenów Microsoft Entra.
registration.clientId ID aplikacji (klienta) rejestracji aplikacji Microsoft Entra, która reprezentuje funkcję aplikacji.
registration.openIdIssuer Adres URL emitenta dla dzierżawcy: https://login.microsoftonline.com/{tenantId}/v2.0.
validation.allowedAudiences Identyfikator klienta i identyfikator URI aplikacji Entra. Tokeny muszą mieć dozwoloną grupę odbiorców w roszczeniu aud .
validation.defaultAuthorizationPolicy.allowedPrincipals.identities ID obiektów (głównych) dozwolone do wywołania funkcji app. Przykład pozwala tylko na zarządzaną tożsamość wywołań zwrotnych przestrzeni nazw. Dostosuj tę politykę, jeśli Twoja aplikacja ma innych dzwoniących. Prawidłowy token z roszczeniem oid nieobecnym na liście dozwolonych jest odrzucany za pomocą HTTP 403.

Ustawienia registration i w validation tej tabeli znajdują się pod identityProviders.azureActiveDirectory.

Przykład przypisuje również zarządzaną tożsamość przypisaną przez użytkownika do aplikacji funkcyjnej i federuje ją z rejestracją aplikacji Entra. Wbudowane uwierzytelnianie wykorzystuje ten federacyjny poświadczeń tożsamości do uzyskiwania asercji klienta bez przechowywania sekretu klienta. Przykład ustawia ustawienie OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID aplikacji na identyfikator klienta funkcji identity aplikacji i ustawia registration.clientSecretSettingName na nazwę tego ustawienia.

Tożsamość funkcji aplikacji używana do federacji jest oddzielna od tożsamości wywołania zwrotnego przestrzeni nazw. Tożsamość przestrzeni nazw to wywołujący dozwolony przez allowedPrincipals.identities.

Po skonfigurowaniu wbudowanego uwierzytelniania do weryfikacji wywołań zwrotnych wyłącz redundantne sprawdzanie klucza systemowego w host.json:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

Używaj Anonymous tylko wtedy, gdy inna warstwa uwierzytelniania weryfikuje żądania zanim dotrą do hosta Functions. To ustawienie samo w sobie nie włącza walidacji tokenów.

Konfiguracja przestrzeni nazw łącznika

Włącz zarządzaną tożsamość przypisaną przez system w przestrzeni nazw łącznika lub dołącz do niej tożsamość przypisaną przez użytkownika. W konfiguracji notificationDetails.authenticationwyzwalacza , ustaw:

Właściwość Value
type ManagedServiceIdentity
audience Identyfikator klienta rejestracji aplikacji Entra, dopasowany do odbiorców zaakceptowanych przez aplikację funkcyjną.
identity ID zasobu przypisanej przez użytkownika tożsamości zarządzanej. Pomiń tę właściwość dla tożsamości przypisanej przez system.

Przestrzeń nazw używa tej tożsamości do uzyskania tokena i wysyła go w nagłówku Authorization: Bearer <token> wywołania zwrotnego. Tokeny iss identyfikują dzierżawę, aud identyfikują aplikację docelową oraz oid identyfikują zarządzaną tożsamość przestrzeni nazw.

Przestrzeń nazw automatycznie obsługuje własny dostęp do zarządzanego połączenia łącznika. Ten dostęp jest oddzielny od autoryzacji wywołania zwrotnego, którą konfigurujesz poprzez wbudowane uwierzytelnianie w aplikacji funkcyjnej.

Przepływ uwierzytelniania i walidacja

  1. Przestrzeń nazw łącznika pobiera token dla skonfigurowanej grupy odbiorców, używając swojej zarządzanej tożsamości wywołań zwrotnych.
  2. Przestrzeń nazw wysyła token z zdarzeniem do punktu końcowego webhook rozszerzenia.
  3. Wbudowane uwierzytelnianie weryfikuje podpis, wygaśnięcie, wydawcę i odbiorców tokena oraz sprawdza, czy odpowiada on oid dozwolonej tożsamości. Brakujące lub nieprawidłowe tokeny otrzymują HTTP 401; prawidłowe tokeny z tożsamości nieznajdującej się na liście dozwolonych otrzymują HTTP 403.
  4. Tylko autoryzowane żądania docierają do hosta Funkcji. Po wyłączeniu redundantnego sprawdzania klucza systemowego rozszerzenie wywołuje funkcję docelową i wiąże ciało zdarzenia z jego parametrem.

Twoja funkcja nie potrzebuje kodu aplikacji, aby wykonać te kontrole dostępu.

Użycie Webhook

Przestrzeń nazw łącznika wysyła zdarzenia do punktu końcowego webhook rozszerzenia, gdzie functionName wartość ciągu zapytania wybiera funkcję. Rozszerzenie wiąże ciało zdarzenia z parametrem funkcji; nie implementujesz obsługi HTTP.

Nazwa funkcji musi odpowiadać nazwie w Twoim [Function] atymencie. Wywołania zwrotne mogą zawierać x-ms-* nagłówki identyfikujące konfigurację wyzwalacza, połączenie, typ zdarzenia i identyfikator korelacji, ale te nagłówki nie są dostępne dla Twojej funkcji za pośrednictwem wyzwalacza łącznika.

Używaj [ConnectorTrigger] bez właściwości pollingowych. Webhook jest domyślnie ustawiony, gdy pominiesz DeliveryMode. Zobacz przykłady webhooków.

Twoja funkcja może odbierać ładunek zdarzenia, korzystając z dowolnego z obsługiwanych typów wiązań .NET.

Rozszerzenie akceptuje HTTP POST i PUT żądania o tym typie application/json treści. Niepuste ciało żądania musi zawierać prawidłowy JSON. Żądania podlegają limitowi treści żądania hosta Functions oraz limitom usług upstream; rozszerzenie nie nakłada osobnego limitu rozmiaru ładunku.

Aby skonfigurować limit treści żądania hosta, ustaw ustawienie aplikacji dla całej FUNCTIONS_REQUEST_BODY_SIZE_LIMIT aplikacji w bajtach i uruchom ponownie hosta. To nie jest ustawienie host.json i nie zmienia pobierania z linked-output z ankiety, które używają extensions.connector.maxLinkedOutputSizeInBytes. Większe limity nie gwarantują obsługiwanych rozmiarów ładunku; uwzględniają buforowanie, pamięć roboczą oraz limity upstream.

Użycie Webhook

Ogólny pomocnik otrzymuje .ConnectorTriggerContext<T> Jego payload właściwość zawiera znormalizowaną obwiedź zwrotną, items zawiera elementy zdarzenia i rawPayload zachowuje przeanalizowane dane wejściowe przed normalizacją. Rejestracje specyficzne dla konektora dostarczają nazwane tablice, takie jak emails, records, lub messages.

Każde wywołanie obsługuje jedno wywołanie zwrotne, które może zawierać wiele elementów ładunku. Dla operacji bez rejestracji specyficznej dla konektora, domyślny typ elementu TypeScript to .unknown Zweryfikuj ładunek przed uzyskaniem dostępu do właściwości specyficznych dla operacji. Obsługiwane rejestracje typu znajdziesz w Node.js extension extension.

Użycie Webhook

Wyzwalacz może powiązać ciało żądania z str, dict, lub bytes. Gdy azurefunctions-extensions-connectors rejestruje konwerter dla adnotacji SDK funkcji, pracownik zamiast tego deserializuje ciało żądania do obsługiwanego typu specyficznego dla operacji.

Każde wywołanie obsługuje jedno wywołanie zwrotne. Obsługiwane powiązania SDK dostarczają swoje elementy ładunku jako listę; użyj adnotacji takiej jak list[office365.GraphClientReceiveMessage]. Aby uzyskać obsługiwane adnotacje specyficzne dla operacji, zobacz mapowanie sygnatur operacji.

Rozszerzenie akceptuje HTTP POST i PUT żądania o tym typie application/json treści. Niepuste ciało żądania musi zawierać prawidłowy JSON. Żądania podlegają limitowi żądania hosta i treści oraz limitom usług upstream.

Metadata

Obecnie wyzwalacz Connector nie ujawnia nagłówków callback ani innych metadanych żądań jako dane wiążące. Rozszerzenie definiuje pusty kontrakt danych wiązania, dzięki czemu funkcja otrzymuje tylko ciało żądania JSON w typie wiązania wspieranym przez wybrany język.