Azure Queue Storage-Bindungen für Azure FunctionsAzure Queue storage bindings for Azure Functions

In diesem Artikel erfahren Sie, wie Sie Azure Queue Storage-Bindungen in Azure Functions verwenden.This article explains how to work with Azure Queue storage bindings in Azure Functions. Azure Functions unterstützt Trigger- und Ausgabebindungen für Warteschlangen.Azure Functions supports trigger and output bindings for queues.

Dies sind Referenzinformationen für Azure Functions-Entwickler.This is reference information for Azure Functions developers. Falls Sie mit Azure Functions noch nicht vertraut sind, beginnen Sie mit den folgenden Ressourcen:If you're new to Azure Functions, start with the following resources:

Pakete: Functions 1.xPackages - Functions 1.x

Die Warteschlangenspeicher-Bindungen werden im NuGet-Paket Microsoft.Azure.WebJobs, Version 2.x bereitgestellt.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs NuGet package, version 2.x. Den Quellcode für das Paket finden Sie im GitHub-Repository azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

Unterstützung für diese Bindung wird automatisch in allen Entwicklungsumgebungen bereitgestellt.Support for this binding is automatically provided in all development environments. Sie müssen das Paket nicht manuell installieren oder die Erweiterung registrieren.You don't have to manually install the package or register the extension.

Azure Storage SDK-Version in Functions 1.xAzure Storage SDK version in Functions 1.x

In Functions 1.x verwenden die Storage-Trigger und -Bindungen Version 7.2.1 des Azure Storage SDK (NuGet-Paket WindowsAzure.Storage).In Functions 1.x, the Storage triggers and bindings use version 7.2.1 of the Azure Storage SDK (WindowsAzure.Storage NuGet package). Wenn Sie auf eine andere Version des Storage SDK verweisen und in Ihrer Funktionssignatur an einen Storage SDK-Typ binden, meldet die Functions-Runtime möglicherweise, dass Bindungen an diesen Typ nicht möglich sind.If you reference a different version of the Storage SDK, and you bind to a Storage SDK type in your function signature, the Functions runtime may report that it can't bind to that type. Die Lösung besteht darin, sicherzustellen, dass Ihr Projekt auf WindowsAzure.Storage 7.2.1 verweist.The solution is to make sure your project references WindowsAzure.Storage 7.2.1.

Pakete: Functions 2.xPackages - Functions 2.x

Die Warteschlangenspeicher-Bindungen werden im NuGet-Paket Microsoft.Azure.WebJobs.Extensions.Storage, Version 3.x bereitgestellt.The Queue storage bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package, version 3.x. Den Quellcode für das Paket finden Sie im GitHub-Repository azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

Der folgenden Tabelle können Sie entnehmen, wie Sie Unterstützung für diese Bindung in den einzelnen Entwicklungsumgebungen hinzufügen.The following table tells how to add support for this binding in each development environment.

EntwicklungsumgebungDevelopment environment Hinzufügen von Unterstützung inTo add support in
Functions 2.xFunctions 2.x
Lokale Entwicklung – C#-KlassenbibliothekLocal development - C# class library Paket installierenInstall the package
Lokale Entwicklung – C#-Skript, JavaScript, F#, Java und PythonLocal development - C# script, JavaScript, F#, Java and Python Erweiterung registrierenRegister the extension
Entwicklung im PortalPortal development Installieren beim Hinzufügen einer AusgabebindungInstall when adding output binding

Informationen zum Aktualisieren der vorhandenen Bindungserweiterungen im Portal ohne erneute Veröffentlichung Ihres Funktions-App-Projekts finden Sie unter Manually install or update Azure Functions binding extensions from the portal (Manuelles Installieren oder Aktualisieren von Azure Functions-Bindungserweiterungen über das Portal).To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

CodierenEncoding

Funktionen erwarten eine Base64-codierte Zeichenfolge.Functions expect a base64 encoded string. Alle Anpassungen am Codierungstyp (um Daten als Base64-codierte Zeichenfolge vorzubereiten) müssen im aufrufenden Dienst implementiert werden.Any adjustments to the encoding type (in order to prepare data as a base64 encoded string) need to be implemented in the calling service.

