Azure Queue Storage-Trigger für Azure Functions

Der Queue Storage-Trigger führt eine Funktion aus, wenn Azure Queue Storage Nachrichten hinzugefügt werden.

Die Entscheidungen zur Skalierung von Azure Queue Storage für die Tarife „Verbrauch“ und „Premium“ werden über die zielbasierte Skalierung getroffen. Weitere Informationen finden Sie unter Zielbasierte Skalierung.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

v2

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

v1

Für das Python v1-Programmiermodell müssen Sie Bindungen in einer separaten function.json-Datei im Funktionsordner definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

Verwenden Sie den Warteschlangentrigger, um eine Funktion zu starten, wenn bei einer Warteschlange ein neues Element eingeht. Die Warteschlangennachricht wird als Eingabe für die Funktion bereitgestellt.

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

• Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden. Erweiterungen für isolierte Workerprozessfunktionen verwenden Microsoft.Azure.Functions.Worker.Extensions.*-Namespaces.
• In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird. In einer Variante dieses Modells kann Functions mithilfe von C#-Skripts ausgeführt werden. Dies wird hauptsächlich für die Bearbeitung im C#-Portal unterstützt. Erweiterungen für In-Process-Funktionen verwenden Microsoft.Azure.WebJobs.Extensions.*-Namespaces.

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Isoliertes Workermodell

Die C#-Funktion des folgenden Beispiels fragt die Warteschlange input-queue ab und schreibt bei jeder Verarbeitung eines Warteschlangenelements mehrere Nachrichten in eine Ausgabewarteschlange.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

In-Process-Modell

Die C#-Funktion des folgenden Beispiels fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein neues Warteschlangenelement verarbeitet wird.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

Das folgende Java-Beispiel zeigt eine Funktion für einen Storage-Warteschlangentrigger, mit der die ausgelöste Nachricht, die in Warteschlange myqueuename abgelegt ist, protokolliert wird.

