Trigger azure Queue Storage pro Azure Functions

  • Článek

Trigger služby Queue Storage spustí funkci při přidání zpráv do služby Azure Queue Storage.

Rozhodnutí o škálování služby Azure Queue Storage pro plány Consumption a Premium se provádějí prostřednictvím cílového škálování. Další informace najdete v tématu Škálování na základě cíle.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Příklad

Trigger fronty slouží ke spuštění funkce při přijetí nové položky ve frontě. Jako vstup funkce se poskytuje zpráva fronty.

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

Následující příklad ukazuje funkci jazyka C#, která se dotazuje fronty input-queue a zapisuje několik zpráv do výstupní fronty při každém zpracování položky fronty.

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

Následující příklad Javy ukazuje funkci triggeru fronty úložiště, která zaprokoluje aktivovanou zprávu umístěnou do fronty myqueuename.

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

Následující příklad ukazuje funkci TypeScript triggeru fronty. Funkce se dotazuje fronty myqueue-items a zapíše protokol při každém zpracování položky fronty.

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

Část využití vysvětluje queueItem. Část metadat zprávy vysvětluje všechny ostatní zobrazené proměnné.

Následující příklad ukazuje funkci javascriptové aktivační události fronty. Funkce se dotazuje fronty myqueue-items a zapíše protokol při každém zpracování položky fronty.

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

Část využití vysvětluje queueItem. Část metadat zprávy vysvětluje všechny ostatní zobrazené proměnné.

Následující příklad ukazuje, jak číst zprávu fronty předanou funkci prostřednictvím triggeru.

Trigger fronty úložiště je definován v function.json souboru, kde type je nastavena .queueTrigger

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

Kód v souboru Run.ps1 deklaruje parametr jako $QueueItem, který umožňuje číst zprávu fronty ve vaší funkci.

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

Následující příklad ukazuje, jak číst zprávu fronty předanou funkci prostřednictvím triggeru. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

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

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají k definování funkce atribut QueueTriggerAttribute . Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

V knihovnách tříd jazyka C# konstruktor atributu přebírá název fronty k monitorování, jak je znázorněno v následujícím příkladu:

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

Tento příklad také ukazuje nastavení připojovací řetězec v samotném atributu.

Poznámky

Poznámka QueueTrigger umožňuje přístup k frontě, která funkci aktivuje. Následující příklad zpřístupní zprávu fronty funkci prostřednictvím parametru 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);
    }
}
Vlastnost Popis
name Deklaruje název parametru v podpisu funkce. Při aktivaci funkce má hodnota tohoto parametru obsah zprávy fronty.
queueName Deklaruje název fronty v účtu úložiště.
connection Odkazuje na připojovací řetězec účtu úložiště.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Pro funkce Pythonu v2 definované pomocí dekorátorů definují následující vlastnosti v dekorátoru queue_trigger aktivační událost Queue Storage:

Vlastnost Popis
arg_name Deklaruje název parametru v podpisu funkce. Při aktivaci funkce má hodnota tohoto parametru obsah zprávy fronty.
queue_name Deklaruje název fronty v účtu úložiště.
connection Odkazuje na připojovací řetězec účtu úložiště.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace.

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě app.storageQueue() .

Vlastnost Popis
queueName Název fronty, která se má dotazovat.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke frontám Azure. Viz Připojení iony.

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json a atributu QueueTrigger .

vlastnost function.json Popis
type Musí být nastavena na queueTriggerhodnotu . Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
direction Pouze v souboru function.json . Musí být nastavena na inhodnotu . Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
Jméno Název proměnné, která obsahuje datovou část položky fronty v kódu funkce.
queueName Název fronty, která se má dotazovat.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke frontám Azure. Viz Připojení iony.

Kompletní příklady najdete v části Příklad.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Využití

Poznámka:

Funkce očekávají zakódovaný řetězec base64 . Všechny úpravy typu kódování (aby bylo možné připravit data jako řetězec kódovaný v base64 ) je nutné implementovat ve volající službě.

Použití triggeru fronty závisí na verzi balíčku rozšíření a způsobech jazyka C# používaných ve vaší aplikaci funkcí, což může být jeden z těchto režimů:

Kompilovaná funkce C# v izolované knihovně tříd pracovních procesů běží v procesu izolovaném od modulu runtime.

Zvolte verzi, abyste zobrazili podrobnosti o využití pro režim a verzi.

Trigger fronty může svázat s následujícími typy:

Typ Popis
string Obsah zprávy jako řetězec. Používá se, pokud je zpráva jednoduchá.
byte[] Bajty zprávy.
Serializovatelné typy JSON Když zpráva fronty obsahuje data JSON, functions se pokusí deserializovat data JSON do prostého typu objektu CLR (POCO).
QueueMessage1 Zpráva
BinaryData1 Bajty zprávy.

