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 befindet sich derzeit in der Vorschauphase und bietet JavaScript- und TypeScript-Entwickler*innen eine flexiblere und intuitivere Erfahrung. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Upgradeleitfaden.

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:

  • In-Process-Klassenbibliothek: 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.
  • Klassenbibliothek in einem isolierten Workerprozess: 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.

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

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.

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

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

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

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

Eigenschaft von „function.json“ 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 -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 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.

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:

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.

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 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 eine höhere Version der Erweiterung verwenden, kann die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Azure Active Directory-Identität verwenden. 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 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