Azure Queue Storage-Trigger 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.

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;
}

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 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.

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

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.

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.

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.

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')

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)

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 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)
{
    ....
}

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.

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 Prozess ausgeführt wird, der von der Runtime isoliert ist.

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

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.

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.

Der Warteschlangentrigger kann an die folgenden Typen gebunden werden:

¹ 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.

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.

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.

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.