1 Pokud chcete tyto typy použít, musíte odkazovat na Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 nebo novější a běžné závislosti pro vazby typu sady SDK.

Poznámka QueueTrigger umožňuje přístup ke zprávě fronty, která funkci aktivovala.

Získejte přístup k položce fronty jako první argument funkce. Pokud datová část je JSON, hodnota se deserializuje do objektu.

Přístup ke zprávě fronty prostřednictvím řetězcového parametru, který odpovídá názvu určenému parametrem vazby name v souboru function.json .

Přístup ke zprávě fronty prostřednictvím parametru zadaného jako QueueMessage.

Metadata

Trigger fronty poskytuje několik vlastností metadat. Tyto vlastnosti lze použít jako součást vazeb výrazů v jiných vazbách nebo jako parametry v kódu pro pracovníky jazyka, které poskytují tento přístup k metadatům zpráv.

Vlastnosti metadat zprávy jsou členy Třídy CloudQueueMessage .

K vlastnostem metadat zprávy lze přistupovat z context.triggerMetadata.

Vlastnosti metadat zpráv jsou přístupné z předaného $TriggerMetadata parametru.

Vlastnost Type Popis
QueueTrigger string Datová část fronty (pokud platný řetězec) Pokud datová část zprávy fronty je řetězec, QueueTrigger má stejnou hodnotu jako proměnná pojmenovaná name vlastností v function.json.
DequeueCount long Kolikrát byla tato zpráva vyřazena z fronty.
ExpirationTime DateTimeOffset Čas vypršení platnosti zprávy.
Id string ID zprávy fronty
InsertionTime DateTimeOffset Čas přidání zprávy do fronty
NextVisibleTime DateTimeOffset Čas, kdy bude zpráva příště viditelná.
PopReceipt string Potvrzení o pop zprávě.

Následující vlastnosti metadat zpráv jsou přístupné z předaného parametru vazby (msg v předchozích příkladech).

Vlastnost Popis
body Datová část fronty jako řetězec
dequeue_count Kolikrát byla tato zpráva vyřazena z fronty.
expiration_time Čas vypršení platnosti zprávy.
id ID zprávy fronty
insertion_time Čas přidání zprávy do fronty
time_next_visible Čas, kdy bude zpráva příště viditelná.
pop_receipt Potvrzení o pop zprávě.

Propojení

Vlastnost connection je odkazem na konfiguraci prostředí, která určuje, jak se má aplikace připojit ke frontám Azure. Může zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Pokud chcete získat připojovací řetězec, postupujte podle kroků uvedených v tématu Správa přístupových klíčů účtu úložiště.

Tato připojovací řetězec by měla být uložena v nastavení aplikace s názvem, který connection odpovídá hodnotě určené vlastností konfigurace vazby.

Pokud název nastavení aplikace začíná na "AzureWebJobs", můžete zde zadat pouze zbytek názvu. Pokud například nastavíte connection "MyStorage", modul runtime Functions vyhledá nastavení aplikace s názvem AzureWebJobsMyStorage. Pokud necháte connection prázdné, modul runtime Služby Functions použije výchozí připojovací řetězec úložiště v nastavení aplikace s názvem AzureWebJobsStorage.

Připojení založená na identitách

Pokud používáte rozšíření verze 5.x nebo vyšší (sada 3.x nebo vyšší pro non-.NET zásobníky jazyků), místo použití připojovací řetězec s tajným kódem můžete aplikaci použít identitu Microsoft Entra. Pokud chcete použít identitu, definujete nastavení pod běžnou předponou, která se mapuje na connection vlastnost v konfiguraci triggeru a vazby.

Pokud nastavujete connection azureWebJobsStorage, přečtěte si, Připojení hostování úložiště s identitou. Pro všechna ostatní připojení rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Identifikátor URI služby Queue <CONNECTION_NAME_PREFIX>__queueServiceUri1 Identifikátor URI roviny dat služby fronty, ke které se připojujete, pomocí schématu HTTPS. <https:// storage_account_name.queue.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri lze použít jako alias. Pokud jsou k dispozici oba formuláře, použije se queueServiceUri formulář. Formulář serviceUri nelze použít, pokud se má použít celková konfigurace připojení napříč objekty blob, frontami a/nebo tabulkami.

Pro přizpůsobení připojení mohou být nastaveny další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Budete muset vytvořit přiřazení role, které poskytuje přístup k vaší frontě za běhu. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Queue Storage v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí
Trigger Čtečka dat fronty úložiště, procesor zpráv fronty úložiště
Výstupní vazba Přispěvatel dat fronty úložiště, odesílatel dat fronty úložiště

