Azure Queue Storage-Ausgabebindungen für Azure Functions

  • Artikel

Azure Functions kann neue Azure Queue Storage-Nachrichten durch Einrichten einer Ausgabebindung erstellen.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

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.

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.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

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.

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

Das folgende Beispiel zeigt eine Java-Funktion, die eine Warteschlangennachricht erstellt, wenn sie durch eine HTTP-Anforderung ausgelöst wird.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> 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. Der Parametertyp sollte OutputBinding<T> lauten, wobei T für einen beliebigen nativen Java-Typ eines POJO steht.

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

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

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

Die folgenden Codebeispiele veranschaulichen, wie eine Warteschlangennachricht aus einer durch HTTP ausgelösten Funktion ausgegeben wird. Der Konfigurationsabschnitt mit dem type von queue definiert die Ausgabebindung.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Mithilfe dieser Bindungskonfiguration kann eine PowerShell-Funktion mithilfe von Push-OutputBinding eine Warteschlangennachricht erstellen. In diesem Beispiel wird eine Nachricht aus einer Abfragezeichenfolge oder einem Textparameter erstellt.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Wenn mehrere Nachrichten gleichzeitig gesendet werden sollen, definieren Sie ein Nachrichtenarray und verwenden Push-OutputBinding, um Nachrichten an die Warteschlangenausgabebindung zu senden.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Im folgenden Beispiel wird veranschaulicht, wie Sie einzelne und mehrere Werte an Speicherwarteschlangen ausgeben. Die für function.json erforderliche Konfiguration ist in beiden Fällen identisch. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

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'

Attributes

Das Attribut, das eine Ausgabebindung in C#-Bibliotheken definiert, hängt vom Modus ab, in dem die C#-Klassenbibliothek ausgeführt wird.

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.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Decorators definiert wurden, gelten die folgenden Eigenschaften für queue_output:

Eigenschaft BESCHREIBUNG
arg_name Der Name der Variablen, die die Warteschlange im Funktionscode darstellt.
queue_name Der Name der Warteschlange.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Azure Queues hergestellt wird. Siehe Verbindungen.

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

Anmerkungen

Die QueueOutput-Anmerkung ermöglicht Ihnen, eine Nachricht als Ausgabe einer Funktion zu schreiben. Das folgende Beispiel zeigt eine HTTP-ausgelöste Funktion, die eine Warteschlangennachricht erstellt.

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

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
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.

Der Parameter, der der QueueOutput-Anmerkung zugeordnet ist, ist als OutputBinding<T>-Instanz typisiert.

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

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.

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

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

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

function.json-Eigenschaft BESCHREIBUNG
type Muss auf queue festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
direction Muss auf out festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name Der Name der Variablen, die die Warteschlange im Funktionscode darstellt. Legen Sie diesen Wert auf $return fest, um auf den Rückgabewert der Funktion zu verweisen.
queueName Der Name der Warteschlange.
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Azure Queues hergestellt wird. Siehe Verbindungen.

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

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verwendung

Die Verwendung der Warteschlangenausgabebindung hängt von der Version des Erweiterungspakets und der C#-Modalität ab, die in Ihrer Funktions-App verwendet wird. Dies kann eine der folgenden Modalitäten sein:

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

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

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

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

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

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

Für andere Ausgabeszenarien erstellen und verwenden Sie Typen direkt aus Azure.Storage.Queues.

Es gibt zwei Optionen für das Schreiben in eine Warteschlange aus einer Funktion mit der QueueOutput-Anmerkung:

  • Rückgabewert: Wenn Sie die Anmerkung auf die Funktion selbst anwenden, wird der Rückgabewert der Funktion in die Warteschlange geschrieben.

  • Imperativ: Um den Nachrichtenwert explizit festzulegen, wenden Sie die Anmerkung auf einen bestimmten Parameter des Typs OutputBinding<T> an, wobei T ein POJO oder ein beliebiger nativer Java-Typ ist. Bei dieser Konfiguration wird bei der Übergabe eines Werts an die setValue-Methode der Wert in die Warteschlange geschrieben.

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.

Die Ausgabe an die Warteschlangennachricht ist über Push-OutputBinding verfügbar. Dort übergeben Sie Argumente, die dem Namen entsprechen, der durch den name-Parameter der Bindung in der Datei function.json festgelegt wird.

Es gibt zwei Optionen zum Schreiben aus Ihrer Funktion in die konfigurierte Warteschlange:

  • Rückgabewert: Legen Sie die Eigenschaft name in function.json auf $return fest. Mit dieser Konfiguration wird der Rückgabewert der Funktion als Queue Storage-Nachricht beibehalten.

  • Imperativ: Übergeben Sie einen Wert an die set-Methode des Parameters, der als Out-Typ deklariert ist. Der an set übergebene Wert wird als Queue Storage-Nachricht beibehalten.

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:

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

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

Ausnahmen und Rückgabecodes

Bindung Verweis
Warteschlange Warteschlangen-Fehlercodes
Blob, Tabelle, Warteschlange Speicherfehlercodes
Blob, Tabelle, Warteschlange Problembehandlung

Nächste Schritte