Azure Queue Storage-Trigger und -Bindungen für Azure Functions – Übersicht

  • Artikel

Azure Functions kann ausgeführt werden, wenn neue Azure Queue Storage-Nachrichten erstellt werden, und Warteschlangennachrichten in eine Funktion schreiben.

Aktion type
Ausführen einer Funktion, wenn sich Queue Storage-Daten ändern Trigger
Schreiben von Queue Storage-Nachrichten Ausgabebindung

Installieren der Erweiterung

Das NuGet-Erweiterungspaket, das Sie installieren, hängt vom C#-Modus ab, den Sie in Ihrer Funktions-App verwenden:

Funktionen werden in einem isolierten C#-Workerprozess ausgeführt. Weitere Informationen finden Sie im Leitfaden zum Ausführen von Azure Functions (C#) in einem isolierten Workerprozess.

Die Funktionalität der Erweiterung ist abhängig von der Erweiterungsversion unterschiedlich:

Diese Version bietet die Möglichkeit, eine Verbindung mithilfe einer Identität anstelle eines Geheimnisses herzustellen. Ein Tutorial zum Konfigurieren Ihrer Funktions-Apps mit verwalteten Identitäten finden Sie im Tutorial zum Erstellen einer Funktions-App mit identitätsbasierten Verbindungen.

Mit dieser Version können Sie Bindungen an Typen aus Azure.Storage.Queues erstellen.

Diese Version unterstützt die Konfiguration von Triggern und Bindungen über die .NET Aspire-Integration.

Fügen Sie ihrem Projekt die Erweiterung hinzu, indem Sie das NuGet-Paket, Version 5.x, installieren.

Verwenden der .NET-CLI:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Hinweis

Azure Blobs, Azure Queues und Azure Tables verwenden jetzt separate Erweiterungen und werden einzeln referenziert. Wenn Sie beispielsweise die Trigger und Bindungen für alle drei Dienste in Ihrer .NET-App im isolierten Prozess verwenden möchten, sollten Sie Ihrem Projekt die folgenden Pakete hinzufügen:

Zuvor wurden die Erweiterungen zusammen als Microsoft.Azure.Functions.Worker.Extensions.Storage Version 4.x ausgeliefert. Dieses Paket verfügt auch über eine 5.x-Version, die nur auf die geteilten Pakete für Blobs und Warteschlangen verweist. Wenn Sie Ihre Paketverweise älterer Versionen aktualisieren, müssen Sie möglicherweise zusätzlich auf das neue NuGet-Paket Microsoft.Azure.Functions.Worker.Extensions.Tables verweisen. Stellen Sie beim Verweisen auf diese neueren geteilten Pakete außerdem sicher, dass Sie nicht auf eine ältere Version des kombinierten Speicherpakets verweisen, da dies zu Konflikten durch jeweils zwei Definitionen derselben Bindungen führt.

Installieren des Pakets

Die Blob-Speicherbindung ist Teil eines Erweiterungspakets, das in Ihrer Projektdatei „host.json“ angegeben wird. Möglicherweise müssen Sie dieses Paket ändern, um die Version der Bindung zu ändern, oder wenn Pakete noch nicht installiert sind. Weitere Informationen finden Sie unter Erweiterungspakete.

Diese Version bietet die Möglichkeit, eine Verbindung mithilfe einer Identität anstelle eines Geheimnisses herzustellen. Ein Tutorial zum Konfigurieren Ihrer Funktions-Apps mit verwalteten Identitäten finden Sie im Tutorial zum Erstellen einer Funktions-App mit identitätsbasierten Verbindungen.

Sie können diese Version der Erweiterung aus dem Vorschauerweiterungspaket v3 hinzufügen, indem Sie den folgenden Code in Ihrer Datei host.json hinzufügen oder ersetzen:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Weitere Informationen finden Sie unter Aktualisierung Ihrer Erweiterungen.

Bindungstypen

Die für .NET unterstützten Bindungstypen hängen sowohl von der Erweiterungsversion als auch von dem C#-Ausführungsmodus ab, der einer der folgenden sein kann:

Eine Klassenbibliothek in einem isolierten Workerprozess ist eine kompilierte C#-Funktion, die in einem von der Runtime isolierten Prozess ausgeführt wird.

Wählen Sie eine Version aus, um für den Modus und die Version Details zum Bindungstyp anzuzeigen.

Der isolierte Workerprozess unterstützt Parametertypen gemäß den folgenden Tabellen. Die Unterstützung für die Bindung an Typen aus Azure.Storage.Queues befindet sich in der Vorschauphase.

Warteschlangentrigger

Der Warteschlangentrigger kann an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string Den Nachrichteninhalt als Zeichenfolge. Verwenden Sie diesen Parameter, wenn es sich bei der Nachricht um einfachen Text handelt.
byte[] Die Bytes der Nachricht.
Serialisierbare JSON-Typen Wenn eine Warteschlangennachricht JSON-Daten enthält, versucht Functions, die JSON-Daten in einen POCO-Objekttyp (Plain-Old CLR Object) zu deserialisieren.
QueueMessage1 Die Meldung.
BinaryData1 Die Bytes der Nachricht.

