Azure Queue Storage-Ausgabebindungen für Azure Functions

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.

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.

[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.ToString()}"};

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

    // Queue Output messages
    return messages;
}

Die C#-Funktion des folgenden Beispiels erstellt eine Warteschlangennachricht für jede empfangene HTTP-Anforderung.

[StorageAccount("MyStorageConnectionAppSetting")]
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;
    }
}

Die per HTTP ausgelöste TypeScript-Funktion im folgenden Beispiel erstellt ein Warteschlangenelement für jede empfangene HTTP-Anforderung.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

Um mehrere Nachrichten auszugeben, geben Sie ein Array anstelle eines einzelnen Objekts zurück. Beispiel:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

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

Die per HTTP ausgelöste JavaScript-Funktion im folgenden Beispiel erstellt ein Warteschlangenelement für jede empfangene HTTP-Anforderung.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

Um mehrere Nachrichten auszugeben, geben Sie ein Array anstelle eines einzelnen Objekts zurück. Zum Beispiel:

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Ein End-to-End-Beispiel zum Konfigurieren einer Ausgabebindung an den Warteschlangenspeicher finden Sie in einem der folgenden Artikel:

• Verbinden von Funktionen mit Azure Storage mit Visual Studio Code
• Verbinden von Funktionen mit Azure Storage mithilfe von Befehlszeilentools

Das folgende Beispiel enthält eine HTTP-Triggerbindung in einer Datei function.json sowie eine JavaScript-Funktion, die die Bindung verwendet. Die Funktion erstellt ein Warteschlangenelement für jede empfangene HTTP-Anforderung.

Die Datei function.json sieht wie folgt aus:

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

Weitere Informationen zu diesen Eigenschaften finden Sie im Abschnitt Konfiguration.

Der JavaScript-Code sieht wie folgt aus:

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

Wenn Sie mehrere Nachrichten gleichzeitig senden möchten, können Sie ein Nachrichtenarray für die Ausgabebindung myQueueItem definieren. Der folgende JavaScript-Code sendet zwei Warteschlangennachrichten mit hartcodierten Werten für jede empfangene HTTP-Anforderung.

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

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Ein End-to-End-Beispiel zum Konfigurieren einer Ausgabebindung an den Warteschlangenspeicher finden Sie in einem der folgenden Artikel:

• Verbinden von Funktionen mit Azure Storage mit Visual Studio Code
• Verbinden von Funktionen mit Azure Storage mithilfe von Befehlszeilentools

Eine Speicherwarteschlangenbindung ist in function.json definiert, wobei type auf queue festgelegt ist.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

Um eine einzelne Nachricht in die Warteschlange zu stellen, übergeben Sie einen einzelnen Wert an die set-Methode.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Um mehrere Nachrichten in der Warteschlange zu erstellen, deklarieren Sie einen Parameter als geeigneten Listentyp und übergeben ein Array von Werten (die dem Listentyp entsprechen) an die set-Methode.

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Bei Ausführung in einem isolierten Workerprozess verwenden Sie Attribut QueueOutputAttribute, das den Namen der Warteschlange annimmt, wie im folgenden Beispiel gezeigt:

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

Nur zurückgegebene Variablen werden unterstützt, wenn die Ausführung in einem isolierten Workerprozess erfolgt. Ausgabeparameter können nicht verwendet werden.

In C#-Klassenbibliotheken verwenden Sie die QueueAttribute. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

Das Attribut gilt für einen Parameter vom Typ out oder für den Rückgabewert der Funktion. Der Konstruktor des Attributs akzeptiert den Namen der Warteschlange, wie im folgenden Beispiel zu sehen:

[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:

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

Mit dem Attribut StorageAccount können Sie das Speicherkonto auf Klassen-, Methoden- oder Parameterebene angeben. Weitere Informationen finden Sie unter „Trigger: Attribute“.

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

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

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

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

Schreiben einer einzelnen Warteschlangennachricht mittels eines Methodenparameters wie out T paramName. Anstelle eines Parameters vom Typ out können Sie den Rückgabetyp der Methode verwenden, und T kann einer der folgenden Typen sein:

• Ein Objekt, das als JSON serialisierbar ist
• string
• byte[]
• QueueMessage

Beispiele für die Verwendung dieser Typen finden Sie im GitHub-Repository für die jeweilige Erweiterung.

Sie können mehrere Nachrichten in die Warteschlange schreiben, indem Sie einen der folgenden Typen verwenden:

• ICollector<T> oder IAsyncCollector<T>
• QueueClient

Beispiele für die Verwendung von QueueMessage und QueueClient finden Sie im GitHub-Repository für die jeweilige 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.

Schreiben einer einzelnen Warteschlangennachricht mittels eines Methodenparameters wie out T paramName. Anstelle eines Parameters vom Typ out können Sie den Rückgabetyp der Methode verwenden, und T kann einer der folgenden Typen sein:

• Ein Objekt, das als JSON serialisierbar ist
• string
• byte[]
• CloudQueueMessage

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.

Sie können mehrere Nachrichten in die Warteschlange schreiben, indem Sie einen der folgenden Typen verwenden:

• ICollector<T> oder IAsyncCollector<T>
• CloudQueue

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.

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

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

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 .

Der isolierte Workerprozess unterstützt derzeit nur die Bindung an Zeichenfolgenparameter.

Auf das Ausgabeelement der Warteschlange greifen Sie zu, indem Sie den Wert direkt zurückgeben oder context.extraOutputs.set() verwenden. Für die Nutzlast des Warteschlangenelements kann eine Zeichenfolge oder ein JSON-serialisierbares Objekt verwendet werden.

Auf das Ausgabeereignis der Warteschlange greifen Sie mit context.bindings.<name> zu, wobei <name> der in der name-Eigenschaft von function.json angegebene Wert ist. Für die Nutzlast des Warteschlangenelements kann eine Zeichenfolge oder ein JSON-serialisierbares Objekt verwendet werden.