TriggerTrigger

Verwenden Sie den Warteschlangentrigger, um eine Funktion zu starten, wenn bei einer Warteschlange ein neues Element eingeht.Use the queue trigger to start a function when a new item is received on a queue. Die Warteschlangennachricht wird als Eingabe für die Funktion bereitgestellt.The queue message is provided as input to the function.

Trigger: BeispielTrigger - example

Sehen Sie sich das sprachspezifische Beispiel an:See the language-specific example:

Trigger: C#-BeispielTrigger - C# example

Die C#-Funktion des folgenden Beispiels fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein neues Warteschlangenelement verarbeitet wird.The following example shows a C# function that polls the myqueue-items queue and writes a log each time a queue item is processed.

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

Trigger: C#-SkriptbeispielTrigger - C# script example

Das folgende Beispiel enthält eine Warteschlangentrigger-Bindung in einer Datei vom Typ function.json sowie Code vom Typ C#-Skript (.csx), in dem die Bindung verwendet wird.The following example shows a queue trigger binding in a function.json file and C# script (.csx) code that uses the binding. Die Funktion fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein Warteschlangenelement verarbeitet wird.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Die Datei function.json sieht wie folgt aus:Here's the function.json file:

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

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.The configuration section explains these properties.

Der C#-Skriptcode sieht wie folgt aus:Here's the C# script code:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.Extensions.Logging;
using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

Im Abschnitt Verwendung finden Sie weitere Informationen zu myQueueItem (benannt durch die Eigenschaft name in „function.json“).The usage section explains myQueueItem, which is named by the name property in function.json. Alle anderen gezeigten Variablen werden im Abschnitt Nachrichtenmetadaten erläutert.The message metadata section explains all of the other variables shown.

Trigger: JavaScript-BeispielTrigger - JavaScript example

Das folgende Beispiel enthält eine Warteschlangentrigger-Bindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet.The following example shows a queue trigger binding in a function.json file and a JavaScript function that uses the binding. Die Funktion fragt die Warteschlange myqueue-items ab und schreibt ein Protokoll, sobald ein Warteschlangenelement verarbeitet wird.The function polls the myqueue-items queue and writes a log each time a queue item is processed.

Die Datei function.json sieht wie folgt aus:Here's the function.json file:

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

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.The configuration section explains these properties.

Hinweis

Der Namensparameter wird als context.bindings.<name> im JavaScript-Code wiedergegeben, der die Nutzlast des Warteschlangenelements enthält.The name parameter reflects as context.bindings.<name> in the JavaScript code which contains the queue item payload. Diese Nutzlast wird der Funktion außerdem als zweiter Parameter übergeben.This payload is also passed as the second parameter to the function.

Der JavaScript-Code sieht wie folgt aus:Here's the JavaScript code:

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);
    context.done();
};

Im Abschnitt Verwendung finden Sie weitere Informationen zu myQueueItem (benannt durch die Eigenschaft name in „function.json“).The usage section explains myQueueItem, which is named by the name property in function.json. Alle anderen gezeigten Variablen werden im Abschnitt Nachrichtenmetadaten erläutert.The message metadata section explains all of the other variables shown.

Trigger: Java-BeispielTrigger - Java example

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.The following Java example shows a storage queue trigger functions which logs the triggered message placed into queue myqueuename.

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

Trigger: AttributeTrigger - attributes

