Connector extension for Azure Functions overview (Preview)

Rozszerzenie Connector zapewnia przychodzące wiązanie wyzwalające, które uruchamia funkcję, gdy wystąpi zdarzenie w usłudze połączonej przez zarządzany konektor. Aby wywołać operacje i wykonać działania w tych połączonych usługach z kodu funkcji, użyj Azure Connectors SDK, które jest obecnie dostępne dla .NET, Node.jsi Python. Więcej informacji o wyzwalaczach, akcjach SDK oraz terminach stosowania zarządzanych konektorów można znaleźć w artykule Używaj zarządzanych łączników w Azure Functions.

Jak działa przedłużenie

Funkcja wyzwalana przez złącze wykorzystuje następujące elementy:

Gdy wystąpi skonfigurowane zdarzenie, przestrzeń nazw Connector wysyła to zdarzenie do punktu końcowego webhooka rozszerzenia. Rozszerzenie wykorzystuje wartość stringu functionName zapytania do wyboru funkcji i przekazuje ciało zdarzenia JSON parametrowi wyzwalającemu. Host Functions weryfikuje klucz systemowy przed przetworzeniem żądania przez rozszerzenie, chyba że skonfigurujesz inną warstwę uwierzytelniania, jak opisano w callbackach Authenticate.

W izolowanej funkcji roboczej .NET należy zastosować [ConnectorTrigger] parametr otrzymujący ciało zdarzenia.

Instalowanie rozszerzenia

Wyzwalacz Connector obsługuje model .NET izolowanego pracownika. Informacje o wspieranych wersjach .NET w wersjach Azure Functions w czasie uruchomieniowym można znaleźć w sekcji Languages by runtime version.

Dodaj pakiet rozszerzenia podglądowego Connector do swojego projektu:

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

Aby używać silnie typowanych modeli payload lub wywołać operacje zarządzanego łącznika, dodaj także podgląd Azure Connectors SDK:

dotnet add package Azure.Connectors.Sdk --prerelease

Aktualne wersje pakietów i kompletne projekty można znaleźć w przykładach konektorów Azure Functions dla .NET.

Instalowanie rozszerzenia

Zainstaluj pakiety używane przez wyzwalacz Connector:

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

Pakiety te oferują następujące funkcje:

• @azure/functions zapewnia podstawową rejestracjęconnectorTrigger, która otrzymuje wejście wyzwalacze jako typ generyczny, domyślnie przyjmujący .unknown
• @azure/functions-extensions-connectors owija wejście w znormalizowany kontekst wyzwalania złącza i zapewnia typowe konteksty dla obsługiwanych operacji złącza.
• @azure/connectors, podglądowy zestaw Azure Connectors SDK dla Node.js, dostarcza modele payload używane przez te konteksty i klientów do wywoływania operacji łącznikowych.

Skonfiguruj swoją aplikację tak, aby używała wersji 4.42.0 lub nowszej pakietu rozszerzenia podglądowego w pliku host.json :

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

Aktualne wersje pakietów i kompletne projekty można znaleźć w przykładach konektorów Azure Functions dla TypeScript.

Instalowanie rozszerzenia

Użyj modelu programowania Python v2 i zainstaluj pakiety wymagane przez wyzwalacz Connector:

azure-functions>=2.2.0
azurefunctions-extensions-connectors

Podstawowa biblioteka Python azure-functions może wiązać payload wyzwalający z str, dict, lub bytes. Pakiet azurefunctions-extensions-connectors integruje SDK Azure Connectors dla Python oraz rejestruje dodatkowe konwertery dla specyficznych dla operacji adnotacji SDK, które obsługuje.

Skonfiguruj swoją aplikację tak, aby używała wersji 4.42.0 lub nowszej pakietu rozszerzenia podglądowego w pliku host.json :

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

Aktualne wersje pakietów i kompletne projekty można znaleźć w przykładach konektorów Azure Functions dla Python.

Typy powiązań

