Azure Queue Storage-utlösare för Azure Functions

  • Artikel

Kölagringsutlösaren kör en funktion när meddelanden läggs till i Azure Queue Storage.

Skalningsbeslut för Azure Queue Storage för förbruknings- och Premium-planer görs via målbaserad skalning. Mer information finns i Målbaserad skalning.

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

Använd köutlösaren för att starta en funktion när ett nytt objekt tas emot i en kö. Kömeddelandet anges som indata till funktionen.

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.

I följande exempel visas en C#-funktion som avsöker input-queue kön och skriver flera meddelanden till en utdatakö varje gång ett köobjekt bearbetas.

[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 Java-exempel visas en funktion för lagringsköutlösare som loggar det utlösta meddelandet som placeras i kön myqueuename.

@FunctionName("queueprocessor")
public void run(
    @QueueTrigger(name = "msg",
                queueName = "myqueuename",
                connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

I följande exempel visas en TypeScript-funktion för köutlösare. Funktionen avsöker myqueue-items kön och skriver en logg varje gång ett köobjekt bearbetas.

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

Användningsavsnittet förklarar queueItem. I avsnittet med meddelandemetadata förklaras alla andra variabler som visas.

I följande exempel visas en JavaScript-funktion för köutlösare. Funktionen avsöker myqueue-items kön och skriver en logg varje gång ett köobjekt bearbetas.

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

Användningsavsnittet förklarar queueItem. I avsnittet med meddelandemetadata förklaras alla andra variabler som visas.

I följande exempel visas hur du läser ett kömeddelande som skickas till en funktion via en utlösare.

En Storage-köutlösare definieras i function.json fil där type är inställd på queueTrigger .

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Koden i Filen Run.ps1 deklarerar en parameter som $QueueItem, som gör att du kan läsa kömeddelandet i din funktion.

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

I följande exempel visas hur du läser ett kömeddelande som skickas till en funktion via en utlösare. 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="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')

Attribut

C#-biblioteken i både processprocess och isolerad arbetsprocess använder QueueTriggerAttribute för att definiera funktionen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

I C#-klassbibliotek tar attributets konstruktor namnet på kön för att övervaka, som du ser i följande exempel:

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

Det här exemplet visar också inställningen anslutningssträng i själva attributet.

Kommentarer

Anteckningen QueueTrigger ger dig åtkomst till kön som utlöser funktionen. I följande exempel blir kömeddelandet tillgängligt för funktionen via parametern message .

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

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}
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.

Dekoratörer

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

För Python v2-funktioner som definierats med hjälp av dekoratörer definierar följande egenskaper i queue_trigger dekoratören utlösaren För Kölagringsutlösare:

Property beskrivning
arg_name Deklarerar parameternamnet i funktionssignaturen. När funktionen utlöses innehåller den här parameterns värde innehållet i kömeddelandet.
queue_name Deklarerar könamnet i lagringskontot.
connection Pekar på lagringskontots anslutningssträng.

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

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 app.storageQueue() till metoden.

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

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

function.json egenskap beskrivning
typ Måste anges till queueTrigger. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
riktning Endast i filen function.json . Måste anges till in. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure-portalen.
Namn Namnet på variabeln som innehåller nyttolasten för köobjektet i funktionskoden.
queueName Namnet på kön som ska avsökas.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Azure Queues. Se Anslut ioner.

Se avsnittet Exempel för fullständiga exempel.

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

Användning

Kommentar

Functions förväntar sig en base64-kodad sträng. Eventuella justeringar av kodningstypen (för att förbereda data som en base64-kodad sträng) måste implementeras i den anropande tjänsten.

Användningen av köutlösaren beror på versionen av tilläggspaketet och den C#-modalitet som används i funktionsappen, vilket kan vara något av följande lägen:

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.

Köutlösaren kan 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 När ett kömeddelande innehåller JSON-data försöker Functions deserialisera JSON-data till en oformaterad TYP av CLR-objekt (POCO).
QueueMessage1 Meddelandet.
BinaryData1 Byte för meddelandet.

1 Om du vill använda dessa typer måste du referera till Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 eller senare och de vanliga beroendena för SDK-typbindningar.

QueueTrigger-kommentaren ger dig åtkomst till kömeddelandet som utlöste funktionen.

Få åtkomst till köobjektet som det första argumentet till din funktion. Om nyttolasten är JSON deserialiseras värdet till ett objekt.

Få åtkomst till kömeddelandet via strängparametern som matchar namnet som anges av bindningens name parameter i filen function.json .

Få åtkomst till kömeddelandet via parametern som anges som QueueMessage.

Metadata

Köutlösaren innehåller flera metadataegenskaper. Dessa egenskaper kan användas som en del av bindningsuttryck i andra bindningar eller som parametrar i koden för språkarbetare som ger den här åtkomsten till meddelandemetadata.

Egenskaperna för meddelandemetadata är medlemmar i klassen CloudQueueMessage .

Egenskaperna för meddelandemetadata kan nås från context.triggerMetadata.

Egenskaperna för meddelandemetadata kan nås från den skickade $TriggerMetadata parametern.

Property Type Beskrivning
QueueTrigger string Könyttolast (om en giltig sträng). Om nyttolasten för kömeddelandet är en sträng har QueueTrigger samma värde som variabeln som heter av name egenskapen i function.json.
DequeueCount long Antalet gånger meddelandet har tagits bort.
ExpirationTime DateTimeOffset Tiden då meddelandet upphör att gälla.
Id string Kömeddelande-ID.
InsertionTime DateTimeOffset Den tid då meddelandet lades till i kön.
NextVisibleTime DateTimeOffset Den tid då meddelandet visas härnäst.
PopReceipt string Meddelandets popkvitto.

Följande egenskaper för meddelandemetadata kan nås från den skickade bindningsparametern (msg i tidigare exempel).

Property beskrivning
body Könyttolast som en sträng.
dequeue_count Antalet gånger meddelandet har tagits bort.
expiration_time Tiden då meddelandet upphör att gälla.
id Kömeddelande-ID.
insertion_time Den tid då meddelandet lades till i kön.
time_next_visible Den tid då meddelandet visas härnäst.
pop_receipt Meddelandets popkvitto.

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

Giftmeddelanden

När en köutlösarfunktion misslyckas försöker Azure Functions funktionen igen upp till fem gånger för ett givet kömeddelande, inklusive det första försöket. Om alla fem försök misslyckas lägger funktionskörningen till ett meddelande i en kö med namnet <originalqueuename-poison>. Du kan skriva en funktion för att bearbeta meddelanden från giftkön genom att logga dem eller skicka ett meddelande om att manuell uppmärksamhet krävs.

Om du vill hantera giftmeddelanden manuellt kontrollerar du dequeueCount för kömeddelandet.

Tittlås

Peek-lock-mönstret sker automatiskt för köutlösare med hjälp av synlighetsmekaniken som tillhandahålls av lagringstjänsten. När meddelanden blir utqueuerade av den utlösta funktionen markeras de som osynliga. Körning av en köutlöst funktion kan ha något av följande resultat på meddelandet i kön:

  • Funktionskörningen har slutförts och meddelandet tas bort från kön.
  • Funktionskörningen misslyckas och Functions-värden uppdaterar meddelandets synlighet baserat på visibilityTimeoutinställningen i host.json-filen. Standardtimeouten för synlighet är noll, vilket innebär att meddelandet omedelbart visas igen i kön för ombearbetning. Använd inställningen visibilityTimeout för att fördröja ombearbetningen av meddelanden som inte kan bearbetas. Den här tidsgränsinställningen gäller för alla köutlösta funktioner i funktionsappen.
  • Functions-värden kraschar under funktionskörningen. När den här ovanliga händelsen inträffar kan värden inte tillämpa på visibilityTimeout meddelandet som bearbetas. Meddelandet lämnas i stället med standardtimeouten på 10 minuter som angetts av lagringstjänsten. Efter 10 minuter visas meddelandet igen i kön för ombearbetning. Det går inte att ändra den här tjänstdefinierade standardtimeouten.

Avsökningsalgoritm

Köutlösaren implementerar en slumpmässig exponentiell back-off-algoritm för att minska effekten av inaktivitetskösökning på lagringstransaktionskostnader.

Algoritmen använder följande logik:

  • När ett meddelande hittas väntar körningen 100 millisekunder och söker sedan efter ett annat meddelande.
  • När inget meddelande hittas väntar det cirka 200 millisekunder innan det försöker igen.
  • Efter efterföljande misslyckade försök att få ett kömeddelande fortsätter väntetiden att öka tills den når den maximala väntetiden, som standard är en minut.
  • Den maximala väntetiden maxPollingInterval kan konfigureras via egenskapen i filen host.json.

Under lokal utveckling är det maximala avsökningsintervallet som standard två sekunder.

Kommentar

När det gäller fakturering när du är värd för funktionsappar i förbrukningsplanen debiteras du inte för den tid som avsökningen tar vid körningen.

Samtidighet

När det finns flera kömeddelanden som väntar hämtar köutlösaren en batch meddelanden och anropar funktionsinstanser samtidigt för att bearbeta dem. Som standard är batchstorleken 16. När antalet som bearbetas blir nere på 8 hämtar körningen en annan batch och börjar bearbeta dessa meddelanden. Så det maximala antalet samtidiga meddelanden som bearbetas per funktion på en virtuell dator (VM) är 24. Den här gränsen gäller separat för varje köutlöst funktion på varje virtuell dator. Om funktionsappen skalar ut till flera virtuella datorer väntar varje virtuell dator på utlösare och försöker köra funktioner. Om en funktionsapp till exempel skalar ut till 3 virtuella datorer är det maximala standardantalet samtidiga instanser av en köutlöst funktion 72.

Batchstorleken och tröskelvärdet för att hämta en ny batch kan konfigureras i filen host.json. Om du vill minimera parallell körning för köutlösta funktioner i en funktionsapp kan du ange batchstorleken till 1. Den här inställningen eliminerar endast samtidighet så länge funktionsappen körs på en enda virtuell dator (VM).

Köutlösaren förhindrar automatiskt att en funktion bearbetar ett kömeddelande flera gånger samtidigt.

host.json egenskaper

Filen host.json innehåller inställningar som styr köutlösarens beteende. Mer information om tillgängliga inställningar finns i avsnittet host.json inställningar .

Nästa steg