Verwenden Sie in C#-Klassenbibliotheken die folgenden Attribute, um einen Warteschlangentrigger zu konfigurieren:In C# class libraries, use the following attributes to configure a queue trigger:

  • QueueTriggerAttributeQueueTriggerAttribute

    Der Konstruktor des Attributs akzeptiert den Namen der zu überwachenden Warteschlange, wie im folgenden Beispiel zu sehen:The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

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

    Durch Festlegen der Eigenschaft Connection können Sie das zu verwendende Speicherkonto angeben, wie im folgenden Beispiel zu sehen:You can set the Connection property to specify the storage account to use, as shown in the following example:

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

    Ein vollständiges Beispiel finden Sie unter Trigger: C#-Beispiel.For a complete example, see Trigger - C# example.

  • StorageAccountAttributeStorageAccountAttribute

    Eine weitere Möglichkeit zum Angeben des zu verwendenden Speicherkontos.Provides another way to specify the storage account to use. Der Konstruktor akzeptiert den Namen einer App-Einstellung mit einer Speicherverbindungszeichenfolge.The constructor takes the name of an app setting that contains a storage connection string. Das Attribut kann auf Parameter-, Methoden- oder Klassenebene angewendet werden.The attribute can be applied at the parameter, method, or class level. Das folgende Beispiel zeigt die Anwendung auf Klassen- und Methodenebene:The following example shows class level and method level:

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

Das zu verwendende Speicherkonto wird anhand von Folgendem bestimmt (in der angegebenen Reihenfolge):The storage account to use is determined in the following order:

  • Die Eigenschaft Connection des Attributs QueueTrigger.The QueueTrigger attribute's Connection property.
  • Das Attribut StorageAccount, das auf den gleichen Parameter angewendet wird wie das Attribut QueueTrigger.The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • Das Attribut StorageAccount, das auf die Funktion angewendet wird.The StorageAccount attribute applied to the function.
  • Das Attribut StorageAccount, das auf die Klasse angewendet wird.The StorageAccount attribute applied to the class.
  • Die App-Einstellung „AzureWebJobsStorage“.The "AzureWebJobsStorage" app setting.

Trigger: KonfigurationTrigger - configuration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut QueueTrigger festlegen:The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

Eigenschaft von „function.json“function.json property AttributeigenschaftAttribute property BESCHREIBUNGDescription
typetype n/a Muss auf queueTrigger festgelegt sein.Must be set to queueTrigger. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/a Nur in der Datei function.json.In the function.json file only. Muss auf in festgelegt sein.Must be set to in. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
namename n/a Der Name der Variablen, die die Nutzlast des Warteschlangenelements im Funktionscode enthält.The name of the variable that contains the queue item payload in the function code.
queueNamequeueName QueueNameQueueName Der Name der abzufragenden Warteschlange.The name of the queue to poll.
Verbindungconnection ConnectionConnection Der Name einer App-Einstellung, die die Storage-Verbindungszeichenfolge für diese Bindung enthält.The name of an app setting that contains the Storage connection string to use for this binding. Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie hier nur den Rest des Namens angeben.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Wenn Sie connection also beispielsweise auf „MyStorage“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyStorage“.For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Storage-Verbindungszeichenfolge aus der App-Einstellung AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.When you're developing locally, app settings go into the local.settings.json file.

Trigger: VerwendungTrigger - usage

Verwenden Sie in C# und C#-Skripts einen Methodenparameter wie string paramName, um auf die Nachrichtendaten zuzugreifen.In C# and C# script, access the message data by using a method parameter such as string paramName. In C#-Skripts ist paramName der Wert, der in der Eigenschaft name von function.json angegeben ist.In C# script, paramName is the value specified in the name property of function.json. Eine Bindung kann mit folgenden Typen erstellt werden:You can bind to any of the following types:

  • Objekt – Die Functions-Runtime deserialisiert eine JSON-Nutzlast in eine Instanz einer beliebigen Klasse, die in Ihrem Code definiert ist.Object - The Functions runtime deserializes a JSON payload into an instance of an arbitrary class defined in your code.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

Wenn Sie versuchen, eine Bindung an CloudQueueMessage herzustellen, und eine Fehlermeldung erhalten, stellen Sie sicher, dass ein Verweis auf die richtige Storage SDK-Version vorliegt.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