@FunctionName("queueprocessor")
public void run(
    @QueueTrigger(name = "msg",
                queueName = "myqueuename",
                connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

Modell v4

Das folgende Beispiel zeigt eine TypeScript-Funktion für den Warteschlangentrigger. Die Funktion fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein Warteschlangenelement verarbeitet wird.

import { app, InvocationContext } from '@azure/functions';

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

Im Abschnitt Verwendung wird queueItem erläutert. Alle anderen gezeigten Variablen werden im Abschnitt Nachrichtenmetadaten erläutert.

Modell v3

TypeScript-Beispiele sind für Modell v3 nicht dokumentiert.

Modell v4

Das folgende Beispiel zeigt eine JavaScript-Funktion für den Warteschlangentrigger. Die Funktion fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein Warteschlangenelement verarbeitet wird.

const { app } = require('@azure/functions');

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

Im Abschnitt Verwendung wird queueItem erläutert. Alle anderen gezeigten Variablen werden im Abschnitt Nachrichtenmetadaten erläutert.

Modell v3

Das folgende Beispiel enthält eine Warteschlangentrigger-Bindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet. Die Funktion fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein Warteschlangenelement verarbeitet wird.

Die Datei function.json sieht wie folgt aus:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Hinweis

Der Namensparameter wird als context.bindings.<name> im JavaScript-Code wiedergegeben, der die Nutzlast des Warteschlangenelements enthält. Diese Nutzlast wird der Funktion außerdem als zweiter Parameter übergeben.

Der JavaScript-Code sieht wie folgt aus:

module.exports = async function (context, message) {
    context.log('Node.js queue trigger function processed work item', message);
    // OR access using context.bindings.<name>
    // context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
};

Im Abschnitt Verwendung finden Sie weitere Informationen zu myQueueItem (benannt durch die Eigenschaft name in „function.json“). Alle anderen gezeigten Variablen werden im Abschnitt Nachrichtenmetadaten erläutert.

Das folgende Beispiel zeigt, wie Sie eine an eine Funktion übergebene Warteschlangennachricht mittels Trigger lesen.

Der Trigger einer Speicherwarteschlange wird in der Datei function.json definiert, wobei type auf queueTrigger festgelegt ist.

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Der Code in der Datei Run.ps1 deklariert einen Parameter als $QueueItem, was es Ihnen ermöglicht, die Warteschlangennachricht in ihrer Funktion zu lesen.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

Das folgende Beispiel zeigt, wie Sie eine an eine Funktion übergebene Warteschlangennachricht mittels Trigger lesen. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

v1

Der Trigger einer Speicherwarteschlange ist in function.json definiert, wobei type auf queueTrigger festgelegt ist.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Der Code _init_.py deklariert einen Parameter als func.QueueMessage, was es Ihnen ermöglicht, die Warteschlangennachricht in Ihrer Funktion zu lesen.

import logging
import json

import azure.functions as func

def main(msg: func.QueueMessage):
    logging.info('Python queue trigger function processed a queue item.')

    result = json.dumps({
        'id': msg.id,
        'body': msg.get_body().decode('utf-8'),
        'expiration_time': (msg.expiration_time.isoformat()
                            if msg.expiration_time else None),
        'insertion_time': (msg.insertion_time.isoformat()
                           if msg.insertion_time else None),
        'time_next_visible': (msg.time_next_visible.isoformat()
                              if msg.time_next_visible else None),
        'pop_receipt': msg.pop_receipt,
        'dequeue_count': msg.dequeue_count
    })

    logging.info(result)

Attribute

Sowohl von C#-Bibliotheken vom Typ In-Process als auch von C#-Bibliotheken vom Typ Isolierter Workerprozess wird das Attribut QueueTriggerAttribute verwendet, um die Funktion zu definieren. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Isoliertes Workermodell

In C#-Klassenbibliotheken akzeptiert der Konstruktor des Attributs den Namen der zu überwachenden Warteschlange, wie im folgenden Beispiel zu sehen:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

In diesem Beispiel wird auch das Festlegen der Verbindungszeichenfolgeneinstellung im Attribut selbst veranschaulicht.

In-Process-Modell

In C#-Klassenbibliotheken akzeptiert der Konstruktor des Attributs den Namen der zu überwachenden Warteschlange, wie im folgenden Beispiel zu sehen:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem, 
    ILogger log)
{
    ...
}

Sie können die Eigenschaft Connection festlegen, um die App-Einstellung anzugeben, die die zu verwendende Verbindungszeichenfolge des Speicherkontos enthält, wie im folgenden Beispiel gezeigt:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
    ILogger log)
{
    ....
}

Anmerkungen

Die QueueTrigger-Anmerkung gewährt Ihnen Zugriff auf die Warteschlange, die die Funktion auslöst. Im folgenden Beispiel wird die Warteschlangennachricht über den Parameter message für die Funktion verfügbar gemacht.

package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}

Eigenschaft	BESCHREIBUNG
name	Deklariert den Parameternamen in der Funktionssignatur. Wenn die Funktion ausgelöst wird, enthält der Wert dieses Parameters den Inhalt der Warteschlangennachricht.
queueName	Deklariert den Warteschlangennamen im Speicherkonto.
connection	Verweist auf die Speicherkonto-Verbindungszeichenfolge.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe von Decorators definiert wurden, definieren die folgenden Eigenschaften auf dem queue_trigger-Decorator den Warteschlangenspeichertrigger:

Eigenschaft	BESCHREIBUNG
arg_name	Deklariert den Parameternamen in der Funktionssignatur. Wenn die Funktion ausgelöst wird, enthält der Wert dieses Parameters den Inhalt der Warteschlangennachricht.
queue_name	Deklariert den Warteschlangennamen im Speicherkonto.
connection	Verweist auf die Speicherkonto-Verbindungszeichenfolge.