Otrávené zprávy

Když se funkce triggeru fronty nezdaří, Azure Functions tuto funkci opakuje až pětkrát pro danou zprávu fronty, včetně prvního pokusu. Pokud se všech pět pokusů nezdaří, modul runtime funkcí přidá zprávu do fronty s názvem originalqueuename-jed>.< Funkci pro zpracování zpráv z jedové fronty můžete napsat tak, že je zapíšete nebo odešlete oznámení, že je potřeba ruční pozornost.

Pokud chcete zpracovávat otrávené zprávy ručně, zkontrolujte dequeueCount zprávy fronty.

Náhled zámku

Model náhledu zámku se automaticky provádí u triggerů front pomocí mechanismu viditelnosti poskytované službou úložiště. Vzhledem k tomu, že aktivovaná funkce odvolají zprávy, označí se jako neviditelné. Spuštění funkce aktivované frontou může mít jeden z těchto výsledků ve zprávě ve frontě:

  • Provádění funkce se úspěšně dokončí a zpráva se odstraní z fronty.
  • Spuštění funkce selže a hostitel Služby Functions aktualizuje viditelnost zprávy na visibilityTimeoutzákladě nastavení v souboru host.json. Výchozí časový limit viditelnosti je nula, což znamená, že se zpráva okamžitě znovu zobrazí ve frontě pro opětovné zpracování. visibilityTimeout Nastavení použijte ke zpoždění opětovného zpracování zpráv, které se nedaří zpracovat. Toto nastavení časového limitu platí pro všechny funkce aktivované frontou v aplikaci funkcí.
  • Hostitel služby Functions se během provádění funkce chybově ukončí. Pokud dojde k této neobvyklé události, hostitel nemůže použít visibilityTimeout zpracování zprávy. Místo toho je zpráva ponechána s výchozím časovým limitem 10 minut nastaveným službou úložiště. Po 10 minutách se zpráva znovu zobrazí ve frontě pro opětovné zpracování. Tento výchozí časový limit definovaný službou nelze změnit.

Algoritmus dotazování

Trigger fronty implementuje náhodný exponenciální back-off algoritmus, který snižuje účinek nečinného dotazování fronty na náklady na transakce úložiště.

Algoritmus používá následující logiku:

  • Po nalezení zprávy modul runtime počká 100 milisekund a pak zkontroluje jinou zprávu.
  • Pokud se žádná zpráva nenajde, čeká přibližně 200 milisekund, než se pokusíte znovu.
  • Po následných neúspěšných pokusech o získání zprávy fronty se doba čekání bude dál zvětšovat, dokud nedosáhne maximální doby čekání, což je ve výchozím nastavení jedna minuta.
  • Maximální doba čekání je konfigurovatelná prostřednictvím maxPollingInterval vlastnosti v souboru host.json.

Během místního vývoje se maximální interval dotazování nastaví na dvě sekundy.

Poznámka:

Pokud jde o fakturaci při hostování aplikací funkcí v plánu Consumption, neúčtují se vám poplatky za čas strávený dotazováním modulem runtime.

Souběžnost

Pokud čeká více zpráv fronty, trigger fronty načte dávku zpráv a vyvolá instance funkcí souběžně, aby je zpracoval. Ve výchozím nastavení je velikost dávky 16. Když se počet zpracovávaných dat dostane dolů na 8, modul runtime získá další dávku a začne tyto zprávy zpracovávat. Maximální počet souběžných zpráv zpracovávaných na funkci na jednom virtuálním počítači je tedy 24. Tento limit platí zvlášť pro každou funkci aktivovanou frontou na každém virtuálním počítači. Pokud se vaše aplikace funkcí škáluje na více virtuálních počítačů, každý virtuální počítač počká na triggery a pokusí se spustit funkce. Pokud například aplikace funkcí škáluje kapacitu na 3 virtuální počítače, výchozí maximální počet souběžných instancí jedné funkce aktivované frontou je 72.

Velikost dávky a prahová hodnota pro získání nové dávky je možné konfigurovat v souboru host.json. Pokud chcete minimalizovat paralelní spouštění pro funkce aktivované frontou v aplikaci funkcí, můžete nastavit velikost dávky na 1. Toto nastavení eliminuje souběžnost jenom za předpokladu, že vaše aplikace funkcí běží na jednom virtuálním počítači.

Trigger fronty automaticky zabraňuje funkci ve zpracování zprávy fronty vícekrát současně.

host.json vlastnosti

Soubor host.json obsahuje nastavení, která řídí chování triggeru fronty. Podrobnosti o dostupných nastaveních najdete v části nastavení host.json .

Další kroky