Verwenden Sie in JavaScript context.bindings.<name>, um auf die Nutzlast des Warteschlangenelements zuzugreifen.In JavaScript, use context.bindings.<name> to access the queue item payload. Falls es sich um eine JSON-Nutzlast handelt, wird sie in ein Objekt deserialisiert.If the payload is JSON, it's deserialized into an object.

Trigger: NachrichtenmetadatenTrigger - message metadata

Der Warteschlangentrigger stellt mehrere Metadateneigenschaften bereit.The queue trigger provides several metadata properties. Diese Eigenschaften können als Teil der Bindungsausdrücke in anderen Bindungen oder als Parameter im Code verwendet werden.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Im Folgenden werden Eigenschaften der CloudQueueMessage-Klasse aufgeführt:These are properties of the CloudQueueMessage class.

EigenschaftProperty TypType BESCHREIBUNGDescription
QueueTrigger string Die Warteschlangennutzlast (bei einer gültigen Zeichenfolge).Queue payload (if a valid string). Handelt es sich bei der Warteschlangennutzlast um eine Zeichenfolge, hat QueueTrigger den gleichen Wert wie die Variable, die durch die Eigenschaft name in function.json benannt wird.If the queue message payload as a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int Gibt an, wie oft diese Nachricht aus der Warteschlange entfernt wurde.The number of times this message has been dequeued.
ExpirationTime DateTimeOffset Die Zeit, zu der die Nachricht abläuft.The time that the message expires.
Id string ID der WarteschlangennachrichtQueue message ID.
InsertionTime DateTimeOffset Die Zeit, zu der die Nachricht der Warteschlange hinzugefügt wurde.The time that the message was added to the queue.
NextVisibleTime DateTimeOffset Die Zeit, zu der die Nachricht als Nächstes sichtbar wird.The time that the message will next be visible.
PopReceipt string Die POP-Bestätigung der Nachricht.The message's pop receipt.

Trigger: Nicht verarbeitbare NachrichtenTrigger - poison messages

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.When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. Sind alle fünf Versuche nicht erfolgreich, fügt die Functions-Laufzeit einer Warteschlange namens <Name der Originalwarteschlange>-poison eine Nachricht hinzu.If all five attempts fail, the functions runtime adds a message to a queue named <originalqueuename>-poison. 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.You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

Überprüfen Sie zur manuellen Behandlung nicht verarbeitbarer Nachrichten den Wert dequeueCount der Warteschlangennachricht.To handle poison messages manually, check the dequeueCount of the queue message.

Trigger: AbrufalgorithmusTrigger - polling algorithm

Der Warteschlangentrigger implementiert einen zufälligen exponentiellen Backoffalgorithmus, um die Auswirkungen des Abfragens von Warteschlangen im Leerlauf auf Speichertransaktionskosten zu reduzieren.The queue trigger implements a random exponential back-off algorithm to reduce the effect of idle-queue polling on storage transaction costs. Wenn eine Nachricht gefunden wird, wartet die Runtime zwei Sekunden und prüft dann, ob eine andere Meldung vorhanden ist. Wenn keine Nachricht gefunden wird, wartet sie ungefähr vier Sekunden vor dem erneuten Versuch.When a message is found, the runtime waits two seconds and then checks for another message; when no message is found, it waits about four seconds before trying again. 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.After subsequent failed attempts to get a queue message, the wait time continues to increase until it reaches the maximum wait time, which defaults to one minute. Die maximale Wartezeit kann über die maxPollingInterval-Eigenschaft in der Datei host.json konfiguriert werden.The maximum wait time is configurable via the maxPollingInterval property in the host.json file.

Trigger: ParallelitätTrigger - concurrency