Informationen zu Python-Funktionen, die mithilfe von „function.json“ definiert wurden, finden Sie im Abschnitt „Konfiguration“.

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

Modell v4

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die app.storageQueue()-Methode übergeben wurde.

Eigenschaft	BESCHREIBUNG
queueName	Der Name der abzufragenden Warteschlange.
connection	Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Azure Queues hergestellt wird. Siehe Verbindungen.

Modell v3

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen.

Eigenschaft	Beschreibung des Dataflows
type	Muss auf queueTrigger festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
direction	Nur in der Datei function.json. Muss auf in festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name	Der Name der Variablen, die die Nutzlast des Warteschlangenelements im Funktionscode enthält.
queueName	Der Name der abzufragenden Warteschlange.
connection	Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Azure Queues hergestellt wird. Siehe Verbindungen.

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut QueueTrigger festlegen:

Eigenschaft von „function.json“	BESCHREIBUNG
type	Muss auf queueTrigger festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
direction	Nur in der Datei function.json. Muss auf in festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name	Der Name der Variablen, die die Nutzlast des Warteschlangenelements im Funktionscode enthält.
queueName	Der Name der abzufragenden Warteschlange.
connection	Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Azure Queues hergestellt wird. Siehe Verbindungen.

Vollständige Beispiele finden Sie im Abschnitt „Beispiele“.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Verwendung

Hinweis

Funktionen erwarten eine Base64-codierte Zeichenfolge. Alle Anpassungen am Codierungstyp (um Daten als Base64-codierte Zeichenfolge vorzubereiten) müssen im aufrufenden Dienst implementiert werden.

Die Verwendung des Warteschlangentriggers hängt von der Erweiterungspaketversion und der in Ihrer Funktions-App verwendeten C#-Modalität ab, die einer der folgenden Modi sein kann:

Isoliertes Workermodell

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

In-Process-Klassenbibliothek

Eine In-Process-Klassenbibliothek ist eine kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird.

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

Erweiterung 5.x oder höher

Zugriff auf die Nachrichtendaten mittels eines Methodenparameters wie string paramName. paramName ist der in QueueTriggerAttribute angegebene Wert. Eine Bindung kann mit folgenden Typen erstellt werden:

• Einfaches .NET CLR-Objekt (POCO)
• string
• byte[]
• QueueMessage

Bei der Bindung an ein Objekt wird von der Functions-Runtime versucht, die JSON-Nutzdaten in eine Instanz einer beliebigen Klasse zu deserialisieren, die in Ihrem Code definiert ist. Beispiele mit QueueMessage finden Sie im GitHub-Repository für die Erweiterung.

Während das Attribut eine Connection-Eigenschaft annimmt, können Sie auch Connection verwenden, um eine Speicherkontoverbindung anzugeben. Sie können so vorgehen, wenn Sie ein anderes Speicherkonto als andere Funktionen in der Bibliothek verwenden müssen. Der Konstruktor akzeptiert den Namen einer App-Einstellung mit einer Speicherverbindungszeichenfolge. Das Attribut kann auf Parameter-, Methoden- oder Klassenebene angewendet werden. Das folgende Beispiel zeigt die Anwendung auf Klassen- und Methodenebene:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

Das zu verwendende Speicherkonto wird anhand von Folgendem bestimmt (in der angegebenen Reihenfolge):

• Die Connection-Eigenschaft des Triggers oder Bindungsattributs.
• Das StorageAccount-Attribut, das auf den gleichen Parameter wie der Trigger oder das Bindungsattribut angewendet wird.
• Das Attribut StorageAccount, das auf die Funktion angewendet wird.
• Das Attribut StorageAccount, das auf die Klasse angewendet wird.
• Das Standardspeicherkonto für die Funktions-App, das in der AzureWebJobsStorage-Anwendungseinstellung definiert ist.

Erweiterung 2.x oder höher

