Connector Extension for Azure Functions overview (Preview)

Die Connector-Erweiterung stellt die eingehende Triggerbindung bereit, die eine Funktion ausführt, wenn ein Ereignis in einem über einen verwalteten Connector verbundenen Dienst auftritt. Um Operationen aufzurufen und Aktionen in diesen verbundenen Diensten aus Ihrem Funktionscode auszuführen, verwenden Sie ein Azure Connectors SDK, das derzeit für .NET, Node.jsund Python verfügbar ist. Für weitere Informationen zu Triggern, SDK-Aktionen und wann Sie Managed Connectors verwenden sollten, siehe Use Managed Connectors in Azure Functions.

Wie die Erweiterung funktioniert

Eine vom Stecker ausgelöste Funktion verwendet folgende Komponenten:

Wenn ein konfiguriertes Ereignis auftritt, sendet der Connector Namespace das Ereignis an den Webhook-Endpunkt der Erweiterung. Die Erweiterung verwendet den Wert der functionName Abfragezeichenkette, um die Funktion auszuwählen, und übergibt den JSON-Ereigniskörper an den Triggerparameter. Der Functions-Host validiert den Systemschlüssel, bevor die Erweiterung die Anfrage verarbeitet, es sei denn, Sie konfigurieren eine andere Authentifizierungsschicht wie in Authenticate Callbacks beschrieben.

In einer .NET-isolierten Worker-Funktion wird auf den Parameter angewendet[ConnectorTrigger], der den Ereigniskörper empfängt.

Installieren der Erweiterung

Der Connector-Trigger unterstützt das .NET isolierte Worker-Modell. Informationen zu unterstützten .NET-Versionen in Azure Functions-Laufzeitversionen finden Sie unter Sprachen nach Laufzeitversion.

Füge das Vorschau-Connector-Erweiterungspaket zu deinem Projekt hinzu:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector --prerelease

Um stark typisierte Payload-Modelle oder Call Managed Connector-Operationen zu verwenden, fügen Sie außerdem das Vorschau-Azure Connectors SDK hinzu:

dotnet add package Azure.Connectors.Sdk --prerelease

Für aktuelle Paketversionen und vollständige Projekte siehe die Azure Functions-Connector-Beispiele für .NET.

Installieren der Erweiterung

Installieren Sie die vom Connector-Trigger verwendeten Pakete:

npm install @azure/functions @azure/functions-extensions-connectors @azure/connectors

Diese Pakete bieten folgende Funktionalität:

• @azure/functions stellt die Basisregistrierung connectorTrigger bereit, die die Triggereingabe als generischen Typ erhält, der standardmäßig auf unknown.
• @azure/functions-extensions-connectors umwickelt den Eingang in einen normalisierten Connector-Triggerkontext und stellt typisierte Kontexte für unterstützte Steckeroperationen bereit.
• @azure/connectors, die Vorschau Azure Connectors SDK für Node.js, stellt die Nutzlastmodelle bereit, die von diesen Kontexten und Clients für das Aufrufen von Connector-Operationen verwendet werden.

Konfigurieren Sie Ihre App so, dass sie Version 4.42.0 oder höher des Preview-Erweiterungspakets in der host.json-Datei verwendet:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Für aktuelle Paketversionen und komplette Projekte siehe die Azure Functions-Connector-Beispiele für TypeScript.

Installieren der Erweiterung

Verwenden Sie das Python v2 Programmiermodell und installieren Sie die Pakete, die vom Connector-Trigger benötigt werden:

azure-functions>=2.2.0
azurefunctions-extensions-connectors

Die Core Azure-Functions Python-Bibliothek kann die Trigger-Nutzlast an str, dict, oder bytesbinden. Das azurefunctions-extensions-connectors-Paket integriert das Azure Connectors SDK für Python und registriert zusätzliche Konverter für die betriebsspezifischen SDK-Annotationen, die es unterstützt.

Konfigurieren Sie Ihre App so, dass sie Version 4.42.0 oder höher des Preview-Erweiterungspakets in der host.json-Datei verwendet:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Für aktuelle Paketversionen und komplette Projekte siehe die Azure Functions-Connector-Beispiele für Python.

Bindungstypen