Wyzwalacz Connector obsługuje następujące typy parametrów dla izolowanych funkcji roboczych .NET:

Przykłady kodu i specyficzne dla operacji zachowanie ładunku można znaleźć w odniesieniu do wyzwalania Connector.

Aby określić, które operacje łączące mają silnie typowane modele payload .NET, zobacz mapowanie sygnatur Operacje do Azure Functions.

Typy powiązań

Rejestracja bazowa connectorTrigger przekazuje wejście wyzwalacze do ogólnego typu handlera, który domyślnie jest .unknown Pakiet @azure/functions-extensions-connectors przetwarza surowe dane wejściowe na a ConnectorTriggerContext<T> z normalizowanymi payloaditems i właściwościami, oryginalnymi rawPayload, oraz specyficznymi dla operacji typowanymi kontekstami, gdy są dostępne. Dla operacji bez typowej rejestracji należy użyć kontekstu ogólnego i zweryfikować unknown ładunek przed uzyskaniem dostępu do jego treści.

Aby określić, które operacje łączące mają silnie typowane modele payload TypeScript, zobacz mapowanie sygnatur Operacje do Azure Functions.

Typy powiązań

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

Aby określić, które operacje łączące mają zarejestrowany typowy konwerter Python oraz czy adnotacja reprezentuje jeden element lub kolekcję, zobacz mapowanie podpisów Operacje do Azure Functions. Użyj str, dict, lub bytes dla operacji, które nie mają obsługiwanej adnotacji SDK.

Konfiguruj zasoby łącznika

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

1. Przestrzeń nazw Connector.
2. Zarządzane połączenie złącza upoważnione do dostępu do usługi zewnętrznej.
3. Konfiguracja wyzwalająca, która wybiera zdarzenie łącznika i identyfikuje funkcję docelową.

Konfiguracja wyzwalacza obejmuje połączenie z zarządzanym połączeniem, nazwę operacji, parametry operacji, adres callback URL oraz uwierzytelnianie callback. Aby uzyskać wartości konfiguracyjne i instrukcje tworzenia wyzwalacza za pomocą Azure CLI lub portalu Connector Namespace, zobacz Konfiguruj wyzwalacz.

Uwierzytelnianie połączeń zwrotnych

Domyślnie rozszerzenie Connector tworzy system klawisza funkcji o nazwie connector_extension. Odzyskaj klucz, biegnąc:

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

Skonfiguruj link URL odwołania bez klucza:

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

Przechowywać klucz osobno w :notificationDetails.authentication

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

W czasie callbacku przestrzeń nazw Connector dodaje klucz jako code parametr stringu zapytań. Oddzielenie klucza od zapisanego URL-a callback pozwala portalowi ukryć go jako tajemnicę.

W przypadku wdrożeń wymagających uwierzytelniania callback opartego na tożsamości, używaj wbudowanego uwierzytelniania App Service z tożsamością zarządzaną zamiast wspólnego klucza systemowego. Pełny wzór można znaleźć w artykule Uwierzytelnij swoje funkcje do przestrzeni nazw złącza.

ustawienia pliku host.json

Domyślne uwierzytelnianie kluczem systemowym nie wymaga ustawień specyficznych dla konektora w pliku host.json .

Gdy wbudowana autyzacja App Service weryfikuje odwołania z przestrzeni nazw konektora, możesz wyłączyć redundantne sprawdzanie klucza systemowego:

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

Używaj Anonymous tylko wtedy, gdy inna warstwa uwierzytelniania, taka jak wbudowane uwierzytelnianie w App Service, weryfikuje żądania zanim dotrą do hosta Functions.

Aby uzyskać pełną implementację tej niezależnej od języka konfiguracji aplikacji, zobacz wbudowany przykład uwierzytelniania.

Następne kroki

• Managed connector trigger for Azure Function
• Używaj zarządzanych konektorów w Azure Functions
• Azure Functions Connectors Samples
• Co to jest przestrzeń nazw łącznika Azure?
• Odniesienie do złączy