Zugriff auf die Nachrichtendaten mittels eines Methodenparameters wie string paramName. paramName ist der in QueueTriggerAttribute angegebene Wert. Eine Bindung kann mit folgenden Typen erstellt werden:

• Plain Old CLR Object (POCO)
• string
• byte[]
• CloudQueueMessage

Bei der Bindung an ein Objekt wird von der Functions-Runtime versucht, die JSON-Nutzdaten in eine Instanz einer beliebigen Klasse zu deserialisieren, die in Ihrem Code definiert ist. Wenn Sie versuchen, eine Bindung mit CloudQueueMessage herzustellen, und eine Fehlermeldung erhalten, stellen Sie sicher, dass ein Verweis auf die richtige Storage SDK-Version vorhanden ist.

Während das Attribut eine Connection-Eigenschaft annimmt, können Sie auch Connection verwenden, um eine Speicherkontoverbindung anzugeben. Sie können so vorgehen, wenn Sie ein anderes Speicherkonto als andere Funktionen in der Bibliothek verwenden müssen. Der Konstruktor akzeptiert den Namen einer App-Einstellung mit einer Speicherverbindungszeichenfolge. Das Attribut kann auf Parameter-, Methoden- oder Klassenebene angewendet werden. Das folgende Beispiel zeigt die Anwendung auf Klassen- und Methodenebene:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

Das zu verwendende Speicherkonto wird anhand von Folgendem bestimmt (in der angegebenen Reihenfolge):

• Die Connection-Eigenschaft des Triggers oder Bindungsattributs.
• Das StorageAccount-Attribut, das auf den gleichen Parameter wie der Trigger oder das Bindungsattribut angewendet wird.
• Das Attribut StorageAccount, das auf die Funktion angewendet wird.
• Das Attribut StorageAccount, das auf die Klasse angewendet wird.
• Das Standardspeicherkonto für die Funktions-App, das in der AzureWebJobsStorage-Anwendungseinstellung definiert ist.

Erweiterung 5.x oder höher

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.

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

Erweiterung 2.x oder höher

Frühere Versionen dieser Erweiterung im isolierten Workerprozess haben nur die Bindung an Zeichenfolgen unterstützt. Weitere Optionen stehen für Erweiterung 5.x+ zur Verfügung.

Die QueueTrigger-Anmerkung gewährt Ihnen Zugriff auf die Warteschlangennachricht, die die Funktion ausgelöst hat.

Modell v4

Greifen Sie auf das Warteschlangenelement als erstes Argument für Ihre Funktion zu. Falls es sich um eine JSON-Nutzlast handelt, wird der Wert in ein Objekt deserialisiert.

Modell v3

Greifen Sie über context.bindings.<NAME> auf das Warteschlangenelement zu, wobei <NAME> mit dem in function.json definierten Wert übereinstimmt. Falls es sich um eine JSON-Nutzlast handelt, wird der Wert in ein Objekt deserialisiert.

Greifen Sie auf die Warteschlangennachricht über einen Zeichenfolgenparameter zu, der mit dem Namen übereinstimmt, der durch den name-Parameter der Bindung in der Datei name festgelegt ist.

Greifen Sie über den Parameter, der als QueueMessage typisiert ist, auf die Warteschlangennachricht zu.

Metadaten

Der Warteschlangentrigger stellt mehrere Metadateneigenschaften bereit. Diese Eigenschaften können als Teil von Bindungsausdrücken in anderen Bindungen oder als Parameter in Ihrem Code für Sprachmitarbeiter verwendet werden, die diesen Zugriff auf Nachrichtenmetadaten ermöglichen.

Die Nachrichtenmetadateneigenschaften sind Member der CloudQueueMessage-Klasse .

Auf die Eigenschaften der Nachrichtenmetadaten kann zugegriffen context.triggerMetadatawerden.

Auf die Eigenschaften der Nachrichtenmetadaten kann über den übergebenen Parameter zugegriffen $TriggerMetadata werden.

