Connector extensie voor Azure Functions overzicht (Preview)

De Connector-extensie biedt de inbound triggerbinding die een functie uitvoert wanneer een gebeurtenis plaatsvindt in een dienst die via een beheerde connector is verbonden. Om operaties aan te roepen en acties uit te voeren in deze verbonden services vanuit je functiecode, gebruik je een Azure Connectors SDK, die momenteel beschikbaar is voor .NET, Node.jsen Python. Voor meer informatie over triggers, SDK-acties en wanneer beheerde connectoren te gebruiken, zie Use managed connectors in Azure Functions.

Hoe de uitbreiding werkt

Een connector-getriggerde functie gebruikt deze componenten:

Wanneer een geconfigureerd event optreedt, stuurt de Connector Namespace het event naar het webhook-eindpunt van de extensie. De extensie gebruikt de functionName querystringwaarde om de functie te selecteren en geeft het JSON-gebeurtenislichaam door aan de triggerparameter. De Functions-host valideert de systeemsleutel voordat de extensie het verzoek verwerkt, tenzij je een andere authenticatielaag configureert zoals beschreven in Authenticate callbacks.

In een .NET geïsoleerde worker-functie, pas [ConnectorTrigger] je toe op de parameter die het event body ontvangt.

De extensie installeren

De Connector-trigger ondersteunt het .NET geïsoleerde werkermodel. Voor informatie over ondersteunde .NET-versies binnen Azure Functions runtime-versies, zie Talen per runtime-versie.

Voeg het preview-Connector-extensiepakket toe aan je project:

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

Om sterk getypeerde payloadmodellen of call managed connector-operaties te gebruiken, voeg je ook de preview Azure Connectors SDK toe:

dotnet add package Azure.Connectors.Sdk --prerelease

Voor huidige pakketversies en complete projecten, zie de Azure Functions connectorvoorbeelden voor .NET.

De extensie installeren

Installeer de pakketten die door de Connector-trigger worden gebruikt:

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

Deze pakketten bieden de volgende functionaliteit:

• @azure/functions levert de basisregistratie connectorTrigger , die de triggerinvoer ontvangt als een generiek type dat standaard op unknown.
• @azure/functions-extensions-connectors wikkelt de invoer in een genormaliseerde connectortriggercontext en levert getypeerde contexten voor ondersteunde connectoroperaties.
• @azure/connectors, de preview Azure Connectors SDK voor Node.js, biedt de payloadmodellen die door die contexten en clients worden gebruikt voor het aanroepen van connectoroperaties.

Configureer je app om versie 4.42.0 of later van de preview-extensiebundel in het host.json-bestand te gebruiken:

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

Voor huidige pakketversies en volledige projecten, zie de Azure Functions connectorvoorbeelden voor TypeScript.

De extensie installeren

Gebruik het Python v2 programmeermodel en installeer de pakketten die vereist zijn door de Connector-trigger:

azure-functions>=2.2.0
azurefunctions-extensions-connectors

De core azure-functions Python-bibliotheek kan de triggerpayload binden aan str, dict, of bytes. Het azurefunctions-extensions-connectors-pakket integreert de Azure Connectors SDK voor Python en registreert extra converters voor de operation-specifieke SDK-annotaties die het ondersteunt.

Configureer je app om versie 4.42.0 of later van de preview-extensiebundel in het host.json-bestand te gebruiken:

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

Voor huidige pakketversies en complete projecten, zie de Azure Functions connectorvoorbeelden voor Python.

Bindingstypen

De Connector-trigger ondersteunt deze parametertypen voor .NET geïsoleerde werkerfuncties:

Voor codevoorbeelden en operationeel gebruikslastgedrag, zie de Connector-triggerreferentie.

Om te bepalen welke connectoroperaties sterk getypeerde .NET-payloadmodellen hebben, zie Operations to Azure Functions signature mapping.

Bindingstypen

De basisregistratie connectorTrigger geeft de triggerinvoer door aan een generiek handlertype dat standaard op unknown. Het @azure/functions-extensions-connectors pakket parseert de ruwe invoer in een ConnectorTriggerContext<T> met de genormaliseerde payload en items eigenschappen, de originele rawPayload, en operation-specifieke getypeerde contexten wanneer beschikbaar. Voor operaties zonder getypte registratie gebruik je de generieke context en valideer je de unknown payload voordat je de inhoud benadert.

Om te bepalen welke connectoroperaties sterk getypeerde TypeScript-payloadmodellen hebben, zie Operations to Azure Functions signature mapping.

Bindingstypen

De Connector-trigger ondersteunt deze Python-parametertypen:

Om te bepalen welke connectoroperaties een geregistreerde Python-converter hebben en of de annotatie één item of een collectie vertegenwoordigt, zie Operations to Azure Functions signature mapping. Gebruik str, dict, of bytes voor bewerkingen die geen ondersteunde SDK-annotatie hebben.

Configureer connectorbronnen

Voordat de uitbreiding een event kan ontvangen, maak je deze resources en configuraties aan:

1. Een Connector-naamruimte.
2. Een beheerde connectorverbinding die gemachtigd is om toegang te krijgen tot de externe dienst.
3. Een triggerconfiguratie die het connector-event selecteert en de bestemmingsfunctie identificeert.

De triggerconfiguratie omvat de managed connector-verbinding, operatienaam, operationele parameters, callback-URL en callback-authenticatie. Voor de configuratiewaarden en instructies voor het aanmaken van een trigger met Azure CLI of het Connector Namespace-portaal, zie Configureer de trigger.

Authenticeer callbacks

Standaard maakt de Connector-extensie een functie-app systeemsleutel aan met de naam connector_extension. Haal de sleutel op door te voeren:

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

Configureer de callback-URL zonder de sleutel:

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

Sla de sleutel apart op in notificationDetails.authentication:

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

Bij het terugbellen voegt de Connector Namespace de sleutel toe als de code querystringparameter. Door de sleutel gescheiden te houden van de opgeslagen callback-URL kan het portaal het als een geheim maskeren.

Voor implementaties die identiteitsgebaseerde callback-authenticatie vereisen, gebruik App Service ingebouwde authenticatie met een beheerde identiteit in plaats van een gedeelde systeemsleutel. Voor het volledige patroon, zie Authenticate your functions to a connector namespace.

host.json-instellingen

De standaard systeemsleutelauthenticatie vereist geen connector-specifieke instellingen in het host.json-bestand .

Wanneer de ingebouwde App Service-authenticatie callbacks vanuit de connectornaamruimte valideert, kun je de redundante systeemsleutelcontrole uitschakelen:

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

Gebruik alleen Anonymous wanneer een andere authenticatielaag, zoals de ingebouwde App Service authenticatie, verzoeken valideert voordat ze de Functions-host bereiken.

Voor een volledige implementatie van deze taalonafhankelijke app-configuratie, zie het ingebouwde authenticatievoorbeeld.

Volgende stappen 

• Managed connector trigger for Azure Function
• Gebruik beheerde connectoren in Azure Functions
• Azure Functions Connectors Samples
• Wat is Azure Connector-naamruimte?
• Connectorreferentie