Wenn mehrere Warteschlangennachrichten warten, ruft der Warteschlangentrigger einen Batch mit Nachrichten ab und ruft parallel Funktionsinstanzen zur Verarbeitung auf.When there are multiple queue messages waiting, the queue trigger retrieves a batch of messages and invokes function instances concurrently to process them. Standardmäßig ist die Batchgröße 16.By default, the batch size is 16. Wenn die zu verarbeitende Anzahl 8 erreicht, ruft die Runtime einen weiteren Batch ab und beginnt mit der Verarbeitung dieser Nachrichten.When the number being processed gets down to 8, the runtime gets another batch and starts processing those messages. Aus diesem Grund beträgt die maximale Anzahl der pro Funktion auf einem virtuellen Computer verarbeiteten parallelen Nachrichten 24.So the maximum number of concurrent messages being processed per function on one virtual machine (VM) is 24. Dieser Grenzwert gilt separat für jede durch Warteschlangen ausgelöste Funktion auf jedem virtuellen Computer.This limit applies separately to each queue-triggered function on each VM. Wenn die Funktions-App horizontal auf mehrere virtuelle Computer hochskaliert wird, wartet jeder virtuelle Computer auf Trigger und versucht, Funktionen auszuführen.If your function app scales out to multiple VMs, each VM will wait for triggers and attempt to run functions. 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.For example, if a function app scales out to 3 VMs, the default maximum number of concurrent instances of one queue-triggered function is 72.

Die Batchgröße und der Schwellenwert für das Abrufen eines neuen Batches können in der Datei host.json konfiguriert werden.The batch size and the threshold for getting a new batch are configurable in the host.json file. 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.If you want to minimize parallel execution for queue-triggered functions in a function app, you can set the batch size to 1. Diese Einstellung verhindert Parallelität nur so lange, wie Ihre Funktions-App auf einem einzelnen virtuellen Computer ausgeführt wird.This setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM).

Mit dem Warteschlangentrigger wird automatisch verhindert, dass eine Funktion Warteschlangennachrichten mehrfach verarbeitet. Daher müssen keine idempotenten Funktionen geschrieben werden.The queue trigger automatically prevents a function from processing a queue message multiple times; functions do not have to be written to be idempotent.

Trigger: Eigenschaften von „host.json“Trigger - host.json properties

Die Datei host.json enthält Einstellungen, mit denen das Verhalten des Warteschlangentriggers gesteuert werden kann.The host.json file contains settings that control queue trigger behavior. Informationen zu verfügbaren Einstellungen finden Sie im Abschnitt Einstellungen für „host.json“.See the host.json settings section for details regarding available settings.

OutputOutput

Verwenden Sie die Azure Queue Storage-Ausgabebindung, um Nachrichten in eine Warteschlange zu schreiben.Use the Azure Queue storage output binding to write messages to a queue.

Ausgabe: BeispielOutput - example

Sehen Sie sich das sprachspezifische Beispiel an:See the language-specific example:

Ausgabe: C#-BeispielOutput - C# example

Die C#-Funktion des folgenden Beispiels erstellt eine Warteschlangennachricht für jede empfangene HTTP-Anforderung.The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("AzureWebJobsStorage")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Ausgabe: C#-SkriptbeispielOutput - C# script example

Das folgende Beispiel enthält eine HTTP-Triggerbindung in einer Datei vom Typ function.json sowie Code vom Typ C#-Skript (.csx), in dem die Bindung verwendet wird.The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. Die Funktion erstellt ein Warteschlangenelement mit einer CustomQueueMessage-Objektnutzlast für jede empfangene HTTP-Anforderung.The function creates a queue item with a CustomQueueMessage object payload for each HTTP request received.

Die Datei function.json sieht wie folgt aus:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.The configuration section explains these properties.

Der folgende C#-Skriptcode erstellt eine einzelne Warteschlangennachricht:Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

Mithilfe eines Parameters vom Typ ICollector oder IAsyncCollector können mehrere Nachrichten gleichzeitig gesendet werden.You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Der folgende C#-Skriptcode sendet mehrere Nachrichten – eine mit den HTTP-Anforderungsdaten und eine mit hartcodierten Werten:Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

Ausgabe: JavaScript-BeispielOutput - JavaScript example

Das folgende Beispiel enthält eine HTTP-Triggerbindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet.The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. Die Funktion erstellt ein Warteschlangenelement für jede empfangene HTTP-Anforderung.The function creates a queue item for each HTTP request received.