Eigenschaft	Typ	BESCHREIBUNG
QueueTrigger	string	Die Warteschlangennutzlast (bei einer gültigen Zeichenfolge). Handelt es sich bei der Warteschlangennutzlast um eine Zeichenfolge, hat QueueTrigger den gleichen Wert wie die Variable, die durch die Eigenschaft name in QueueTrigger benannt wird.
DequeueCount	long	Gibt an, wie oft diese Nachricht aus der Warteschlange entfernt wurde.
ExpirationTime	DateTimeOffset	Die Zeit, zu der die Nachricht abläuft.
Id	string	ID der Warteschlangennachricht
InsertionTime	DateTimeOffset	Die Zeit, zu der die Nachricht der Warteschlange hinzugefügt wurde.
NextVisibleTime	DateTimeOffset	Die Zeit, zu der die Nachricht als Nächstes sichtbar wird.
PopReceipt	string	Die POP-Bestätigung der Nachricht.

Auf die folgenden Nachrichtenmetadateneigenschaften kann über den übergebenen Bindungsparameter zugegriffen werden (msg in früheren Beispielen).

Eigenschaft	Beschreibung
body	Warteschlangennutzlast als Zeichenfolge.
dequeue_count	Gibt an, wie oft diese Nachricht aus der Warteschlange entfernt wurde.
expiration_time	Die Zeit, zu der die Nachricht abläuft.
id	ID der Warteschlangennachricht
insertion_time	Die Zeit, zu der die Nachricht der Warteschlange hinzugefügt wurde.
time_next_visible	Die Zeit, zu der die Nachricht als Nächstes sichtbar wird.
pop_receipt	Die POP-Bestätigung der Nachricht.

Verbindungen

Die Eigenschaft connection ist ein Verweis auf die Umgebungskonfiguration, die angibt, wie die App eine Verbindung mit Azure Warteschlangen herstellen soll. Folgendes kann angegeben werden:

• Der Name einer Anwendungseinstellung, die eine Verbindungszeichenfolge enthält
• Der Name eines gemeinsam genutzten Präfixes für mehrere Anwendungseinstellungen, die zusammen eine identitätsbasierte Verbindung definieren.

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Um eine Verbindungszeichenfolge abzurufen, führen Sie die Schritte unter Verwalten von Speicherkonto-Zugriffsschlüsseln aus.

Diese Verbindungszeichenfolge sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der mit dem von der connection-Eigenschaft der Bindungskonfiguration angegebenen Wert übereinstimmt.

Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie hier nur den Rest des Namens angeben. Wenn Sie beispielsweise connection auf „MyStorage“ setzen, sucht die Functions-Runtime nach einer App-Einstellung mit dem Namen „AzureWebJobsMyStorage“. Wenn Sie connection leer lassen, verwendet die Functions-Runtime die Standard-Speicherverbindungszeichenfolge in der App-Einstellung mit dem Namen AzureWebJobsStorage.

Identitätsbasierte Verbindungen

Wenn Sie Version 5.x oder höher der Erweiterung verwenden (Bündel 3.x oder höher für non-.NET Sprachstapel), anstatt einen Verbindungszeichenfolge mit einem geheimen Schlüssel zu verwenden, können Sie die App über eine Microsoft Entra-Identität verfügen. Um eine Identität zu verwenden, definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Eigenschaft connection in der Trigger- und Bindungskonfiguration zugeordnet ist.

Wenn Sie connection auf „AzureWebJobsStorage“ festlegen, finden Sie weitere Informationen unter Herstellen einer Verbindung zum Hostspeicher mit einer Identität. Für alle anderen Verbindungen erfordert die Erweiterung die folgenden Eigenschaften:

Eigenschaft	Vorlage für Umgebungsvariable	BESCHREIBUNG	Beispielwert
Warteschlangendienst-URI	<CONNECTION_NAME_PREFIX>__queueServiceUri1	Dies ist der URI der Datenebene des Warteschlangendiensts, mit dem Sie mithilfe des HTTPS-Schemas eine Verbindung herstellen.	https://<storage_account_name>.queue.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__serviceUri kann als Alias verwendet werden. Wenn beide Formate bereitgestellt werden, wird das Format queueServiceUri verwendet. Das Format serviceUri kann nicht verwendet werden, wenn die gesamte Verbindungskonfiguration über Blobs, Warteschlangen und/oder Tabellen hinweg verwendet werden soll.

Andere Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

Wichtig

Vom Zieldienst werden möglicherweise einige nicht für alle Kontexte erforderliche Berechtigungen verfügbar gemacht. Befolgen Sie nach Möglichkeit das Prinzip der geringsten Berechtigung, und gewähren Sie der Identität nur die erforderlichen Berechtigungen. Wenn die App beispielsweise nur Daten aus einer Datenquelle lesen muss, verwenden Sie eine Rolle, die nur über Leseberechtigungen verfügt. Es wäre nicht angemessen, eine Rolle zu zuweisen, die auch das Schreiben in diesen Dienst zulässt, da dies eine übermäßige Berechtigung für einen Lesevorgang wäre. Ebenso sollten Sie sicherstellen, dass die Rollenzuweisung auf die Ressourcen begrenzt ist, die gelesen werden müssen.

Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihre Warteschlange ermöglicht. Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für den normalen Betrieb mit der Queue Storage-Erweiterung empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp	Integrierte Beispielrollen
Trigger	Storage-Warteschlangendatenleser, Verarbeiter von Speicherwarteschlangen-Datennachrichten
Ausgabebindung	Mitwirkender an Storage-Warteschlangendaten, Absender der Speicherwarteschlangen-Datennachricht

Nicht verarbeitbare Nachrichten

Falls eine Funktion des Warteschlangentriggers nicht erfolgreich ausgeführt werden kann, versucht Azure Functions für eine bestimmte Warteschlangennachricht bis zu fünf Mal (einschließlich des ersten Versuchs), die Funktion auszuführen. Sind alle fünf Versuche nicht erfolgreich, fügt die Functions-Laufzeit einer Warteschlange namens <Name der Originalwarteschlange>-poison eine Nachricht hinzu. Sie können eine Funktion schreiben, um Nachrichten aus der Warteschlange für nicht verarbeitete Nachrichten zu verarbeiten, indem Sie diese protokollieren oder eine Benachrichtigung senden, dass ein manueller Eingriff erforderlich ist.

Überprüfen Sie zur manuellen Behandlung nicht verarbeitbarer Nachrichten den Wert dequeueCount der Warteschlangennachricht.

Peek-Lock

Das Vorschausperrmuster erfolgt automatisch für Warteschlangentrigger, wobei die Sichtbarkeitsmechanik des Speicherdiensts verwendet wird. Wenn Nachrichten von der ausgelösten Funktion entqueuiert werden, werden sie als unsichtbar markiert. Die Ausführung einer ausgelösten Warteschlange kann eines der folgenden Ergebnisse für die Nachricht in der Warteschlange haben:

• Die Funktionsausführung wird erfolgreich abgeschlossen, und die Nachricht wird aus der Warteschlange gelöscht.
• Die Funktionsausführung schlägt fehl, und der Funktionshost aktualisiert die Sichtbarkeit der Nachricht basierend auf der Einstellung in der visibilityTimeout host.json Datei. Das Standardmäßige Sichtbarkeitstimeout ist null, was bedeutet, dass die Nachricht sofort wieder in der Warteschlange für die Erneute Verarbeitung angezeigt wird. Verwenden Sie die visibilityTimeout Einstellung, um die Neuverarbeitung von Nachrichten zu verzögern, die nicht verarbeitet werden können. Diese Timeouteinstellung gilt für alle in der Warteschlange ausgelösten Funktionen in der Funktions-App.
• Der Funktionshost stürzt während der Funktionsausführung ab. Wenn dieses ungewöhnliche Ereignis auftritt, kann der Host die visibilityTimeout verarbeitete Nachricht nicht anwenden. Stattdessen bleibt die Nachricht mit dem vom Speicherdienst festgelegten Standardtimeout von 10 Minuten übrig. Nach 10 Minuten wird die Nachricht wieder in der Warteschlange für die Erneute Verarbeitung angezeigt. Dieses vom Dienst definierte Standardtimeout kann nicht geändert werden.

