Utdatabindningar för Azure Queue Storage för Azure Functions

  • Artikel

Azure Functions kan skapa nya Azure Queue Storage-meddelanden genom att konfigurera en utdatabindning.

Information om konfiguration och konfigurationsinformation finns i översikten.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden för Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i python-funktionskoden. Mer information finns i utvecklarguiden för Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för in-process-funktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.

Viktigt!

Supporten upphör för den pågående modellen den 10 november 2026. Vi rekommenderar starkt att du migrerar dina appar till den isolerade arbetsmodellen för fullt stöd.

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

I följande exempel visas en Java-funktion som skapar ett kömeddelande för när den utlöses av en HTTP-begäran.

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

I Java Functions-körningsbiblioteket använder du anteckningen @QueueOutput för parametrar vars värde skulle skrivas till Queue Storage. Parametertypen ska vara OutputBinding<T>, där T är alla inbyggda Java-typer av en POJO.

I följande exempel visas en HTTP-utlöst TypeScript-funktion som skapar ett köobjekt för varje HTTP-begäran som tas emot.

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

Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas en HTTP-utlöst JavaScript-funktion som skapar ett köobjekt för varje HTTP-begäran som tas emot.

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.' };
    },
});

Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:

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

Följande kodexempel visar hur du matar ut ett kömeddelande från en HTTP-utlöst funktion. Konfigurationsavsnittet med av typequeue definierar utdatabindningen.

{
  "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"
    }
  ]
}

Med den här bindningskonfigurationen kan en PowerShell-funktion skapa ett kömeddelande med hjälp av Push-OutputBinding. I det här exemplet skapas ett meddelande från en frågesträng eller brödtextparameter.

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"
})

Om du vill skicka flera meddelanden samtidigt definierar du en meddelandematris och använder Push-OutputBinding för att skicka meddelanden till utdatabindningen Queue.

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"
})

I följande exempel visas hur du matar ut enkla och flera värden till lagringsköer. Konfigurationen som behövs för function.json är densamma i båda riktningarna. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

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'

Attribut

Attributet som definierar en utdatabindning i C#-bibliotek beror på i vilket läge C#-klassbiblioteket körs.

När du kör i en isolerad arbetsprocess använder du QueueOutputAttribute, som tar namnet på kön, enligt följande exempel:

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

Endast returnerade variabler stöds när de körs i en isolerad arbetsprocess. Det går inte att använda utdataparametrar.

Dekoratörer

Gäller endast för python v2-programmeringsmodellen.

För Python v2-funktioner som definierats med hjälp av en dekoratör, följande egenskaper på queue_output:

Property beskrivning
arg_name Namnet på variabeln som representerar kön i funktionskoden.
queue_name Namnet på kön.
connection Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Queues. Se Anslut ioner.

Information om Python-funktioner som definierats med hjälp av function.json finns i avsnittet Konfiguration .

Kommentarer

Med QueueOutput-anteckningen kan du skriva ett meddelande som utdata för en funktion. I följande exempel visas en HTTP-utlöst funktion som skapar ett kömeddelande.

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();
    }
}
Property beskrivning
name Deklarerar parameternamnet i funktionssignaturen. När funktionen utlöses innehåller den här parameterns värde innehållet i kömeddelandet.
queueName Deklarerar könamnet i lagringskontot.
connection Pekar på lagringskontots anslutningssträng.

Parametern som är associerad med QueueOutput-anteckningen skrivs som en OutputBinding<T-instans> .

Konfiguration

Gäller endast programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.storageQueue() till metoden.

Property beskrivning
queueName Namnet på kön.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Queues. Se Anslut ioner.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i filen function.json .

function.json egenskap beskrivning
typ Måste anges till queue. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
riktning Måste anges till out. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
Namn Namnet på variabeln som representerar kön i funktionskoden. Ange till för att referera till $return funktionens returvärde.
queueName Namnet på kön.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Queues. Se Anslut ioner.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Se avsnittet Exempel för fullständiga exempel.

Användning

Användningen av köutdatabindningen beror på tilläggspaketversionen och den C#-modalitet som används i funktionsappen, vilket kan vara något av följande:

Ett isolerat arbetsprocessklassbibliotek kompilerade C#-funktioner körs i en process som är isolerad från körningen.

Välj en version för att se användningsinformation för läget och versionen.

När du vill att funktionen ska skriva ett enda meddelande kan köutdatabindningen binda till följande typer:

Typ Beskrivning
string Meddelandeinnehållet som en sträng. Använd när meddelandet är enkel text.
byte[] Byte för meddelandet.
JSON-serialiserbara typer Ett objekt som representerar innehållet i ett JSON-meddelande. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data.

När du vill att funktionen ska skriva flera meddelanden kan köutdatabindningen binda till följande typer:

Typ Beskrivning
T[] där T är en av de enskilda meddelandetyperna En matris som innehåller innehåll för flera meddelanden. Varje post representerar ett meddelande.

För andra utdatascenarier skapar och använder du typer från Azure.Storage.Queues direkt.

Det finns två alternativ för att skriva till en kö från en funktion med hjälp av QueueOutput-kommentaren:

  • Returvärde: Genom att använda anteckningen på själva funktionen skrivs funktionens returvärde till kön.

  • Imperativ: Om du uttryckligen vill ange meddelandevärdet använder du anteckningen på en specifik parameter av typen OutputBinding<T>, där T är en POJO eller någon inbyggd Java-typ. Med den här konfigurationen skriver ett värde till setValue metoden värdet till kön.

Få åtkomst till utdataköobjektet genom att returnera värdet direkt eller med hjälp av context.extraOutputs.set(). Du kan använda en sträng eller ett JSON-serialiserbart objekt för köobjektets nyttolast.

Utdata till kömeddelandet är tillgängliga via Push-OutputBinding där du skickar argument som matchar namnet som anges av bindningens name parameter i filen function.json .

Det finns två alternativ för att skriva från din funktion till den konfigurerade kön:

  • Returvärde: Ange name egenskapen i function.json till $return. Med den här konfigurationen sparas funktionens returvärde som ett kölagringsmeddelande.

  • Imperativ: Skicka ett värde till den angivna metoden för parametern som deklarerats som en Out-typ . Värdet som skickas till set sparas som ett kölagringsmeddelande.

anslutningar

Egenskapen connection är en referens till miljökonfigurationen som anger hur appen ska ansluta till Azure Queues. Den kan ange:

Om det konfigurerade värdet både är en exakt matchning för en enskild inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Connection string

För att få en anslutningssträng följer du stegen som visas i Hantera åtkomstnycklar för lagringskonto.

Den här anslutningssträng ska lagras i en programinställning med ett namn som matchar det värde som anges av connection egenskapen för bindningskonfigurationen.

Om namnet på appinställningen börjar med "AzureWebJobs" kan du bara ange resten av namnet här. Om du till exempel anger connection "MyStorage" letar Functions-körningen efter en appinställning med namnet "AzureWebJobsMyStorage". Om du lämnar connection tomt använder Functions-körningen standardinställningen Storage anslutningssträng i appinställningen med namnet AzureWebJobsStorage.

Identitetsbaserade anslutningar

Om du använder version 5.x eller senare av tillägget (paket 3.x eller senare för non-.NET språkstackar) i stället för att använda en anslutningssträng med en hemlighet kan du låta appen använda en Microsoft Entra-identitet. Om du vill använda en identitet definierar du inställningar under ett vanligt prefix som mappar till connection egenskapen i utlösar- och bindningskonfigurationen.

Om du anger connection "AzureWebJobsStorage" läser du Anslut som värd för lagring med en identitet. För alla andra anslutningar kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Kötjänst-URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 Dataplanets URI för kötjänsten som du ansluter till med hjälp av HTTPS-schemat. <https:// storage_account_name.queue.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri kan användas som ett alias. Om båda formulären tillhandahålls används formuläret queueServiceUri . Formuläret serviceUri kan inte användas när den övergripande anslutningskonfigurationen ska användas mellan blobar, köer och/eller tabeller.

Andra egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. För de flesta Azure-tjänster innebär det att du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt!

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om minsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom detta skulle vara överdriven behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Du måste skapa en rolltilldelning som ger åtkomst till din kö vid körning. Hanteringsroller som Ägare räcker inte. I följande tabell visas inbyggda roller som rekommenderas när du använder kölagringstillägget i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller
Utlösare Dataläsare för lagringskö, datameddelandeprocessor för lagringskö
Utdatabindning Storage Queue Data Contributor, Storage Queue Data Message Sender

Undantag och returkoder

Bindning Referens
Queue Köfelkoder
Blob, Tabell, Kö Felkoder för lagring
Blob, Tabell, Kö Felsökning

Nästa steg