Výstupní vazby azure Queue Storage pro Azure Functions

  • Článek

Azure Functions může vytvářet nové zprávy azure Queue Storage nastavením výstupní vazby.

Informace o nastavení a konfiguraci najdete v přehledu.

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

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.

[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 ukazuje funkci Java, která vytvoří zprávu fronty pro při aktivaci požadavkem HTTP.

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

V knihovně modulu runtime funkcí Java použijte poznámku @QueueOutput k parametrům, jejichž hodnota by byla zapsána do queue storage. Typ parametru by měl být OutputBinding<T>, kde T je jakýkoli nativní typ Javy POJO.

Následující příklad ukazuje funkci TypeScript aktivovanou protokolem HTTP, která vytvoří položku fronty pro každý přijatý požadavek HTTP.

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

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje funkci Jazyka JavaScript aktivovanou protokolem HTTP, která vytvoří položku fronty pro každý přijatý požadavek HTTP.

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

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklady kódu ukazují, jak vytvořit výstup zprávy fronty z funkce aktivované protokolem HTTP. Oddíl konfigurace s typequeue definicí výstupní vazby.

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

Pomocí této konfigurace vazby může funkce PowerShellu vytvořit zprávu fronty pomocí Push-OutputBinding. V tomto příkladu se vytvoří zpráva z řetězce dotazu nebo základního parametru.

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

Pokud chcete odeslat více zpráv najednou, definujte pole zpráv a použijte Push-OutputBinding k odesílání zpráv do výstupní vazby fronty.

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

Následující příklad ukazuje výstup jedné a více hodnot do front úložiště. Konfigurace potřebná pro function.json je v obou směrech stejná. 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="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'

Atributy

Atribut, který definuje výstupní vazbu v knihovnách jazyka C#, závisí na režimu, ve kterém je knihovna tříd jazyka C#spuštěna.

Při spuštění v izolovaném pracovním procesu použijete QueueOutputAttribute, který převezme název fronty, 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)

Při spuštění v izolovaném pracovním procesu jsou podporovány pouze vrácené proměnné. Výstupní parametry nelze použít.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Pro funkce Pythonu v2 definované pomocí dekorátoru následující vlastnosti:queue_output

Vlastnost Popis
arg_name Název proměnné, která představuje frontu v kódu funkce.
queue_name Název fronty.
connection Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke frontám Azure. Viz Připojení iony.

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

Poznámky

Poznámka QueueOutput umožňuje napsat zprávu jako výstup funkce. Následující příklad ukazuje funkci aktivovanou protokolem HTTP, která vytvoří zprávu fronty.

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();
    }
}
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ě.

Parametr přidružený k poznámce QueueOutput je zadán jako outputBinding<T> instance.

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ě output.storageQueue() .

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

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

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

vlastnost function.json Popis
type Musí být nastavena na queuehodnotu . Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
direction Musí být nastavena na outhodnotu . Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
Jméno Název proměnné, která představuje frontu v kódu funkce. Nastaví se tak, aby $return odkaz na vrácenou hodnotu funkce.
queueName Název fronty.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke frontám Azure. Viz Připojení iony.

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

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

Využití

Použití výstupní vazby fronty závisí na verzi balíčku rozšíření a režimu jazyka C# používaném ve vaší aplikaci funkcí, což může být jedna z následujících možností:

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.

Pokud chcete, aby funkce zapisuje jednu zprávu, výstupní vazba fronty může svázat s následujícími typy:

Typ Popis
string Obsah zprávy jako řetězec. Používá se, když je zpráva jednoduchá.
byte[] Bajty zprávy.
Serializovatelné typy JSON Objekt představující obsah zprávy JSON. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisuje více zpráv, výstupní vazba fronty může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single message types Pole obsahující obsah pro více zpráv. Každá položka představuje jednu zprávu.

V případě jiných výstupních scénářů můžete přímo vytvářet a používat typy z Azure.Storage.Queues .

Existují dvě možnosti zápisu do fronty z funkce pomocí poznámky QueueOutput :

  • Návratová hodnota: Použitím poznámky na samotnou funkci se návratová hodnota funkce zapíše do fronty.

  • Imperativní: Pokud chcete explicitně nastavit hodnotu zprávy, použijte poznámku na konkrétní parametr typu OutputBinding<T>, kde T je POJO nebo jakýkoli nativní typ Java. Při této konfiguraci předání hodnoty setValue metodě zapíše hodnotu do fronty.

Přístup k výstupní položce fronty vrácením hodnoty přímo nebo pomocí context.extraOutputs.set(). Pro datovou část položky fronty můžete použít řetězec nebo serializovatelný objekt JSON.

Výstup zprávy fronty je k dispozici prostřednictvím Push-OutputBinding předávání argumentů, které odpovídají názvu určenému parametrem vazby name v souboru function.json .

Existují dvě možnosti zápisu z vaší funkce do nakonfigurované fronty:

  • Návratová hodnota: Nastavte name vlastnost v function.json na $returnhodnotu . Při této konfiguraci se návratová hodnota funkce zachová jako zpráva queue storage.

  • Imperativní: Předejte hodnotu metodě sady parametru deklarovaného jako typ Out . Předaná set hodnota je trvalá jako zpráva queue storage.

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ě

Výjimky a návratové kódy

Vazba Reference
Fronta Kódy chyb fronty
Objekt blob, tabulka, fronta Kódy chyb úložiště
Objekt blob, tabulka, fronta Řešení potíží

Další kroky