Abrufalgorithmus

Der Warteschlangentrigger implementiert einen zufälligen exponentiellen Backoffalgorithmus, um die Auswirkungen des Abfragens von Warteschlangen im Leerlauf auf Speichertransaktionskosten zu reduzieren.

Der Algorithmus verwendet die folgende Logik:

• Wenn eine Nachricht gefunden wird, wartet die Laufzeit 100 Millisekunden und sucht dann nach einer anderen Nachricht.
• Wenn keine Nachricht gefunden wird, wartet sie ungefähr 200 Millisekunden, bevor der Versuch wiederholt wird.
• Nach aufeinander folgenden fehlgeschlagenen Versuchen, eine Warteschlangennachricht abzurufen, erhöht sich die Wartezeit immer mehr, bis die maximale Wartezeit, standardmäßig eine Minute, erreicht ist.
• Die maximale Wartezeit kann über die maxPollingInterval-Eigenschaft in der Datei maxPollingInterval konfiguriert werden.

Während der lokalen Entwicklung wird standardmäßig das maximale Abrufintervall auf zwei Sekunden festgelegt.

Hinweis

Bei der Abrechnung von Funktions-Apps im Verbrauchsplan wird Ihnen die Zeit, die die Runtime mit dem Abruf verbringt, nicht in Rechnung gestellt.

Parallelität

Wenn mehrere Warteschlangennachrichten warten, ruft der Warteschlangentrigger einen Batch mit Nachrichten ab und ruft parallel Funktionsinstanzen zur Verarbeitung auf. Standardmäßig ist die Batchgröße 16. Wenn die zu verarbeitende Anzahl 8 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 auf einem virtuellen Computer verarbeiteten parallelen Nachrichten 24. Dieser Grenzwert gilt separat für jede durch Warteschlangen ausgelöste Funktion auf jedem virtuellen Computer. Wenn Ihre Funktions-App auf mehrere virtuelle Computer skaliert wird, wartet jede VM auf Trigger und versucht, Funktionen auszuführen. Beispiel: Wenn eine Funktions-App auf drei virtuelle Computer horizontal hochskaliert wird, beträgt die standardmäßige maximale Anzahl von parallelen Instanzen einer durch Warteschlangen ausgelösten Funktion 72.

Die Batchgröße und der Schwellenwert für das Abrufen eines neuen Batches können in der Datei host.json konfiguriert werden. Sie können die Batchgröße auf 1 festlegen, wenn Sie die parallele Ausführung von durch Warteschlangen ausgelösten Funktionen in einer Funktions-App minimieren möchten. Diese Einstellung verhindert Parallelität nur so lange, wie Ihre Funktions-App auf einem einzelnen virtuellen Computer ausgeführt wird.

Mit dem Warteschlangentrigger wird automatisch verhindert, dass eine Funktion Warteschlangennachrichten mehrmals gleichzeitig verarbeitet.

Eigenschaften von „host.json“

Die Datei host.json enthält Einstellungen, mit denen das Verhalten des Warteschlangentriggers gesteuert werden kann. Informationen zu verfügbaren Einstellungen finden Sie im Abschnitt Einstellungen für „host.json“.

Nächste Schritte

• Schreiben von Queue Storage-Nachrichten (Ausgabebindung)