Die Datei function.json sieht wie folgt aus:Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.The configuration section explains these properties.

Der JavaScript-Code sieht wie folgt aus:Here's the JavaScript code:

module.exports = function (context, input) {
    context.done(null, input.body);
};

Wenn Sie mehrere Nachrichten gleichzeitig senden möchten, können Sie ein Nachrichtenarray für die Ausgabebindung myQueueItem definieren.You can send multiple messages at once by defining a message array for the myQueueItem output binding. Der folgende JavaScript-Code sendet zwei Warteschlangennachrichten mit hartcodierten Werten für jede empfangene HTTP-Anforderung.The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

Ausgabe: Java-BeispielOutput - Java example

Die Java-Funktion des folgenden Beispiels erstellt eine Warteschlangennachricht bei Auslösung durch eine HTTP-Anforderung.The following example shows a Java function that creates a queue message for when triggered by a HTTP request.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "AzureWebJobsStorage")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding&lt;String&gt; result) {
       result.setValue(message + " has been added.");
       return message;
 }

Verwenden Sie die @QueueOutput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Parameter, deren Wert in Queue Storage geschrieben wird.In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. Der Parametertyp sollte OutputBinding<T> lauten, wobei „T“ für einen beliebigen nativen Java-Typ eines POJO steht.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Ausgabe: AttributeOutput - attributes

In C#-Klassenbibliotheken verwenden Sie die QueueAttribute.In C# class libraries, use the QueueAttribute.

Das Attribut gilt für einen Parameter vom Typ out oder für den Rückgabewert der Funktion.The attribute applies to an out parameter or the return value of the function. Der Konstruktor des Attributs akzeptiert den Namen der Warteschlange, wie im folgenden Beispiel zu sehen:The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Durch Festlegen der Eigenschaft Connection können Sie das zu verwendende Speicherkonto angeben, wie im folgenden Beispiel zu sehen:You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

Ein vollständiges Beispiel finden Sie unter Ausgabe: C#-Beispiel.For a complete example, see Output - C# example.

Mit dem Attribut StorageAccount können Sie das Speicherkonto auf Klassen-, Methoden- oder Parameterebene angeben.You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. Weitere Informationen finden Sie unter „Trigger: Attribute“.For more information, see Trigger - attributes.

Ausgabe: KonfigurationOutput - configuration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut Queue festlegen:The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

Eigenschaft von „function.json“function.json property AttributeigenschaftAttribute property BESCHREIBUNGDescription
typetype n/a Muss auf queue festgelegt sein.Must be set to queue. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/a Muss auf out festgelegt sein.Must be set to out. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
namename n/a Der Name der Variablen, die die Warteschlange im Funktionscode darstellt.The name of the variable that represents the queue in function code. Legen Sie diesen Wert auf $return fest, um auf den Rückgabewert der Funktion zu verweisen.Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName Der Name der Warteschlange.The name of the queue.
Verbindungconnection ConnectionConnection Der Name einer App-Einstellung, die die Storage-Verbindungszeichenfolge für diese Bindung enthält.The name of an app setting that contains the Storage connection string to use for this binding. Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie hier nur den Rest des Namens angeben.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. Wenn Sie connection also beispielsweise auf „MyStorage“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyStorage“.For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Storage-Verbindungszeichenfolge aus der App-Einstellung AzureWebJobsStorage.If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.When you're developing locally, app settings go into the local.settings.json file.

Ausgabe: VerwendungOutput - usage

Verwenden Sie in C# und C#-Skripts einen Methodenparameter wie out T paramName, um eine einzelne Warteschlangennachricht zu schreiben.In C# and C# script, write a single queue message by using a method parameter such as out T paramName. In C#-Skripts ist paramName der Wert, der in der Eigenschaft name von function.json angegeben ist.In C# script, paramName is the value specified in the name property of function.json. Anstelle eines Parameters vom Typ out können Sie den Rückgabetyp der Methode verwenden, und T kann einer der folgenden Typen sein:You can use the method return type instead of an out parameter, and T can be any of the following types:

