Connector trigger for Azure Functions (Preview)

Beispiele

Die Beispiele Office 365 Outlook und SharePoint Online verwenden stark typisierte Nutzlasten aus dem Azure Connectors SDK. Für Connector-Operationen, die noch keine stark typisierten Nutzlasten besitzen, binden Sie an string , um die rohe JSON-Nutzlast zu empfangen. Diese Beispiele protokollieren absichtlich nur grundlegende Nutzlastinformationen, um sich auf die Definition von Connector-ausgelösten Funktionen zu konzentrieren. Ersetzen Sie das Logging durch die Verarbeitungslogik Ihrer Anwendung.

Office 365 Outlook

Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:

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 class O365Functions
{
    private readonly ILogger<O365Functions> _logger;

    public O365Functions(ILogger<O365Functions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewEmail")]
    public void OnNewEmail(
        [ConnectorTrigger] Office365OnNewEmailTriggerPayload payload)
    {
        var messageCount = payload.Body?.Value?.Count ?? 0;
        _logger.LogInformation(
            "Received {MessageCount} new email message(s).",
            messageCount);
    }
}

Der Typ Office365OnNewEmailTriggerPayload ist im Namensraum Azure.Connectors.Sdk.Office365.Models definiert.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe Office 365 Outlook Trigger für .NET.

SharePoint Online

Das folgende Beispiel läuft, wenn eine Datei in der konfigurierten SharePoint Online-Dokumentbibliothek erstellt wird:

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 class SharePointFunctions
{
    private readonly ILogger<SharePointFunctions> _logger;

    public SharePointFunctions(ILogger<SharePointFunctions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewFile")]
    public void OnNewFile(
        [ConnectorTrigger] SharePointOnlineOnNewFileItemsTriggerPayload payload)
    {
        var fileCount = payload.Body?.Value?.Count ?? 0;
        _logger.LogInformation(
            "Received {FileCount} new SharePoint file(s).",
            fileCount);
    }
}

Der Typ SharePointOnlineOnNewFileItemsTriggerPayload ist im Namensraum Azure.Connectors.Sdk.SharePointOnline.Models definiert.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe SharePoint Online Trigger für .NET.

Steckverbinder ohne stark typisierte Nutzlast

Einige Connector-Events haben noch keine stark typisierte .NET-Nutzlast. Das folgende Beispiel läuft, wenn eine neue Nachricht zu einem Microsoft Teams-Chat oder -Kanal hinzugefügt wird und die Nutzlast stringan bindet:

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

namespace TeamsApp;

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

    public TeamsFunctions(ILogger<TeamsFunctions> logger)
    {
        _logger = logger;
    }

    [Function("OnNewTeamsMessage")]
    public void OnNewTeamsMessage([ConnectorTrigger] string payload)
    {
        _logger.LogInformation("Received a new Teams message: {Payload}", payload);
    }
}

Um Connector-Operationen zu identifizieren, die noch keine stark typisierten Payloads besitzen, siehe Operations to Azure Functions signature mapping.

Attribute

In einer .NET-isolierten Worker-App wenden Sie auf den Funktionsparameter an[ConnectorTrigger], der die Ereignisnutzlast empfängt:

[Function("OnConnectorEvent")]
public void Run([ConnectorTrigger] string payload)
{
    // Process the raw JSON payload.
}

Das Attribut ConnectorTrigger hat keine konfigurierbaren Eigenschaften. Konfigurieren Sie den Connector, die Operation, die Betriebsparameter, die Zielfunktion und die Rückruf-Authentifizierung in der Trigger-Konfiguration im Azure Connector Namespace.

Beispiele

Die Node.js-Connector-Erweiterung bietet typisierte Kontexte für die in diesem Abschnitt gezeigten Operationen Office 365 Outlook, SharePoint Online und Microsoft Teams. Diese Beispiele protokollieren absichtlich nur grundlegende Nutzlastinformationen, um sich auf die Definition von Connector-ausgelösten Funktionen zu konzentrieren. Ersetzen Sie das Logging durch die Verarbeitungslogik Ihrer Anwendung.

Office 365 Outlook

Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:

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

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (
        context: EmailTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

Der Typ EmailTriggerContext stellt die Nachrichten als getyptes emails Array sichtbar.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe Office 365 Outlook Trigger für TypeScript.

SharePoint Online

Das folgende Beispiel läuft, wenn eine Datei in der konfigurierten SharePoint Online-Dokumentbibliothek erstellt wird:

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

connectors.sharepoint.onNewFile('OnSharepointNewFile', {
    handler: async (
        context: FileTriggerContext,
        invocationContext: InvocationContext,
    ) => {
        invocationContext.log(
            `Received ${context.files.length} new SharePoint file(s).`,
        );
    },
});

Der Typ FileTriggerContext stellt die Dateimetadaten als typisiertes files Array offen.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe SharePoint Online Trigger für TypeScript.

Microsoft Teams

Das folgende Beispiel gilt, wenn eine neue Nachricht zu einem Microsoft Teams-Kanal hinzugefügt wird:

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

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

Der Typ ChannelMessageTriggerContext stellt die Nachrichten als getyptes messages Array sichtbar.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe Microsoft Teams-Trigger für TypeScript.

Registration

Verwenden Sie die generische connectorTrigger Funktion für eine Operation, die keine steckerspezifische Registrierung hat:

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

Die generische Registrierung setzt den Artikeltyp standardmäßig auf unknown. Validiere die Nutzlast, bevor du auf operation-spezifische Eigenschaften zugreifst. Konfigurieren Sie den Connector, die Operation, die Betriebsparameter, die Zielfunktion und die Rückruf-Authentifizierung in der Trigger-Konfiguration im Azure Connector Namespace.

Beispiele

Die Node.js-Connector-Erweiterung bietet connector-spezifische Kontexte für die in diesem Abschnitt gezeigten Office 365 Outlook-, SharePoint-Online- und Microsoft Teams-Operationen. Diese Beispiele protokollieren absichtlich nur grundlegende Nutzlastinformationen, um sich auf die Definition von Connector-ausgelösten Funktionen zu konzentrieren. Ersetzen Sie das Logging durch die Verarbeitungslogik Ihrer Anwendung.

Office 365 Outlook

Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:

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

connectors.office365.onNewEmail('OnNewEmail', {
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.emails.length} new email message(s).`,
        );
    },
});

Der Handler-Kontext stellt die Nachrichten über das emails Array sichtbar.

SharePoint Online

Das folgende Beispiel läuft, wenn eine Datei in der konfigurierten SharePoint Online-Dokumentbibliothek erstellt wird:

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

connectors.sharepoint.onNewFile('OnSharepointNewFile', {
    handler: async (context, invocationContext) => {
        invocationContext.log(
            `Received ${context.files.length} new SharePoint file(s).`,
        );
    },
});

Der Handler-Kontext stellt die Dateimetadaten über das files Array frei.

Microsoft Teams

Das folgende Beispiel gilt, wenn eine neue Nachricht zu einem Microsoft Teams-Kanal hinzugefügt wird:

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

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

Der Handler-Kontext stellt die Nachrichten über das messages Array sichtbar.

Registration

Verwenden Sie die generische connectorTrigger Funktion für eine Operation, die keine steckerspezifische Registrierung hat:

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

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

Die generische Registrierung normalisiert den Rückruf-Umschlag, validiert jedoch nicht die operation-spezifische Nutzlastform. Validiere die Nutzlast, bevor du auf operation-spezifische Eigenschaften zugreifst. Konfigurieren Sie den Connector, die Operation, die Betriebsparameter, die Zielfunktion und die Rückruf-Authentifizierung in der Trigger-Konfiguration im Azure Connector Namespace.

Beispiele

Das Office 365 Outlook Beispiel verwendet eine stark typisierte Nutzlast, die von der Python Connector-Erweiterung registriert wird. Die Beispiele str für SharePoint Online und Microsoft Teams binden und parsen das rohe JSON, da diese Operationen derzeit keine registrierten Python-Konverter mit Typisierung haben. Diese Beispiele protokollieren absichtlich nur grundlegende Nutzlastinformationen, um sich auf die Definition von Connector-ausgelösten Funktionen zu konzentrieren. Ersetzen Sie das Logging durch die Verarbeitungslogik Ihrer Anwendung.

Office 365 Outlook

Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:

import logging
from typing import List

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")
def on_new_email(
    emails: List[office365.ClientReceiveMessage],
) -> None:
    logging.info(
        "Received %s new email message(s).",
        len(emails),
    )

Der Typ ClientReceiveMessage wird bereitgestellt durch azurefunctions-extensions-connectors und repräsentiert die Office 365 Outlook Nachrichten im Batch.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe Office 365 Outlook Trigger für Python.

SharePoint Online

Das folgende Beispiel läuft, wenn eine Datei in der konfigurierten SharePoint Online-Dokumentbibliothek erstellt wird:

import json
import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(arg_name="payload")
def on_sharepoint_new_file(payload: str) -> None:
    data = json.loads(payload)
    files = data.get("body", {}).get("value", [])
    logging.info(
        "Received %s new SharePoint file(s).",
        len(files),
    )

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe SharePoint Online Trigger für Python.

Steckverbinder ohne stark typisierte Nutzlast

Das folgende Beispiel läuft, wenn eine neue Nachricht zu einem Microsoft Teams-Kanal hinzugefügt wird und die Nutzlast an strbindet:

import json
import logging

import azure.functions as func

app = func.FunctionApp()


@app.function_name(name="OnNewChannelMessage")
@app.connector_trigger(arg_name="payload")
def on_new_channel_message(payload: str) -> None:
    data = json.loads(payload)
    messages = data.get("body", {}).get("value", [])
    logging.info(
        "Received %s new Teams message(s).",
        len(messages),
    )

Um Connector-Operationen zu identifizieren, die noch keine stark typisierten Python-Payloads besitzen, siehe Operations to Azure Functions signature mapping.

Für das vollständige Codebeispiel, einschließlich Infrastruktur und Trigger-Registrierung, siehe Microsoft Teams Trigger für Python.

Dekorateure

Wenden Sie connector_trigger auf die Funktion an, die die Ereignisnutzlast empfängt:

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

Der Wert arg_name identifiziert den Funktionsparameter, der die Nutzlast empfängt. Konfigurieren Sie den Connector, die Operation, die Betriebsparameter, die Zielfunktion und die Rückruf-Authentifizierung in der Trigger-Konfiguration im Azure Connector Namespace.

Den Trigger konfigurieren

Eine Trigger-Konfiguration im Azure Connector Namespace verknüpft ein externes Service-Ereignis mit dem Callback der Zielfunktion.

Trigger-Konfigurationswerte

Der functionName Wert der Abfrage-String in der Callback-URL der Trigger-Konfiguration muss mit dem Namen der registrierten Funktion übereinstimmen. Gültige Funktionsnamen enthalten 1 bis 128 Buchstaben, Zahlen, Unterstriche oder Bindestriche.

Der Operationsname wird vom verwalteten Connector definiert. Du wählst den Funktionsnamen in deinem Code, und die Trigger-Konfiguration ordnet die Operation dieser Funktion zu. Die Beispiele in diesem Artikel verwenden folgende Abbildungen:

Erstellen Sie eine Trigger-Konfiguration

Erstellen Sie eine Trigger-Konfiguration mithilfe der Azure CLI oder des Connector Namespace Portals.

Bevor Sie die Trigger-Konfiguration erstellen, erstellen Sie eine autorisierte verwaltete Connector-Verbindung in Ihrem Connector-Namensraum und bereiten Sie die Funktions-App aus, die die Zielfunktion enthält.

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

$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"

$notificationDetails = @{
    callbackUrl = $callbackUrl
    authentication = @{
        type  = "QueryString"
        name  = "code"
        value = $connectorKey
    }
} | ConvertTo-Json -Depth 3 -Compress

$notificationFile = Join-Path $env:TEMP "notification-details.json"
$notificationDetails | Set-Content -Path $notificationFile -NoNewline

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'}"

Remove-Item $notificationFile -ErrorAction SilentlyContinue

Usage

Der Trigger bindet den JSON-Anforderungskörper an einen der von der Erweiterung unterstützten .NET-Binding-Typen.

Connector-Operationen können ein Ereignis oder eine Reihe von Ereignissen zurückgeben. Verwenden Sie das operation-spezifische Nutzlastmodell, da dessen Form den Antwortvertrag für diese Verbindungsoperation darstellt.

Usage

Die generische Registrierung erhält ein ConnectorTriggerContext<T>. Seine Eigenschaft enthält den normalisierten Rückruf-Umschlag payload , items enthält die Ereigniselemente und rawPayload bewahrt den ursprünglichen Anforderungskörper. Steckerspezifische Registrierungen liefern benannte typisierte Arrays wie emails, files, oder messages.

Für eine Operation ohne konnektorspezifische Registrierung lautet der Item-Typ standardmäßig .unknown Validiere die Nutzlast, bevor du auf operation-spezifische Eigenschaften zugreifst.

Usage

Der Trigger kann den Anforderungskörper an str, dict, oder bytesbinden. Wenn azurefunctions-extensions-connectors ein Konverter für die SDK-Annotation der Funktion registriert wird, deserialisiert der Worker stattdessen den Anforderungskörper in den unterstützten operation-spezifischen Typ.

Connector-Operationen können ein Ereignis oder eine Reihe von Ereignissen zurückgeben. Verwenden Sie die für die Operation angegebene Typ- oder Sammlungsannotation in der Operation Signature Mapping.

Die Erweiterung akzeptiert HTTP POST und PUT Anfragen mit dem Inhaltstyp application/json . Ein nichtleerer Anforderungskörper muss gültiges JSON enthalten. Die Erweiterung lehnt Anfragekörper größer als 10 MB ab.

Metadata

Der Connector-Trigger stellt derzeit keine Callback-Header oder andere Anforderungsmetadaten als Bindungsdaten frei. Die Erweiterung definiert einen leeren Bindungsdatenvertrag, sodass die Funktion nur den JSON-Anforderungskörper in einem von der gewählten Sprache unterstützten Bindungstyp empfängt.

Nächste Schritte

• Übersicht zur Steckverbindererweiterung
• Verwenden Sie verwaltete Connectors in Azure Functions
• Azure Functions Connectors Samples
• Was ist Azure Connector-Namespace?
• Steckverbinder-Referenz