Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Azure Functions bietet Trigger- und Bindungserweiterungen, die sich mit verschiedenen Diensten, vor allem Azure-Diensten, integrieren. Die Connector-Erweiterung erweitert diese Integrationen auf eine deutlich größere Auswahl an Diensten, darunter Geschäftssysteme und Datenplattformen.
Verwenden Sie zum Beispiel den Connector Trigger, um eine Funktion auszuführen, wenn eine neue E-Mail in Office 365 Outlook eintrifft, eine Datei in SharePoint erstellt wird oder sich ein Datensatz in Salesforce ändert. Der Trigger empfängt Ereignisse von einem verwalteten Connector im Azure Connector Namespace. Um die verfügbaren verwalteten Steckverbinder zu erkunden, siehe die Referenz zu den Anschlüssen.
Weitere Informationen zu verwalteten Connectors, wann Sie sie verwenden sollten und zur Verfügbarkeit von Funktionen finden Sie unter Use managed connectors in Azure Functions.
Note
Der Connector Trigger wird derzeit für diese Sprache nicht unterstützt.
Liefermodi
Verwaltete Connectors unterstützen zwei Bereitstellungsmodi:
-
Polling: Der Functions-Host verbindet ausgehende Verbindungen zum Connector-Namespace, um Ereignisse zu empfangen. Stellen Sie
deliveryMode: 'Poll', und liefernconnectionSie undtriggerConfigNamein den Registrierungsoptionen. -
Webhook: Der Connector-Namespace sendet Ereignisse an den Callback-Endpunkt der Erweiterung. Webhook ist der Standard, wenn du wegfällst
deliveryMode.
Beide Modi unterstützen benannte Helfer wie connectors.office365.onNewEmail den generischen connectorTrigger Hilfsbereitschaft. Für Hilfe bei der Auswahl eines Modus siehe Auslieferungsmodus auswählen.
Get started
Folgen Sie dem Setup-Pfad für Ihren Zustellmodus:
- Installieren Sie die Node.js-Pakete und konfigurieren Sie das Erweiterungspaket.
- Erstellen oder wiederverwenden Sie einen Namespace und eine Verbindung sowie erstellen Sie eine Polling-Trigger-Konfiguration.
- Holen Sie sich den Polling-Endpunkt.
- Konfigurieren Sie Anrufer-Anmeldedaten, Verbindungszugriff sowie lokale oder bereitgestellte Einstellungen.
- Verwenden Sie unten ein Polling-Beispiel und ordnen Sie seine
connectionWertetriggerConfigNamemit Ihren Einstellungen ab.
Polling erfordert keinen öffentlichen Callback-Endpunkt oder Systemschlüssel. Für die Webhook-Bereitstellung müssen die Zielfunktion und der Callback-Endpunkt bereit sein, bevor Sie die Triggerkonfiguration erstellen.
Liefermodi
Verwaltete Connectors unterstützen zwei Bereitstellungsmodi:
-
Polling: Der Functions-Host verbindet ausgehende Verbindungen zum Connector-Namespace, um Ereignisse zu empfangen. Setze
delivery_mode=func.DeliveryMode.POLL, und Supplyconnectionundtrigger_config_nameOn@app.connector_trigger. -
Webhook: Der Connector-Namespace sendet Ereignisse an den Callback-Endpunkt der Erweiterung. Webhook ist der Standard, wenn du auf
@app.connector_triggerweglässtdelivery_mode.
Für Hilfe bei der Auswahl eines Modus siehe Auslieferungsmodus auswählen.
Get started
Folgen Sie dem Setup-Pfad für Ihren Zustellmodus:
- Installieren Sie die Python-Pakete und konfigurieren Sie das Erweiterungspaket.
- Erstellen oder wiederverwenden Sie einen Namespace und eine Verbindung sowie erstellen Sie eine Polling-Trigger-Konfiguration.
- Holen Sie sich den Polling-Endpunkt.
- Konfigurieren Sie Anrufer-Anmeldedaten, Verbindungszugriff sowie lokale oder bereitgestellte Einstellungen.
- Verwenden Sie unten ein Polling-Beispiel und ordnen Sie seine
connectionWertetrigger_config_namemit Ihren Einstellungen ab.
Polling erfordert keinen öffentlichen Callback-Endpunkt oder Systemschlüssel. Für die Webhook-Bereitstellung müssen die Zielfunktion und der Callback-Endpunkt bereit sein, bevor Sie die Triggerkonfiguration erstellen.
Liefermodi
Verwaltete Connectors unterstützen zwei Bereitstellungsmodi:
-
Polling: Der Functions-Host verbindet ausgehende Verbindungen zum Connector-Namespace, um Ereignisse zu empfangen. Setzen Sie
DeliveryMode = ConnectorTriggerDeliveryMode.Poll, und fügen Sie die Verbindungseinstellungen sowie die Triggerkonfiguration auf[ConnectorTrigger]hinzu. -
Webhook: Der Connector-Namespace sendet Ereignisse an den Callback-Endpunkt der Erweiterung. Webhook ist der Standard, wenn du das
[ConnectorTrigger]Attribut weglässtDeliveryMode.
Für Hilfe bei der Auswahl eines Modus siehe Auslieferungsmodus auswählen.
Get started
Folgen Sie dem Setup-Pfad für Ihren Zustellmodus:
- Installieren Sie die Erweiterung.
- Erstellen oder wiederverwenden Sie einen Namespace und eine Verbindung sowie erstellen Sie eine Polling-Trigger-Konfiguration.
- Holen Sie sich den Polling-Endpunkt.
- Konfigurieren Sie Anrufer-Anmeldedaten, Verbindungszugriff sowie lokale oder bereitgestellte Einstellungen.
- Verwenden Sie unten ein Beispiel, in dem Sie seine
ConnectionWerte undTriggerConfigNameWerte an Ihre Einstellungen anpassen.
Polling erfordert keinen öffentlichen Callback-Endpunkt oder Systemschlüssel. Für die Webhook-Bereitstellung müssen die Zielfunktion und der Callback-Endpunkt bereit sein, bevor Sie die Triggerkonfiguration erstellen.
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 Payload-Informationen, um sich darauf zu konzentrieren, wie connector-ausgelöste Funktionen definiert werden. Ersetzen Sie das Logging durch die Verarbeitungslogik Ihrer Anwendung.
Um herauszufinden, welche Connector-Operationen stark typisierte Payloads für .NET unterstützen, siehe Operations to Azure Functions signature mapping.
Der Abfragemodus unterstützt außerdem optionale Eigenschaften für das Attribut [ConnectorTrigger] . Für Beschreibungen, unterstützte Werte und Standardeinstellungen siehe Polling-Attributeigenschaften.
Office 365 Outlook
Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:
Dieses Beispiel empfängt Chargen von bis zu vier Connector-Ereignissen, die jeweils eine E-Mail enthalten, und wird verwendet ConnectorEvent<T> , um auf die Payload jedes Ereignisses zuzugreifen und 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);
}
}
}
Für die lokale Entwicklung fügen Sie die Verbindungseinstellungen und den Trigger-Konfigurationsnamen im Values Abschnitt local.settings.json:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}
Die Attributeigenschaften beziehen sich auf folgende Einstellungen:
-
Connection = "ConnectorNamespace"Identifiziert das Einstellungspräfix. Die Erweiterung liest den Abholendpunkt vonConnectorNamespace__pollingEndpoint. Erfahren Sie, wie Sie den Endpunkt und Informationen zu den erforderlichen Zugangsdaten und Zugriffsrichtlinien erhalten, siehe Polling-Endpunkt. -
TriggerConfigName = "%OnNewEmailTriggerConfigName%"löst den Wert derOnNewEmailTriggerConfigNameEinstellung auf. Setzen Sie seinen Wert auf den Namen der Polling-Trigger-Konfiguration in Ihrem Connector-Namespace.
Die Präfix- und Einstellungsnamen sind illustrativ; wenn Sie sie ändern, aktualisieren Sie sowohl die Attributeigenschaften als auch die Einstellungen, damit sie übereinstimmen. Für eine bereitgestellte Funktions-App fügen Sie dieselben Einstellungen in die App-Einstellungen der Funktions-App statt local.settings.json.
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:
Dieses Beispiel erhält ein Connector-Ereignis, das pro Aufruf eine Datei enthält (Standard) und verwendet ConnectorEvent<T> , um auf seine Payload und MessageIdzuzugreifen.
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);
}
}
Für die lokale Entwicklung fügen Sie diese Werte im Values Objekt in local.settings.jsonein:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}
Die Attributeigenschaften beziehen sich auf folgende Einstellungen:
-
Connection = "ConnectorNamespace"Identifiziert das Einstellungspräfix. Die Erweiterung liest den Abholendpunkt vonConnectorNamespace__pollingEndpoint. Erfahren Sie, wie Sie den Endpunkt und Informationen zu den erforderlichen Zugangsdaten und Zugriffsrichtlinien erhalten, siehe Polling-Endpunkt. -
TriggerConfigName = "%OnNewFileTriggerConfigName%"löst den Wert derOnNewFileTriggerConfigNameEinstellung auf. Setzen Sie seinen Wert auf den Namen der SharePoint-Polling-Trigger-Konfiguration in Ihrem Connector-Namensraum.
Die Präfix- und Einstellungsnamen sind illustrativ; wenn Sie sie ändern, aktualisieren Sie sowohl die Attributeigenschaften als auch die Einstellungen, damit sie übereinstimmen. Für eine bereitgestellte Funktions-App fügen Sie dieselben Einstellungen in die App-Einstellungen der Funktions-App statt local.settings.json.
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 wird ausgeführt, wenn eine neue Nachricht zu einem Microsoft Teams-Chat oder -Kanal hinzugefügt wird. Polling wird verwendet ConnectorEvent<string> , um die Roh-JSON-Payload mit Liefermetadaten zu empfangen; Webhook-Lieferungen binden direkt zu string:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis (Standard) und wird verwendet ConnectorEvent<string> , um auf seine JSON-Payload und MessageIdzuzugreifen.
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);
}
}
Für die lokale Entwicklung fügen Sie diese Werte im Values Objekt in local.settings.jsonein:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}
Die Attributeigenschaften beziehen sich auf folgende Einstellungen:
-
Connection = "ConnectorNamespace"Identifiziert das Einstellungspräfix. Die Erweiterung liest den Abholendpunkt vonConnectorNamespace__pollingEndpoint. Erfahren Sie, wie Sie den Endpunkt und Informationen zu den erforderlichen Zugangsdaten und Zugriffsrichtlinien erhalten, siehe Polling-Endpunkt. -
TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%"löst den Wert derOnNewTeamsMessageTriggerConfigNameEinstellung auf. Setzen Sie seinen Wert auf den Namen der Teams-Polling-Triggerkonfiguration in Ihrem Connector-Namespace.
Die Präfix- und Einstellungsnamen sind illustrativ; wenn Sie sie ändern, aktualisieren Sie sowohl die Attributeigenschaften als auch die Einstellungen, damit sie übereinstimmen. Für eine bereitgestellte Funktions-App fügen Sie dieselben Einstellungen in die App-Einstellungen der Funktions-App statt local.settings.json.
Für das vollständige Codebeispiel, einschließlich Infrastruktur- und Trigger-Registrierung, siehe Generic connector triggers for .NET.
Connector-Ereigniszuordnungen
Der Operationsname wird vom verwalteten Connector definiert. Sie wählen den Funktionsnamen in Ihrem Code aus. Die Polling- und Webhook-Beispiele verwenden dieselben Ereignis-, Operations- und Funktionsnamen:
| Konnektor-Ereignis | Vorgangsname | Funktionsname |
|---|---|---|
| Neue Office 365 Outlook-E-Mail | OnNewEmailV3 |
OnNewEmail |
| Neue SharePoint Online-Datei | GetOnNewFileItems |
OnNewFile |
| Neue Microsoft Teams-Chat- oder Kanalnachricht | WebhookNewMessageTrigger |
OnNewTeamsMessage |
Webhook-Payloads können je nach Trigger-Konfiguration mehrere Elemente enthalten.
Die Auslieferung der Polling aktiviert splitOnimmer , sodass jedes warteschlange Ereignis ein getrenntes Element enthält. Der Polling-Modus kann jedoch Ereignisse zu einer einzigen Funktionsaufruf gruppieren, indem er gesetzt IsBatched = truewird. Für die Batching-Konfiguration siehe Attribute.
Bindungstypen
Für .NET-Isolationsarbeiterfunktionen unterstützen beide Bereitstellungsmodi folgende Parametertypen:
| Typ | Description |
|---|---|
string |
Erhält den Event-Body als rohes JSON. Verwenden Sie diesen Typ, wenn kein stark typisiertes SDK-Modell verfügbar ist oder wenn Sie die Nutzlast selbst deserialisieren möchten. |
| Connector-SDK-Modell | Deserialisiert den JSON-Ereigniskörper in ein operationsspezifisches Modell aus Azure.Connectors.Sdk, wie zum Beispiel Office365OnNewEmailTriggerPayload oder SharePointOnlineOnNewFileItemsTriggerPayload. |
| JSON-deserialisierbarer POCO | Deserialisiert den JSON-Ereigniskörper in einen .NET-Typ, dessen Form mit der Connector-Payload übereinstimmt, mithilfe des konfigurierten Worker-Serializers. |
ConnectorEvent<T> |
Umwickelt einen unterstützten Payload-Typ in Data.
MessageId enthält die Delivery-Kennung für Polling und ist für Webhook-Lieferungen vorgesehen null . |
Arrayparameter
Array-Parameter haben in jedem Auslieferungsmodus unterschiedliche Bedeutungen.
Für das AbfragenIsBatched bestimmt die Form des Funktionsparameters, wobei T ein unterstützter Ereignis-Payload-Typ ist:
IsBatched |
Funktionsparametertyp |
|---|---|
false (Standardwert) |
T oder ConnectorEvent<T> |
true |
T[] oder ConnectorEvent<T>[], selbst wenn MaxBatchSize = 1 |
Setzen MaxBatchSize Sie einen Wert von 1 bis 32; ohne Batching muss die effektive Batchgröße 1 sein. Die Batchgröße zählt Connector-Ereignisse, nicht Elemente innerhalb der Payload eines Ereignisses. Batching ändert den Payload-Typ innerhalb jedes Ereignisses nicht. Die Body.Value Sammlung einer SDK-Payload ist getrennt vom äußeren Event-Array, das einem batchierten Aufruf geliefert wird.
Für Webhook, verwenden Sie das T[] , um den JSON-Array-Body eines einzelnen Callbacks in ein Array von Payload-Elementen zu deserialisieren. Das ist keine Reihe separat ausgelieferter Events. Die Webhook-Auslieferung verarbeitet pro Aufruf einen Callback; IsBatched gilt nur für das Abholen.
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.
Um herauszufinden, welche Connector-Operationen stark typisierte Payloads für JavaScript und TypeScript unterstützen, siehe die Node.js-Connector-Erweiterungsreferenz.
Office 365 Outlook
Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:
Dieses Beispiel erhält bis zu vier Connector-Ereignisse pro Aufruf. Der Helfer liefert die E-Mails von diesen Veranstaltungen als eine einzige Liste.
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).`,
);
},
});
Der Typ EmailTriggerContext stellt die Nachrichten als getyptes emails Array sichtbar.
Weitere Beispiele finden Sie unter Office 365 Outlook Triggern für TypeScript.
SharePoint Online
Das folgende Beispiel läuft, wenn eine Datei in der konfigurierten SharePoint Online-Dokumentbibliothek erstellt wird:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Datei-Eigenschaftsdatensätze als Liste.
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).`,
);
},
});
Der Typ SharepointItemTriggerContext stellt Datei-Eigenschaftsdatensätze für die Operation GetOnNewFileItems offenrecords. Der Hilfer bewahrt die vom Connector bereitgestellten Felder bei, ohne sie in ein festes Dateischema umzuwandeln. Weitere Beispiele finden Sie unter SharePoint Online-Triggern für TypeScript.
Microsoft Teams
Das folgende Beispiel gilt, wenn eine neue Nachricht zu einem Microsoft Teams-Kanal hinzugefügt wird:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Nachrichten-Payload als Liste.
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).`,
);
},
});
Der Typ ChannelMessageTriggerContext stellt die Nachrichten als getyptes messages Array sichtbar.
Weitere Beispiele finden Sie unter Microsoft Teams Triggern für TypeScript.
Generic Connector Payload
Verwenden Sie den generischen Helfer, wenn eine Operation keine benannte Registrierung hat. Zugriff darauf context.rawPayload , wenn Ihr Code die ursprüngliche Payload selbst verarbeiten muss.
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Nutzlastgegenstände als Liste.
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).`);
},
});
Der generische Kontext setzt seinen Elementtyp standardmäßig auf unknown. Validieren Sie Elemente, bevor Sie auf operationsspezifische Eigenschaften zugreifen.
context.rawPayload bewahrt die parsierte Eingabe vor der Normalisierung, einschließlich des äußeren Ereignisarrays für batched polling.
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.
Um herauszufinden, welche Connector-Operationen stark typisierte Payloads für JavaScript und TypeScript unterstützen, siehe die Node.js-Connector-Erweiterungsreferenz.
Office 365 Outlook
Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:
Dieses Beispiel erhält bis zu vier Connector-Ereignisse pro Aufruf. Der Helfer liefert die E-Mails von diesen Veranstaltungen als eine einzige Liste.
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).`,
);
},
});
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:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Datei-Eigenschaftsdatensätze als Liste.
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).`,
);
},
});
Der Handler-Kontext stellt Datei-Eigenschaftsdatensätze für die Operation GetOnNewFileItems offenrecords. Der Hilfer bewahrt die vom Connector bereitgestellten Felder bei, ohne sie in ein festes Dateischema umzuwandeln.
Microsoft Teams
Das folgende Beispiel gilt, wenn eine neue Nachricht zu einem Microsoft Teams-Kanal hinzugefügt wird:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Nachrichten-Payload als Liste.
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).`,
);
},
});
Der Handler-Kontext stellt die Nachrichten über das messages Array sichtbar.
Generic Connector Payload
Verwenden Sie den generischen Helfer, wenn eine Operation keine benannte Registrierung hat. Zugriff darauf context.rawPayload , wenn Ihr Code die ursprüngliche Payload selbst verarbeiten muss.
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Helfer liefert seine Nutzlastgegenstände als Liste.
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).`);
},
});
Validieren Sie Elemente, bevor Sie auf operationsspezifische Eigenschaften zugreifen.
context.rawPayload bewahrt die parsierte Eingabe vor der Normalisierung, einschließlich des äußeren Ereignisarrays für batched polling.
Lokale Abstimmungseinstellungen
Fügen Sie die Namen des Polling-Endpunkts und der Trigger-Konfiguration zu local.settings.jsonhinzu:
{
"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>"
}
}
Der Wert der Beispiele connection: 'ConnectorNamespace' identifiziert das Einstellungspräfix. Jeder triggerConfigName Ausdruck löst sich auf seine entsprechende App-Einstellung auf. Für bereitgestellte Einstellungen und Verbindungsberechtigungen siehe Polling-Authentifizierung.
Für ein weiteres Beispiel zur Umfrageregistrierung siehe die Node.js Umfragestichprobe.
Beispiele
Die Office 365 Outlook und SharePoint Online-Beispiele verwenden Konverter, die von bereitgestellt werdenazurefunctions-extensions-connectors. Das generische Beispiel erhält Roh-JSON ohne SDK-Annotation. Diese Beispiele protokollieren nur grundlegende Payload-Informationen; ersetzen Sie die Protokollierung durch die Verarbeitungslogik Ihrer Anwendung.
Um herauszufinden, welche Connector-Operationen stark typisierte Payloads für Python unterstützen, siehe Schlüsselkonzepte in der Python-Connector-Erweiterung.
Office 365 Outlook
Das folgende Beispiel läuft, wenn eine neue E-Mail im konfigurierten Office 365 Outlook-Postfach eingeht:
Dieses Beispiel erhält bis zu vier Connector-Ereignisse pro Aufruf. Der Konverter liefert die E-Mails dieser Ereignisse als eine einzige Liste.
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),
)
Die Bindung GraphClientReceiveMessage unterstützt den Vorgang OnNewEmailV3 . Für vollständige Code-, Infrastruktur- und Triggerregistrierung für beide Modi 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:
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis, das Standard. Der Konverter liefert seine Datei-Eigenschafts-Einträge als Liste.
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),
)
Die Bindung Item unterstützt die GetOnNewFileItems Operation und bewahrt Dateieigenschaften in dynamic_properties. Für vollständige Code-, Infrastruktur- und Triggerregistrierung für beide Modi siehe SharePoint Online-Trigger für Python.
Generic Connector Payload
Verwenden Sie die Bibliothek azure-functions , um Ereignisse als rohe JSON-Zeichenketten zu empfangen, wenn eine Operation keinen unterstützten typisierten Konverter hat oder wenn Sie den JSON selbst parsen möchten.
Dieses Beispiel erhält pro Aufruf ein Connector-Ereignis als Raw JSON-Zeichenkette.
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.")
Für vollständige Beispiele siehe Generische Connector-Trigger für Python.
Für lokale Abfrage definieren Sie die Endpunkt- und Trigger-Konfigurationsnamen unter Values in local.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>"
}
}
Der Wert der Beispiele connection="ConnectorNamespace" identifiziert das Einstellungspräfix. Jeder trigger_config_name Ausdruck löst sich auf seine entsprechende App-Einstellung auf. Für bereitgestellte Einstellungen und Verbindungsberechtigungen siehe Polling-Authentifizierung.
Bindungstypen
Beide Auslieferungsmodi unterstützen die folgenden Registrierungs- und Nutzlastformen:
| Registration | Handler-Eingabe |
|---|---|
von app.connectorTrigger aus @azure/functions |
Erhält die ursprüngliche Trigger-Eingabe ohne Hilfsnormalisierung. Der TypeScript-Eingabetyp ist standardmäßig auf unknown; für batched polling verwenden Sie einen Array-Typ wie unknown[]. |
von connectorTrigger aus @azure/functions-extensions-connectors |
Erhält ein mit ConnectorTriggerContext<T> normalisierten payload und items, parsed rawPayload, und toJSON() serialisiert. Der TypeScript-Elementtyp ist standardmäßig auf unknown. |
Benannte Helfer wie connectors.office365.onNewEmail |
Empfangen Sie den normalisierten Kontext mit einem benannten Array, wie emails, records, oder messages, das aliasiert items. TypeScript leitet den unterstützten SDK-Elementtyp ab. |
Helfer akzeptieren Objekteingaben oder JSON-Zeichenketten. Sie normalisieren { body: item } und { body: { value: [...] } } umrahmen. Beim Batch-Polling fassen sie die äußere Reihe von Umschlägen und deren Nutzlastobjekten zu einem einzigen items Array zusammen, um die Ordnung zu erhalten.
rawPayload behält die geparste Eingabe vor der Normalisierung, einschließlich des äußeren Ereignisarrays.
Aktivieren cardinality: 'many' Sie das Aufruf-Batching. Ein Array im Kontext oder ein TypeScript-Array-Typ allein ermöglicht kein Batching.
maxBatchSize Zählt Connector-Ereignisse, nicht Elemente im normalisierten Array. Jeder Webhook-Aufruf verarbeitet einen Callback, der mehrere Payload-Elemente enthalten kann.
TypeScript-Typen beschreiben die erwartete Nutzlast, validieren oder transformieren jedoch keine operationsspezifischen Felder zur Laufzeit. Validieren Sie die Nutzlast, bevor Sie auf Eigenschaften zugreifen, wenn ihre Form nicht bekannt ist. Für unterstützte typisierte Registrierungen und SDK-Payload-Typen siehe die Node.js-Connector-Erweiterungsreferenz.
Bindungstypen
Der Connector-Trigger unterstützt diese Python-Parametertypen:
| Typ | Description |
|---|---|
str |
Erhält den Ereigniskörper als JSON-String. |
dict |
Als Anmerkung akzeptiert, aber der Raw-Konverter parst JSON-Strings nicht in Wörterbücher um. Um rohes JSON zu parsen, binde an str und verwende json.loads. |
bytes |
Erhält den Ereigniskörper als rohe Bytes. |
typing.List[str] oder typing.List[bytes] |
Empfängt separat zugestellte Connector-Ereignisse als Liste, wenn das Abfragen verwendet cardinality=func.Cardinality.MANYwird. Importieren Sie List aus typing für diese Anmerkungen. |
| Unterstützte Connector SDK-Annotation | Verwendet einen von registrierten Konverter azurefunctions-extensions-connectors , um die Payload in eine Liste operationsspezifischer SDK-Modelle zu deserialisieren. |
Für SDK-Bindungen annotieren Sie den Parameter mit dem unterstützten Bindungstyp oder einer Liste dieses Typs, z. B. list[office365.GraphClientReceiveMessage]. Die unterstützten SDK-Bindungen geben Listen sowohl für Einzelereignis- als auch für Batch-Aufrufe zurück. Für Batch-Polling flacht der Konverter die Transportereignisse und ihre Nutzlastelemente in eine einzige Liste zusammen.
Auf dem Dekorator einstellen cardinality=func.Cardinality.MANY , um das Aufruf-Batching zu aktivieren. Eine Listenanmerkung allein ermöglicht kein Batching. Die Batch-Größeneinstellung zählt Connector-Ereignisse, nicht Elemente innerhalb der Nutzlast eines Ereignisses oder die Anzahl der Modelle in der zurückgegebenen Liste.
Verbindungszugriffs- und Rückrufautorisierung sind getrennt. Der Connector-Namespace verwaltet seinen eigenen Zugriff auf die verwaltete Connector-Verbindung automatisch. Konfigurieren Sie den Zugriff der Funktions-App entsprechend ihrem Auslieferungsmodus.
Attribute
Das Attribut ConnectorTrigger unterstützt die folgenden Eigenschaften, wenn DeliveryMode auf ConnectorTriggerDeliveryMode.Pollgesetzt ist:
| Property | Erforderlich | Default | Description |
|---|---|---|---|
DeliveryMode |
Ja, für Umfragen | ConnectorTriggerDeliveryMode.Webhook |
Auf ConnectorTriggerDeliveryMode.Poll Polling verwenden. |
Connection |
Yes | null |
Identifiziert das Konfigurationspräfix für den Connector-Namespace-Polling-Endpunkt und die Identitätseinstellungen. Zum Beispiel wählt ConnectorNamespace__pollingEndpoint. "ConnectorNamespace" |
TriggerConfigName |
Yes | null |
Der Name der Polling-Triggerkonfiguration im Connector-Namespace. Geben Sie den Namen direkt an oder verwenden Sie einen App-Einstellungsausdruck wie "%OnNewEmailTriggerConfigName%". |
IsBatched |
No | false |
Ob jeder Aufruf eine Reihe von Connector-Ereignissen erhält. Wenn false, erhält jede Invocation ein Ereignis. Setzen Sie auf true und verwenden Sie einen Array-Parameter, um Batches zu empfangen. Batches werden einzeln pro Listener verarbeitet. |
MaxBatchSize |
No | 1 |
Maximale Verbindungsereignisse pro Aufruf, von 1 bis 32. Wenn ausgelassen oder auf 0gesetzt wird, verwendet die Hosteinstellung defaultMaxBatchSize , die standardmäßig auf 1 ist, sofern in host.jsonnicht anders konfiguriert ist. Die effektive Chargengröße muss sein 1 , wenn IsBatched ist false. |
MaxConcurrentCalls |
No | 16 |
Maximale gleichzeitige Einzelereignisverarbeitungsaufgaben pro Listener auf einer Instanz, einschließlich Vorbereitung, Aufruf und Bestätigung. Muss nicht negativ sein. Wenn ausgelassen oder auf 0gesetzt wird, verwendet die Hosteinstellung defaultMaxConcurrentCalls , die standardmäßig auf 16 ist, sofern in host.jsonnicht anders konfiguriert ist. Gilt nur, wenn IsBatchedfalse ist. Batch-Aufrufe werden jeweils einen Batch pro Listener verarbeitet. |
TargetPendingEventThreshold |
No | 16 |
Gewünschte Anzahl ausstehender Connector-Ereignisse pro Instanz für zielbasierte Skalierung. Muss nicht negativ sein. Wenn ausgelassen oder auf 0gesetzt wird, verwendet die Hosteinstellung defaultTargetPendingEventThreshold , die standardmäßig auf 16 ist, sofern in host.jsonnicht anders konfiguriert ist. Die Laufzeit kann dieses Skalierungsziel überschreiben. Diese Eigenschaft ändert weder die Batchgröße noch die Nebenzeitigkeit bei den Aufrufen. |
Für app-weite Standardeinstellungen siehe Polling host.json Einstellungen. Die Batchgröße zählt Connector-Ereignisse, nicht Elemente innerhalb der Payload eines Ereignisses.
Wahldekorateure
Aktivieren delivery_mode=func.DeliveryMode.POLL@app.connector_trigger und konfigurieren Sie die Pollingverbindung und die Trigger-Konfiguration:
| Parameter | Erforderlich | Default | Description |
|---|---|---|---|
arg_name |
Yes | None | Identifiziert den Funktionsparameter, der die Nutzlast erhält. |
delivery_mode |
Ja, für Umfragen | func.DeliveryMode.WEBHOOK |
Auf func.DeliveryMode.POLL Polling verwenden. Die Saiten "Poll" und "Webhook" werden ebenfalls unterstützt. |
connection |
Yes | None | Identifiziert das Einstellungspräfix für den Polling-Endpunkt und die Identitätseinstellungen. Zum Beispiel wählt ConnectorNamespace__pollingEndpoint. "ConnectorNamespace" |
trigger_config_name |
Yes | None | Identifiziert die Polling-Trigger-Konfiguration. Geben Sie den Namen direkt an oder verwenden Sie einen App-Einstellungsausdruck wie "%OnNewEmailTriggerConfigName%". |
cardinality |
No | func.Cardinality.ONE |
Setzen Sie auf func.Cardinality.MANY oder "many" um das Aufruf-Batching zu aktivieren. Batch-Aufrufe werden einzeln pro Listener verarbeitet. |
max_batch_size |
No | Host-Standard: 1 |
Maximale Verbindungsereignisse pro Aufruf, von 1 bis 32. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultMaxBatchSize man von host.json. Ohne Batching muss die effektive Chargengröße betragen 1. |
max_concurrent_calls |
No | Host-Standard: 16 |
Maximale gleichzeitige Einzelereignisbearbeitungsaufgaben pro Listener auf einer einzigen Instanz. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultMaxConcurrentCalls man von host.json. Muss nicht negativ sein. Gilt nicht für gebündelte Aufrufe. |
target_pending_event_threshold |
No | Host-Standard: 16 |
Zielen Sie ausstehende Ereignisse pro Instanz für zielbasierte Skalierung an. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultTargetPendingEventThreshold man von host.json. Muss nicht negativ sein. Ändert weder die Batchgröße noch die Gleichzeitigkeit der Aufrufe; die Laufzeit kann das Skalierungsziel außer Kraft setzen. |
Für app-weite Standardeinstellungen siehe Polling host.json Einstellungen. Für Parameterformen und SDK-Anmerkungen siehe Bindungstypen.
Optionen zur Wahlregistrierung
Setzen Sie deliveryMode: 'Poll' einen benannten Helfer, den generischen connectorTrigger Helfer oder app.connectorTrigger, und konfigurieren Sie die Pollingverbindung sowie die Trigger-Konfiguration:
| Auswahl | Erforderlich | Default | Description |
|---|---|---|---|
deliveryMode |
Ja, für Umfragen | 'Webhook' |
Auf 'Poll' Polling verwenden. |
connection |
Yes | None | Identifiziert das Einstellungspräfix für den Polling-Endpunkt und die Identitätseinstellungen. Zum Beispiel wählt ConnectorNamespace__pollingEndpoint. 'ConnectorNamespace' |
triggerConfigName |
Yes | None | Identifiziert die Polling-Trigger-Konfiguration. Geben Sie den Namen direkt an oder verwenden Sie einen App-Einstellungsausdruck wie '%OnNewEmailTriggerConfigName%'. |
cardinality |
No | 'one' |
Setzen Sie ein, 'many' um Aufruf-Batching zu aktivieren. Batch-Aufrufe werden einzeln pro Listener verarbeitet. |
maxBatchSize |
No | Host-Standard: 1 |
Maximale Verbindungsereignisse pro Aufruf, von 1 bis 32. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultMaxBatchSize man von host.json. Ohne Batching muss die effektive Chargengröße betragen 1. |
maxConcurrentCalls |
No | Host-Standard: 16 |
Maximale gleichzeitige Einzelereignisbearbeitungsaufgaben pro Listener auf einer einzigen Instanz. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultMaxConcurrentCalls man von host.json. Muss nicht negativ sein. Gilt nicht für gebündelte Aufrufe. |
targetPendingEventThreshold |
No | Host-Standard: 16 |
Zielen Sie ausstehende Ereignisse pro Instanz für zielbasierte Skalierung an. Wenn ausgelassen oder auf 0gesetzt wird, verwendet defaultTargetPendingEventThreshold man von host.json. Muss nicht negativ sein. Ändert weder die Batchgröße noch die Gleichzeitigkeit der Aufrufe; die Laufzeit kann das Skalierungsziel außer Kraft setzen. |
Für app-weite Standardeinstellungen siehe Polling host.json Einstellungen. Für Handler-Eingabeformen siehe Bindungstypen.
Abrufendpunkt
Die Verbindungseinstellung der Funktion wählt das Präfix für den Polling-Endpunkt aus. Zum Beispiel verwendet ConnectorNamespace__pollingEndpointdas Präfix "ConnectorNamespace" . Definieren Sie diese Einstellung unter Values in local.settings.json für lokale Entwicklung oder in den App-Einstellungen für eine bereitgestellte Funktionsapp, wie in den Pollingbeispielen gezeigt.
Rufen Sie den Polling-Endpunkt aus dem Connector Namespace-Portal ab oder leiten Sie ihn wie folgt aus dem von der Triggerkonfiguration generierten pollingEndpoints.receiveUri Service ab. Ersetzen Sie die Platzhalter durch Ihre Ressourcenwerte.
Erfordert Azure CLI, jq, und 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"
Leeden Sie die Einstellung aus der dienstgenerierten Empfangs-URI wie folgt ab:
Dienst 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> |
Erhalten Sie den vom Service bereitgestellten Host- und Gateway-Kennung; raten Sie keinen Hostnamen oder konfigurieren Sie nicht die vollständige Empfangs-URL, einen Operationspfad, eine eigenständige /api Basis oder eine Abfragezeichenkette.
Die Erweiterung verwendet diesen Endpunkt mit dem Trigger-Konfigurationsnamen, um URLs für Polling-Operationen zu erstellen. Für die Anmeldedaten und Zugriffsrichtlinien, die zum Aufruf dieser URLs erforderlich sind, siehe Polling-Authentifizierung.
Polling-Trigger-Konfiguration
Der Trigger-Konfigurationsname der Funktion identifiziert die Konfiguration, aus der Ereignisse empfangen werden sollen.
Polling Trigger-Konfigurationswerte
| Konfigurationswert | Description |
|---|---|
| Verbindung | Die autorisierte verwaltete Verbindung, wie Office 365 Outlook oder SharePoint Online. Dies ist getrennt von der Verbindungseinstellung der Funktion, die ein App-Einstellungspräfix identifiziert. |
| Vorgangsname | Der Steckverbinder löst die Funktionsweise aus OnNewEmailV3 , wie zum Beispiel oder GetOnNewFileItems. |
| Parameters | Für die Operation benötigte Werte wie ein Outlook-Ordner oder eine SharePoint-Seite und Dokumentbibliothek. |
| Name der Trigger-Konfiguration | Der Name dieser Polling-Trigger-Konfiguration, direkt von der Funktion oder über eine App-Einstellung angespielt. |
| Liefermodus | Wie Ereignisse über Dienste bereitgestellt werden, entweder durch Umfragen oder Webhook-Modus. |
Eine Abfrage-Trigger-Konfiguration erstellen
Wenn du noch keinen Connector-Namensraum hast, erstelle einen Connector-Namensraum.
Gehe zum Connector Namespace-Portal und wähle dann deinen Namespace aus.
Im Namensraummenü wählen Sie Trigger und dann Erstellen.
Finde den verwalteten Connector, den du verwenden möchtest, und wähle dann das Ereignis aus, das die Funktion auslösen sollte.
Auf der Trigger-Konfigurationsseite erstellen Sie eine Verbindung oder wählen Sie eine bestehende Verbindung aus. Das Herstellen einer Verbindung erfordert eine einmalige Authentifizierung mit dem externen Dienst.
Gib die für das Event erforderlichen Eingaben bereit. Zum Beispiel erfordert das Office 365 Outlook New-Mail-Ereignis, dass der Ordner neue Nachrichten überwacht.
Wählen Sie für ZieltypAzure Functions.
Wählen Sie für den Auslieferungsmodus "Polling".
Überprüfen Sie die Konfiguration, und klicken Sie dann auf Erstellen.
Polling-Authentifizierung
Für das Abfragen gewähren Sie der verwalteten Identität der Funktionsapp (bereitgestellt) oder Ihrer Entwickleridentität (lokal) eine Zugriffsrichtlinie auf Verbindungsebene. Der Functions-Host nutzt die Microsoft Entra-Anmeldedaten dieser Identität, um Ereignisse über den Polling-Endpunkt zu empfangen und zu bestätigen. Der eigene Verbindungszugriff des Connector-Namespace wird automatisch abgewickelt.
Die Richtlinie des Aufrufers gewährt Zugriff auf die verwaltete Connector-Verbindung, nicht auf den Namespace selbst. Das Anmelden oder das Aktivieren einer verwalteten Identität gewährt dem Anrufer diesen Zugriff nicht automatisch.
Im Gegensatz zur Webhook-Auslieferung erfordert Polling keine öffentliche Callback-URL oder einen Funktions-App-Systemschlüssel, da die Funktions-App Ereignisse aus dem Namespace abruft, anstatt Rückrufe zu empfangen.
Die Authentifizierungseinstellungen in den folgenden Unterabschnitten verwenden das Präfix ConnectorNamespace, das den Triggerbeispielen entspricht. Wenn Ihre Funktion ein anderes Verbindungseinstellungspräfix verwendet, verwenden Sie stattdessen dieses Präfix.
Zugangsrichtlinien gewähren
Verwenden Sie beide Methoden, um dem Polling-Caller Zugriff auf die Verbindung zu gewähren. Sie benötigen Berechtigungen, um Zugriffsrichtlinien auf der Verbindung zu verwalten. Verwenden Sie die Principal-(Objekt-)ID des Anrufers, nicht dessen Anwendungs-(Client-)ID.
- Portal
- Azure CLI
- Gehe zum Connector Namespace-Portal und wähle dann deinen Namespace aus.
- Öffnen Sie Verbindungen und wählen Sie die verwaltete Connector-Verbindung aus, die von Ihrer Polling-Trigger-Konfiguration verwendet wird.
- Öffnen Sie die Registerkarte Zugriffsrichtlinien der Verbindung.
- Fügen Sie eine Zugriffsrichtlinie für die Identität des Anrufers hinzu. Für die lokale Entwicklung verwenden Sie die Objekt-ID Ihres Entwicklerkontos. Verwenden Sie für eine bereitgestellte Funktions-App die Haupt- (Objekt-)ID der verwalteten Identität, die Ihre App verwendet.
- Stellen Sie sicher, dass der Anrufer eine Zugriffsrichtlinie für die Verbindung hat.
Lokale Entwicklung
- Melden Sie sich mit Ihrer Entwickleridentität an, zum Beispiel indem Sie ausführen
az login. Dies ist das Microsoft Entra-Konto, das die Erweiterung verwendet, um Abholanfragen lokal zu authentifizieren. - Gewähren Sie eine Zugriffsrichtlinie für die verwaltete Connector-Verbindung für diese Identität. Das Anmelden allein gewährt keinen Zugriff auf die Verbindung.
- Definieren Sie die Verbindungseinstellungen unter
Valuesin local.settings.json. Lasse die Verwendung von Entwickler-Anmeldedaten wegConnectorNamespace__credential.
Ausgerollte Funktions-App
- Aktivieren Sie eine systemzugewiesene verwaltete Identität in der Funktions-App oder weisen Sie ihr eine benutzerdefinierte verwaltete Identität zu.
- Gewähren Sie eine Zugriffsrichtlinie für die verwaltete Connector-Verbindung für diese Identität.
- Konfigurieren Sie die folgenden Authentifizierungseinstellungen in den App-Einstellungen der Funktionsapp:
| App-Einstellung | Wert |
|---|---|
ConnectorNamespace__credential |
managedidentity |
ConnectorNamespace__clientId |
Die Client-ID der vom Benutzer zugewiesenen verwalteten Identität, die für das Abfragen verwendet werden soll. Nur bei Verwendung einer benutzerzugewiesenen Identität festlegen. |
Alternativ können ConnectorNamespace__managedIdentityResourceId Sie auf die Ressourcen-ID der benutzerzugewiesenen Identität setzen, anstatt zu setzen ConnectorNamespace__clientId. Für eine systemzugewiesene Identität lassen Sie beide Selektoren weg.
Umfrageverwendung
Der Functions-Host verbindet sich mit dem Connector-Namespace, um Ereignisse abzufragen und erfolgreiche Aufrufe zu bestätigen. Die Erweiterung leitet die Ereignisse an Ihre Funktion weiter; Sie schreiben keine Abfrageschleife.
Die Lieferung erfolgt mindestens einmal. Fehlgeschlagene Aufrufe werden nicht bestätigt, und Ereignisse können nach Ablauf der service-managed Sperre erneut ausgeliefert werden. Machen Sie die Verarbeitung idempotent.
Wenn Sie es für Deduplizierung verwenden ConnectorEvent<T>.MessageId , begrenzen Sie es auf den Namespace und die Trigger-Konfiguration; gehen Sie nicht davon aus, dass Message-IDs über Trigger hinweg eindeutig sind.
Setz DeliveryMode = ConnectorTriggerDeliveryMode.Poll auf [ConnectorTrigger], und gib die Connection Eigenschaften und TriggerConfigName an. Siehe die Umfragebeispiele.
Für Attributeigenschaften, unterstützte Werte und Standardwerte siehe Polling-Attributeigenschaften.
Set delivery_mode=func.DeliveryMode.POLL auf @app.connector_trigger, und liefer connection und trigger_config_name. Siehe die Umfragebeispiele.
Der Host erhält pro Aufruf ein Ereignis, sofern cardinality=func.Cardinality.MANY nicht das Batching aktiviert wird. Für Rohbatches verwenden typing.List[str] Sie oder typing.List[bytes]; unterstützte SDK-Anmerkungen liefern eine Liste von Modellen. Für Optionen, unterstützte Werte und Standardwerte siehe Polling Decorators.
Stellen Sie deliveryMode: 'Poll', und liefern connection Sie und triggerConfigName in den Registrierungsoptionen. Siehe die Umfragebeispiele.
Der Host erhält pro Aufruf ein Ereignis, sofern cardinality: 'many' nicht das Batching aktiviert wird. Benannte und generische Helfer fassen die Payload-Elemente aller Ereignisse in einem einzigen Kontext zusammen. Direkte Handler app.connectorTrigger erhalten stattdessen das äußere Ereignis-Array. Für Optionen, unterstützte Werte und Standardeinstellungen siehe Polling-Registrierungsoptionen.
Skalierung und Parallelität
Webhook-Lieferung
Im Webhook-Modus sendet der Connector-Namespace HTTP-Anfragen an den Callback-Endpunkt der Erweiterung. Connector-Trigger skalieren wie HTTP-Trigger, abhängig vom HTTP-Skalierungsverhalten und den Limits des Hosting-Plans. Details finden Sie unter Ereignisgesteuerte Skalierung in Azure Functions.
Umfrageergebnisse
Im Polling-Modus verwendet der Connector Trigger eine zielbasierte Skalierung basierend auf dem geschätzten Ereignisrückstand für die Triggerkonfiguration im Connector-Namespace. Das Skalierungsziel ist unabhängig von der pro-instanzlichen Verarbeitungskonkurenz und der Batchgröße. Für die Skalierungsgleichung, Konfigurationseinstellungen und Optimierungshinweise siehe Zielbasierte Skalierung von verwalteten Connectors.
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.
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.
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.
Attribute
Im Gegensatz zu Polling erfordert die Webhook-Auslieferung keine zusätzlichen Eigenschaften für das [ConnectorTrigger] Attribut, da Webhook der Standard-Bereitstellungsmodus ist. Du kannst es auch explizit festlegen DeliveryMode = ConnectorTriggerDeliveryMode.Webhook . Umfragespezifische Eigenschaften gelten nicht für Webhook-Lieferungen.
Konfiguration des Webhook-Triggers
Die Callback-URL der Trigger-Konfiguration identifiziert die Zielfunktion.
Webhook-Trigger-Konfigurationswerte
| Konfigurationswert | Description |
|---|---|
| Verbindung | Die autorisierte verwaltete Verbindung, wie Office 365 Outlook oder SharePoint Online. |
| Vorgangsname | Der Steckverbinder löst die Funktionsweise aus OnNewEmailV3 , wie zum Beispiel oder GetOnNewFileItems. |
| Parameters | Für die Operation benötigte Werte wie ein Outlook-Ordner oder eine SharePoint-Seite und Dokumentbibliothek. |
| Rückruf-URL | Der Webhook-Endpunkt der Connector-Erweiterung für die Zielfunktion. Siehe Webhook-Authentifizierung. |
| Funktionsname | Der Name der registrierten Funktion in deinem App-Code. |
| Authentication | Die Authentifizierungskonfiguration, mit der die Funktions-App aufgerufen wird. |
Der functionName Query-String-Wert in der Callback-URL muss mit dem registrierten Funktionsnamen übereinstimmen. Gültige Webhook-Funktionsnamen enthalten 1 bis 128 Buchstaben, Zahlen, Unterstreiche oder Bindestriche.
Eine Webhook-Triggerkonfiguration erstellen
Erstellen Sie eine Trigger-Konfiguration mithilfe der Azure CLI oder des Connector Namespace Portals.
Den Trigger konfigurieren
Eine Trigger-Konfiguration im Azure Connector Namespace verknüpft ein externes Service-Ereignis mit dem Callback der Zielfunktion.
Trigger-Konfigurationswerte
| Konfigurationswert | Description |
|---|---|
| Verbindung | Die autorisierte verwaltete Verbindung, wie Office 365 Outlook oder SharePoint Online. |
| Vorgangsname | Der Steckverbinder löst die Funktionsweise aus OnNewEmailV3 , wie zum Beispiel oder GetOnNewFileItems. |
| Parameters | Für die Operation benötigte Werte wie ein Outlook-Ordner oder eine SharePoint-Seite und Dokumentbibliothek. |
| Rückruf-URL | Der Webhook-Endpunkt der Connector-Erweiterung für die Zielfunktion. Siehe Webhook-Authentifizierung. |
| Funktionsname | Der Name der registrierten Funktion in deinem App-Code. |
| Authentication | Die Authentifizierungskonfiguration, mit der die Funktions-App aufgerufen wird. |
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:
| Konnektor-Ereignis | Vorgangsname | Funktionsname |
|---|---|---|
| Neue Office 365 Outlook-E-Mail | OnNewEmailV3 |
OnNewEmail |
| Neue SharePoint Online-Datei | GetOnNewFileItems |
OnSharepointNewFile |
| Neue Microsoft Teams-Kanalnachricht | OnNewChannelMessage |
OnNewChannelMessage |
| Ausgewähltes Connector-Ereignis | Die in der Trigger-Konfiguration ausgewählte Operation | OnConnectorEvent |
| Konnektor-Ereignis | Vorgangsname | Funktionsname |
|---|---|---|
| Neue Office 365 Outlook-E-Mail | OnNewEmailV3 |
OnNewEmail |
| Neue SharePoint Online-Datei | GetOnNewFileItems |
OnSharepointNewFile |
| Ausgewähltes Connector-Ereignis | Die in der Trigger-Konfiguration ausgewählte Operation | OnConnectorEvent |
Erstellen Sie eine Trigger-Konfiguration
Erstellen Sie eine Trigger-Konfiguration mithilfe der Azure CLI oder des Connector Namespace Portals.
Bevor die Erweiterung ein Ereignis empfangen kann, erstellen Sie diese Ressourcen und Konfigurationen:
- Ein Connector-Namensraum.
- Eine verwaltete Verbindung, die autorisiert ist, auf den externen Dienst zuzugreifen.
- Eine Trigger-Konfiguration, die das Connector-Ereignis, die Betriebsparameter und den Bereitstellungsmodus auswählt.
Für die Webhook-Bereitstellung umfasst die Trigger-Konfiguration auch die Callback-URL und die Callback-Authentifizierung.
Trigger-Konfigurationen sind Connector-Namespace-Ressourcen, die Sie auch über ARM oder Bicep bereitstellen können.
Die untenstehenden Azure CLI-Beispiele verwenden eine deployierte Funktionsapp. Stellen Sie die App mit der Erweiterung und der Zielfunktion bereit, bevor Sie sie ausführen.
Das folgende Bash-Beispiel verwendet Azure CLI undjq, um einen Office 365 Outlook Neue-Mail-Trigger zu erstellen. Ersetzen Sie die Platzhalterwerte für Ihre Ressourcen und Ihre Verbindung:
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
Der Wert --parameters ist spezifisch für den Steckverbinderbetrieb. In diesem Beispiel folderPath wählt er den Outlook-Ordner aus, den überwacht werden soll. Die Rückruf-URL enthält keinen Systemschlüssel. Das notificationDetails.authentication Objekt fügt den Schlüssel als Geheimnis der Abfrage-String hinzu, wenn Connector Namespace die Funktion aufruft.
Webhook-Authentifizierung
Der Connector-Namespace sendet Ereignisse an die Funktionsapp, anstatt dass die Funktions-App den Namespace abfragt. Standardmäßig authentifiziert der Functions-Host diese Callbacks, indem er den Systemschlüssel der Connector-Erweiterung mit dem Namen connector_extension. validiert.
Der Connector-Namespace verwaltet den Zugriff auf seine verwaltete Connector-Verbindung automatisch. Im Gegensatz zum Abfragen benötigt die Identität der Funktions-App keine Verbindungszugriffsrichtlinie, nur um Webhook-Rückrufe zu empfangen; der Systemschlüssel autorisiert diese Anfragen an die Funktionsapp.
Webhook-Callback-URL
Bereitgestellte App
Verwenden Sie den Callback-Endpunkt der Erweiterung ohne Schlüssel in der URL:
https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>
Der functionName Wert muss mit dem registrierten Funktionsnamen übereinstimmen: dem [Function] Attribut in C#, dem @app.function_name Dekorator in Python oder der Trigger-Registrierung in Node.js.
Für eine bereitgestellte Anwendung mit Standardauthentifizierung verwenden Sie den connector_extension Systemschlüssel der Connector-Erweiterung und nicht eine einzelne Funktionstaste. Nachdem Sie die Funktions-App mit der Erweiterung bereitgestellt haben, rufen Sie den Systemschlüssel ab:
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "systemKeys.connector_extension" \
--output tsv
Speichern Sie in der Trigger-Konfiguration den Schlüssel in notificationDetails.authentication, getrennt von der Callback-URL:
{
"notificationDetails": {
"callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
"authentication": {
"type": "QueryString",
"name": "code",
"value": "<CONNECTOR_EXTENSION_KEY>"
}
}
}
Beim Ausführen eines Ereignisses fügt der Connector-Namespace den Schlüssel als Query-String-Parameter code hinzu. Wenn der Schlüssel von der gespeicherten Rückruf-URL getrennt bleibt, kann das Portal ihn als Geheimnis tarnen. Fügen Sie den Schlüssel nicht in die gespeicherte Callback-URL ein oder setzen Sie ihn nicht auf die Quellcodekontrolle.
Bestehende Trigger-Konfigurationen, die den Schlüssel in der Callback-URL enthalten, funktionieren weiterhin. Wenn du eine bestehende Trigger-Konfiguration bearbeitest und speicherst, wechselt die Taste zu notificationDetails.authentication.
Systemschlüssel können nicht pro Trigger erfasst werden und erfordern eine koordinierte Rotation zwischen der Funktions-App und dem Connector-Namespace. Für identitätsbasierte Rückrufe ohne gemeinsamen Schlüssel siehe Integrierte Authentifizierung.
Lokale Webhook-Entwicklung
Webhook-Callbacks müssen Ihren laufenden Functions-Host über den Connector-Namensraum erreichen. Wenn Sie lokal ausführen:
Starten Sie die Funktions-App mit Azure Functions Core Tools und aktivieren Sie die Autorisierung:
func start --enableAuthImportant
Immer verwenden
--enableAuth, wenn du deine App über einen Dev-Tunnel freilegst. Ohne sie ist dein Funktionsendpunkt im öffentlichen Internet völlig unauthentifiziert.Verwenden Sie einen Microsoft-Dev-Tunnel, um einen öffentlichen HTTPS-Endpunkt an den lokalen Functions-Hostport weiterzuleiten. Setzen Sie die Sichtbarkeit des Tunnelports auf Öffentlich , damit der Connector-Namespace ihn erreichen kann.
Erstellen Sie die Callback-URL mit dem Tunnel-Hostnamen und dem registrierten Funktionsnamen und verwenden Sie sie in der Webhook-Trigger-Konfiguration. Zum Beispiel verwendet ein Tunnel-Weiterleitungsport 7071 an die Funktion
OnNewFileeine URL wie:https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFileFür einen lokalen Host, der Geheimnisse in Azurite speichert, rufen Sie seinen
connector_extensionSystemschlüssel mithilfe dieser PowerShell-Befehle ab. Auf die bekannte Azurite-Verbindungszeichenfolge gesetzt$connStr:$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.jsonSpeichern Sie den
connector_extensionSystemschlüssel des lokalen Hosts separat innotificationDetails.authentication, imQueryStringoben gezeigten Authentifizierungsformat.Halte den Host und den Tunnel während des Tests am Laufen. Aktualisieren Sie die Trigger-Konfiguration, wenn sich der Tunnel-Hostname ändert.
Integrierte Authentifizierung
Für Webhook-Callbacks ohne gemeinsame Schlüssel verwenden Sie die integrierte App Service-Authentifizierung (auch Easy Auth genannt) mit einer verwalteten Identität. Diese Konfiguration ist unabhängig von der Programmiersprache der Funktion.
Der Connector-Namespace verwendet seine systemzugewiesene oder benutzerzugewiesene verwaltete Identität, um für jeden Callback einen Microsoft Entra ID-Token anzufordern. Die integrierte Authentifizierung validiert das Token und die Identität des Anrufers, bevor die Anfrage den Functions-Host erreicht. Für eine End-to-End-Implementierung ohne Client-Secrets siehe das integrierte Authentifizierungsbeispiel.
Dieser Abschnitt behandelt die Authentifizierung vom Namespace zur Funktionsapp. Der Connector-Namespace verwaltet den Zugriff auf seine verwaltete Connector-Verbindung automatisch. Zur Authentifizierung für Upstream-Dienste siehe Azure-Connectoren-Überblick.
Konfiguration von Funktions-Apps
Important
Diese Konfiguration erfordert Authentifizierung über die gesamte Funktionsapp, nicht nur /runtime/webhooks/connectorhinweg, und schränkt den Zugriff auf die Callback-Identität des Namespaces ein. Bestehende HTTP-Funktionen, die Funktionstasten benötigen, benötigen diese Tasten zusätzlich zur App-Authentifizierung weiterhin. Bevor Sie diese Konfiguration auf eine bestehende App anwenden, stellen Sie sicher, dass API-Clients und Gesundheitsproben die App-Authentifizierungs- und Autorisierungsrichtlinie sowie alle Anforderungen an Funktionsschlüssel erfüllen können. Andernfalls können Anfragen mit HTTP 401 oder 403 scheitern. Wenn die App andere Anrufer akzeptieren muss, passen Sie die Autorisierungsrichtlinie an, anstatt diese Erlaubnisliste unverändert zu kopieren. Für Richtlinienoptionen siehe Microsoft Entra-Autorisierung konfigurieren.
Konfigurieren Sie die integrierte Authentifizierung über die authsettingsV2 ARM-Ressource der Funktionsapp oder deren Äquivalent in Bicep. Das Beispiel verwendet die folgenden Schlüsseleinstellungen:
| Setting | Purpose |
|---|---|
platform.enabled: true |
Aktiviert integrierte Authentifizierung. |
globalValidation.requireAuthentication: true |
Erfordert Authentifizierung, bevor Anfragen den Functions-Host erreichen. |
globalValidation.unauthenticatedClientAction: Return401 |
Gibt HTTP 401 für nicht authentifizierte Rückrufe zurück, anstatt auf eine Anmeldeseite umzuleiten. |
identityProviders.azureActiveDirectory.enabled: true |
Aktiviert die Microsoft Entra-Tokenvalidierung. |
registration.clientId |
Die Anwendungs- (Client-)ID der Microsoft Entra-App-Registrierung, die die Funktions-App repräsentiert. |
registration.openIdIssuer |
Die Aussteller-URL für Ihren Mandanten: https://login.microsoftonline.com/{tenantId}/v2.0. |
validation.allowedAudiences |
Die Client-ID und die Bezeichner-URI der Entra-App. Token müssen im Anspruch aud ein erlaubtes Publikum haben. |
validation.defaultAuthorizationPolicy.allowedPrincipals.identities |
Die Objekt-(Haupt-)IDs dürfen die Funktions-App aufrufen. Das Beispiel erlaubt nur die verwaltete Callback-Identität des Namespaces. Passen Sie diese Richtlinie an, wenn Ihre App andere Anrufer hat. Ein gültiger Token mit einem oid Anspruch, der nicht in der Erlaubtenliste steht, wird mit HTTP 403 abgelehnt. |
Die und registrationvalidation Einstellungen in dieser Tabelle sind unter identityProviders.azureActiveDirectory.
Das Beispiel weist der Funktionsapp außerdem eine vom Benutzer zugewiesene verwaltete Identität zu und federiert sie mit der Registrierung der Entra-App. Die integrierte Authentifizierung nutzt diese föderierte Identitätsanmeldeinformation , um Client-Assertions zu erhalten, ohne ein Client-Geheimnis zu speichern. Das Beispiel setzt die App-Einstellung OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID auf die Client-ID der Funktions-App-Identität und setzt registration.clientSecretSettingName sie auf den Namen dieser Einstellung.
Die für die Föderation verwendete Funktions-App-Identität ist von der Callback-Identität des Namespaces getrennt. Die Identität des Namensraums ist der Aufrufer, der durch zugelassen ist allowedPrincipals.identities.
Nachdem die integrierte Authentifizierung zur Validierung von Callbacks konfiguriert wurde, deaktivieren Sie die redundante Systemschlüssel-Überprüfung in host.json:
{
"version": "2.0",
"extensions": {
"connector": {
"system": {
"webhookAuthorizationLevel": "Anonymous"
}
}
}
}
Verwenden Sie Anonymous nur, wenn eine andere Authentifizierungsschicht Anfragen validiert, bevor sie den Functions-Host erreichen. Diese Einstellung aktiviert die Token-Validierung nicht von allein.
Konfiguration des Konnektor-Namespaces
Aktivieren Sie eine systemzugewiesene verwaltete Identität im Connector-Namensraum oder fügen Sie eine benutzerzugewiesene Identität daran an. In der Trigger-Konfiguration notificationDetails.authenticationsetzen Sie folgendes:
| Property | Wert |
|---|---|
type |
ManagedServiceIdentity |
audience |
Die Client-ID der Entra-App-Registrierung, die einem von der Funktionsapp akzeptierten Zielgruppe entspricht. |
identity |
Die Ressourcen-ID der angehängten, vom Benutzer zugewiesenen verwalteten Identität. Lassen Sie diese Eigenschaft für eine systemzugeordnete Identität weg. |
Der Namespace nutzt diese Identität, um einen Token zu erhalten und sendet ihn im Header des Authorization: Bearer <token> Callbacks. Das Token iss identifiziert den Mandanten, aud identifiziert die Ziel-App und oid identifiziert die verwaltete Identität des Namespaces.
Der Namespace verwaltet seinen eigenen Zugriff auf die verwaltete Connector-Verbindung automatisch. Dieser Zugriff ist getrennt von der Callback-Autorisierung, die Sie über die integrierte Authentifizierung in der Funktions-App konfigurieren.
Authentifizierungsablauf und Validierung
- Der Connector-Namespace erhält einen Token für die konfigurierte Zielgruppe mithilfe seiner Callback-verwalteten Identität.
- Der Namespace sendet das Token mit dem Ereignis an den Webhook-Endpunkt der Erweiterung.
- Die integrierte Authentifizierung validiert die Signatur, Ablaufdatum, Emittenten und Zielgruppe des Tokens und überprüft, ob er
oidmit einer erlaubten Identität übereinstimmt. Fehlende oder ungültige Token erhalten HTTP 401; gültige Token einer Identität, die nicht in der Erlaubtenliste steht, erhalten HTTP 403. - Nur autorisierte Anfragen erreichen den Funktionshost. Mit deaktivierter Überprüfung des redundanten Systemschlüssels ruft die Erweiterung die Zielfunktion auf und bindet den Ereigniskörper an dessen Parameter.
Ihre Funktion benötigt keinen Anwendungscode, um diese Zugriffsprüfungen durchzuführen.
Verwandte Authentifizierungsdokumentation
- Authentifizierung und Autorisierung in Azure App Service und Azure Functions
- Konfigurieren Sie Ihre App Service- oder Azure Functions-App für die Nutzung der Microsoft Entra-Anmeldung
- Dateibasierte Konfiguration in der App Service-Authentifizierung
- Workload-Identitätsverbund in Microsoft Entra ID
- Verwaltete Identitäten für Azure-Ressourcen
Webhook-Nutzung
Der Connector-Namespace sendet Ereignisse an den Webhook-Endpunkt der Erweiterung, wo der Wert der functionName Query-String die Funktion auswählt. Die Erweiterung bindet den Ereigniskörper an Ihren Funktionsparameter; Sie implementieren keinen HTTP-Handler.
Der Funktionsname muss mit dem Namen in Ihrem Attribut [Function] übereinstimmen. Callbacks können Header enthalten x-ms-* , die die Trigger-Konfiguration, die Verbindung, den Ereignistyp und die Korrelations-ID identifizieren, aber diese Header sind Ihrer Funktion über den Connector Trigger nicht zugänglich.
Verwenden Sie [ConnectorTrigger] ohne Poling-Eigenschaften. Webhook ist der Standard, wenn du wegfällst DeliveryMode. Siehe die Webhook-Beispiele.
Ihre Funktion kann die Ereignis-Payload mit jedem der unterstützten .NET-Bindungstypen empfangen.
Die Erweiterung akzeptiert HTTP POST und PUT Anfragen mit dem Inhaltstyp application/json . Ein nichtleerer Anforderungskörper muss gültiges JSON enthalten. Anfragen unterliegen der Funktionen-Host-Anfrage-Grenze und der Upstream-Service-Begrenzungen; die Erweiterung legt keine separate Payload-Größenobergrenze fest.
Um das Host-Request-Body-Limit zu konfigurieren, setzen Sie die app-weite FUNCTIONS_REQUEST_BODY_SIZE_LIMIT App-Einstellung in Bytes und starten Sie den Host neu. Dies ist keine Einstellung host.json und ändert nicht die Downloads von Poll-Linked-Outputs, die verwenden extensions.connector.maxLinkedOutputSizeInBytes. Größere Grenzen garantieren keine unterstützten Nutzlastgrößen; berücksichtigen Pufferung, Arbeitsspeicher und Upstream-Grenzen.
Webhook-Nutzung
Der generische Helfer erhält ein ConnectorTriggerContext<T>. Seine Eigenschaft enthält den normalisierten Callback-Envelope payload , items enthält die Ereigniselemente und rawPayload bewahrt die geparste Eingabe vor der Normalisierung bei. Connector-spezifische Registrierungen liefern benannte Arrays wie emails, records, oder messages.
Jeder Aufruf verarbeitet einen Callback, der mehrere Payload-Elemente enthalten kann. Für einen Vorgang ohne connector-spezifische Registrierung ist der TypeScript-Elementtyp standardmäßig auf unknown. Validiere die Nutzlast, bevor du auf operation-spezifische Eigenschaften zugreifst. Für unterstützte typisierte Registrierungen siehe die Node.js-Connector-Erweiterungsreferenz.
Webhook-Nutzung
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.
Jede Invocation behandelt einen Callback. Unterstützte SDK-Bindungen liefern ihre Payload-Elemente als Liste; verwenden Sie eine Anmerkung wie list[office365.GraphClientReceiveMessage]. Für die unterstützten operationsspezifischen Anmerkungen siehe die Operation Signature-Zuordnung.
Die Erweiterung akzeptiert HTTP POST und PUT Anfragen mit dem Inhaltstyp application/json . Ein nichtleerer Anforderungskörper muss gültiges JSON enthalten. Anfragen unterliegen dem Host-Request-Body-Limit von Functions und den Upstream-Service-Grenzen.
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.