1 Um diese Typen verwenden zu können, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.2.0 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

Warteschlangenausgabebindung

Wenn die Funktion eine einzelne Nachricht schreiben soll, kann die Warteschlangenausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string Den Nachrichteninhalt als Zeichenfolge. Verwenden Sie diesen Parameter, wenn es sich bei der Nachricht um einfachen Text handelt.
byte[] Die Bytes der Nachricht.
Serialisierbare JSON-Typen Ein Objekt, das den Inhalt einer JSON-Nachricht darstellt. Functions versucht, einen POCO-Typ (Plain-Old CLR Object) in JSON-Daten zu serialisieren.

Wenn die Funktion mehrere Nachrichten schreiben soll, kann die Warteschlangenausgabebindung an die folgenden Typen gebunden werden:

type BESCHREIBUNG
T[], wobei T einer der einzelnen Nachrichtentypen ist. Ein Array, das Inhalt für mehrere Nachrichten enthält. Jeder Eintrag stellt eine Nachricht dar.

Erstellen und verwenden Sie für andere Ausgabeszenarien einen QueueClient mit anderen Typen von Azure.Storage.Queues direkt. Ein Beispiel für die Verwendung der Abhängigkeitsinjektion zum Erstellen eines Clienttyps aus dem Azure SDK finden Sie unter Registrieren von Azure-Clients .

Einstellungen für „host.json“

In diesem Abschnitt werden die für diese Bindung verfügbaren Konfigurationseinstellungen in Version 2.x und höher beschrieben. Einstellungen in der Datei „host.json“ gelten für alle Funktionen in einer Funktions-App-Instanz. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x und höhere Versionen für diese Bindung. Weitere Informationen zu den Konfigurationseinstellungen für Funktions-Apps in Version 2.x und höher finden Sie unter host.json-Referenz für Azure Functions.

Hinweis

Eine Referenz für „host.json“ in Functions 1.x finden Sie unter host.json-Referenz für Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Eigenschaft Standard BESCHREIBUNG
maxPollingInterval 00:01:00 Das maximale Intervall zwischen Warteschlangenabfragen. Der Minimalintervall ist 00:00:00,100 (100 ms). Intervalle werden bis maxPollingInterval erhöht. Der Standardwert von maxPollingInterval lautet 00:01:00 (1 min). maxPollingInterval darf nicht unter 00:00:00,100 (100 ms) liegen. In Functions 2.x und höher ist der Datentyp eine TimeSpan-Struktur. In Functions 1.x wird diese in Millisekunden angegeben.
visibilityTimeout 00:00:00 Das Zeitintervall zwischen Wiederholungsversuchen, wenn bei der Verarbeitung einer Nachricht ein Fehler auftritt.
batchSize 16 Die Anzahl der Warteschlangennachrichten, die die Functions-Runtime gleichzeitig abruft und parallel verarbeitet. Wenn die zu verarbeitende Anzahl newBatchThreshold erreicht, ruft die Runtime einen weiteren Batch ab und beginnt mit der Verarbeitung dieser Nachrichten. Aus diesem Grund beträgt die maximale Anzahl der pro Funktion verarbeiteten Nachrichten batchSize plus newBatchThreshold. Dieser Grenzwert gilt separat für jede Funktion, die durch die Warteschlange ausgelöst wird.

Wenn Sie eine parallele Ausführung für in einer Warteschlange empfangene Nachrichten vermeiden möchten, können Sie batchSize auf „1“ festlegen. Durch diese Einstellung wird jedoch Parallelität verhindert, solange Ihre Funktions-App nur auf einem einzelnen virtuellen Computer (virtual machine, VM) ausgeführt wird. Wenn die Funktions-App horizontal auf mehrere virtuelle Computer hochskaliert wird, kann jeder virtuelle Computer eine Instanz jeder durch die Warteschlange ausgelösten Funktion ausführen.

Die maximale batchSize beträgt 32.
maxDequeueCount 5 Die Anzahl der Versuche zum Verarbeiten einer Nachricht, bevor diese in die Warteschlange für nicht verarbeitete Nachrichten verschoben wird.
newBatchThreshold N*batchSize/2 Wenn die Anzahl der gleichzeitig verarbeiteten Nachrichten auf diesen Wert sinkt, ruft die Runtime einen weiteren Batch ab.

N stellt die Anzahl der beim Ausführen in App Service oder Premium-Plänen verfügbaren vCPUs dar. Der zugehörige Wert für den Verbrauchsplan ist 1.
messageEncoding base64 Diese Einstellung ist erst ab Version 5.0.0 des Erweiterungspakets verfügbar. Sie stellt das Codierungsformat für Nachrichten dar. Gültige Werte sind base64 und none.

Nächste Schritte