Der Connector-Trigger unterstützt diese Parametertypen für .NET-isolierte Worker-Funktionen:

Für Codebeispiele und betriebsspezifisches Nutzlastverhalten siehe die Connector-Trigger-Referenz.

Um zu bestimmen, welche Connector-Operationen stark typisierte .NET-Payload-Modelle haben, siehe Operations to Azure Functions signature mapping.

Bindungstypen

Die Basisregistrierung connectorTrigger leitet die Triggereingabe an einen generischen Handler-Typ weiter, der standardmäßig auf unknown. Das Paket @azure/functions-extensions-connectors parst die rohe Eingabe in eine ConnectorTriggerContext<T> mit den normalisierten payload und items Eigenschaften, dem ursprünglichen rawPayloadund operation-spezifischen typisierten Kontexten, wenn verfügbar. Für Operationen ohne getippte Registrierung verwenden Sie den generischen Kontext und validieren Sie die unknown Nutzlast, bevor Sie auf deren Inhalt zugreifen.

Um zu bestimmen, welche Connector-Operationen stark typisierte TypeScript-Payload-Modelle haben, siehe Operations to Azure Functions Signature Mapping.

Bindungstypen

Der Connector-Trigger unterstützt diese Python-Parametertypen:

Um zu bestimmen, welche Connector-Operationen einen registrierten Python-Konverter haben und ob die Annotation ein Element oder eine Sammlung darstellt, siehe Operations to Azure Functions Signature Mapping. Verwenden strSie , dict, oder bytes für Operationen, die keine unterstützte SDK-Annotation haben.

Connector-Ressourcen konfigurieren

Bevor die Erweiterung ein Ereignis empfangen kann, erstellen Sie diese Ressourcen und Konfigurationen:

1. Ein Connector-Namensraum.
2. Eine verwaltete Verbindung, die autorisiert ist, auf den externen Dienst zuzugreifen.
3. Eine Trigger-Konfiguration, die das Connector-Event auswählt und die Zielfunktion identifiziert.

Die Trigger-Konfiguration umfasst die Managed-Connector-Verbindung, den Operationsnamen, die Operationsparameter, die Callback-URL und die Callback-Authentifizierung. Für die Konfigurationswerte und Anweisungen zur Erstellung eines Triggers mittels Azure CLI oder des Connector Namespace-Portals siehe Trigger konfigurieren.

Authentifiziere Rückrufe

Standardmäßig erstellt die Connector-Erweiterung einen Funktions-App-Systemschlüssel namens connector_extension. Holen Sie den Schlüssel ab, indem Sie ausführen:

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

Konfigurieren Sie die Rückruf-URL ohne den Schlüssel:

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

Speichern Sie den Schlüssel separat in notificationDetails.authentication:

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

Beim Rückruf fügt der Connector-Namensraum den Schlüssel als Abfragestring-Parameter code hinzu. Wenn der Schlüssel von der gespeicherten Rückruf-URL getrennt bleibt, kann das Portal ihn als Geheimnis tarnen.

Für Deployments, die identitätsbasierte Rückrufauthentifizierung erfordern, verwenden Sie die integrierte App Service-Authentifizierung mit einer verwalteten Identität anstelle eines gemeinsamen Systemschlüssels. Für das vollständige Muster siehe Authenticate your functions to a connector namespace.

Einstellungen für „host.json“

Die Standard-Systemschlüssel-Authentifizierung erfordert keine connector-spezifischen Einstellungen in der host.json-Datei .

Wenn die integrierte App Service-Authentifizierung Rückrufe aus dem Connector-Namensraum validiert, können Sie die redundante Systemschlüsselprüfung deaktivieren:

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

Verwenden Anonymous Sie nur, wenn eine andere Authentifizierungsschicht, wie die integrierte App Service-Authentifizierung, Anfragen validiert, bevor sie den Funktionshost erreichen.

Für eine vollständige Implementierung dieser sprachunabhängigen App-Konfiguration siehe das integrierte Authentifizierungsbeispiel.

Nächste Schritte

• Managed connector trigger for Azure Function
• Verwenden Sie verwaltete Connectors in Azure Functions
• Azure Functions Connectors Samples
• Was ist Azure Connector-Namespace?
• Steckverbinder-Referenz