Wenn Sie versuchen, eine Bindung an CloudQueueMessage herzustellen, und eine Fehlermeldung erhalten, stellen Sie sicher, dass ein Verweis auf die richtige Storage SDK-Version vorliegt.If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

Verwenden Sie einen der folgenden Typen, um in C# und C#-Skripts mehrere Warteschlangennachrichten zu schreiben:In C# and C# script, write multiple queue messages by using one of the following types:

Verwenden Sie in JavaScript-Funktionen context.bindings.<name>, um auf die Ausgabewarteschlangennachricht zuzugreifen.In JavaScript functions, use context.bindings.<name> to access the output queue message. Für die Nutzlast des Warteschlangenelements kann eine Zeichenfolge oder ein JSON-serialisierbares Objekt verwendet werden.You can use a string or a JSON-serializable object for the queue item payload.

Ausnahmen und RückgabecodesExceptions and return codes

BindungBinding VerweisReference
WarteschlangeQueue Warteschlangen-FehlercodesQueue Error Codes
Blob, Tabelle, WarteschlangeBlob, Table, Queue SpeicherfehlercodesStorage Error Codes
Blob, Tabelle, WarteschlangeBlob, Table, Queue ProblembehandlungTroubleshooting

Einstellungen für „host.json“host.json settings

In diesem Abschnitt werden die verfügbaren globalen Konfigurationseinstellungen für diese Bindung in Version 2.x beschrieben.This section describes the global configuration settings available for this binding in version 2.x. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x für diese Bindung.The example host.json file below contains only the version 2.x settings for this binding. Weitere Informationen zu globalen Konfigurationseinstellungen in Version 2.x finden Sie unter host.json-Referenz für Azure Functions 2.x.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

Hinweis

Eine Referenz für „host.json“ in Functions 1.x finden Sie unter host.json-Referenz für Azure Functions 1.x.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8
        }
    }
}
EigenschaftProperty StandardDefault BESCHREIBUNGDescription
maxPollingIntervalmaxPollingInterval 00:00:0100:00:01 Das maximale Intervall zwischen Warteschlangenabfragen.The maximum interval between queue polls. Der Mindestwert lautet 00:00:00.100 (100 ms).Minimum is 00:00:00.100 (100 ms).
visibilityTimeoutvisibilityTimeout 00:00:0000:00:00 Das Zeitintervall zwischen Wiederholungsversuchen, wenn bei der Verarbeitung einer Nachricht ein Fehler auftritt.The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 Die Anzahl der Warteschlangennachrichten, die die Functions-Runtime gleichzeitig abruft und parallel verarbeitet.The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. Wenn die zu verarbeitende Anzahl newBatchThreshold erreicht, ruft die Runtime einen weiteren Batch ab und beginnt mit der Verarbeitung dieser Nachrichten.When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. Aus diesem Grund beträgt die maximale Anzahl der pro Funktion verarbeiteten Nachrichten batchSize plus newBatchThreshold.So the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. Dieser Grenzwert gilt separat für jede Funktion, die durch die Warteschlange ausgelöst wird.This limit applies separately to each queue-triggered function.

Wenn Sie eine parallele Ausführung für in einer Warteschlange empfangene Nachrichten vermeiden möchten, können Sie batchSize auf „1“ festlegen.If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. Diese Einstellung verhindert Parallelität jedoch nur so lange, wie Ihre Funktions-App auf einem einzelnen virtuellen Computer (VM) ausgeführt wird.However, this setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM). 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.If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

Die maximale batchSize beträgt 32.The maximum batchSize is 32.
maxDequeueCountmaxDequeueCount 55 Die Anzahl der Versuche zum Verarbeiten einer Nachricht, bevor diese in die Warteschlange für nicht verarbeitete Nachrichten verschoben wird.The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 Wenn die Anzahl der gleichzeitig verarbeiteten Nachrichten auf diesen Wert sinkt, ruft die Runtime einen weiteren Batch ab.Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

Nächste SchritteNext steps