Azure Queue Storage kimeneti kötések az Azure Functionshez

  • Cikk

Az Azure Functions egy kimeneti kötés beállításával új Azure Queue Storage-üzeneteket hozhat létre.

A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.

Fontos

Ez a cikk lapokat használ a Node.js programozási modell több verziójának támogatásához. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további információkért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.

Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.

A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.

Ez a cikk mindkét programozási modellt támogatja.

Példa

A C#-függvények a következő C#-módok egyikével hozhatók létre:

  • Izolált feldolgozómodell: Lefordított C# függvény, amely a futtatókörnyezettől elkülönített feldolgozói folyamatban fut. Izolált feldolgozói folyamat szükséges az LTS- és nem LTS-verziókon futó C#-függvények támogatásához .NET és .NET-keretrendszer. Az izolált feldolgozói folyamatfüggvények bővítményei névtereket használnak Microsoft.Azure.Functions.Worker.Extensions.* .
  • Folyamaton belüli modell: Lefordított C# függvény, amely ugyanabban a folyamatban fut, mint a Functions-futtatókörnyezet. A modell egy változatában a Functions C#-szkriptekkel futtatható, amely elsősorban a C#-portál szerkesztéséhez támogatott. A folyamaton belüli függvények bővítményei névtereket használnak Microsoft.Azure.WebJobs.Extensions.* .

Fontos

A folyamaton belüli modell támogatása 2026. november 10-én megszűnik. Erősen javasoljuk, hogy az alkalmazásokat az elkülönített feldolgozói modellbe migrálja a teljes támogatás érdekében.

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

Az alábbi példa egy Java-függvényt mutat be, amely egy HTTP-kérés által aktivált üzenetsort hoz létre.

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

A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet azon @QueueOutput paramétereken, amelyek értékét a Queue Storage-ba írná. A paramétertípusnak a POJO bármely natív Java-típusának kell lennieOutputBinding<T>T.

Az alábbi példa egy HTTP által aktivált TypeScript-függvényt mutat be, amely minden fogadott HTTP-kéréshez létrehoz egy üzenetsor-elemet.

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

Több üzenet kimenetéhez egyetlen objektum helyett egy tömböt kell visszaadnia. Példa:

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

Az alábbi példa egy HTTP által aktivált JavaScript-függvényt mutat be, amely minden fogadott HTTP-kéréshez létrehoz egy üzenetsor-elemet.

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

Több üzenet kimenetéhez egyetlen objektum helyett egy tömböt kell visszaadnia. Példa:

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

Az alábbi példakód bemutatja, hogyan jeleníthet meg üzenetsorüzenetet EGY HTTP által aktivált függvényből. A kimeneti kötést a typequeue konfigurációs szakasz határozza meg.

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

Ezzel a kötéskonfigurációval a PowerShell-függvények üzenetsor-üzenetet hozhatnak létre.Push-OutputBinding Ebben a példában egy üzenet jön létre egy lekérdezési sztringből vagy törzsparaméterből.

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

Ha egyszerre több üzenetet szeretne küldeni, definiáljon egy üzenettömböt, és az Push-OutputBinding üzenetsor kimeneti kötésébe küldjön üzeneteket.

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

Az alábbi példa bemutatja, hogyan lehet egyetlen és több értéket kimenetelni a tárolási várólistákra. A function.json konfigurációja mindkét esetben megegyezik. A példa attól függ, hogy a v1 vagy v2 Python programozási modellt használja-e.

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'

Attribútumok

A C#-kódtárakban kimeneti kötést meghatározó attribútum a C# osztálytár futtatásának módjától függ.

Izolált feldolgozói folyamat futtatásakor a QueueOutputAttribute parancsot használja, amely az üzenetsor nevét veszi fel, ahogyan az alábbi példában látható:

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

Csak a visszaadott változók támogatottak, ha izolált feldolgozói folyamatban futnak. A kimeneti paraméterek nem használhatók.

Dekorátorok

Csak a Python v2 programozási modellre vonatkozik.

A dekoratőrrel definiált Python v2-függvények esetében a következő tulajdonságok a queue_outputkövetkezők:

Tulajdonság Leírás
arg_name Annak a változónak a neve, amely az üzenetsort jelöli a függvénykódban.
queue_name Az üzenetsor neve.
connection Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Queueshoz. Lásd: Csatlakozás ions.

A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.

Jegyzetek

A QueueOutput jegyzettel üzenet írható egy függvény kimeneteként. Az alábbi példa egy HTTP által aktivált függvényt mutat be, amely üzenetsort hoz létre.

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();
    }
}
Tulajdonság Leírás
name Deklarálja a paraméter nevét a függvény-aláírásban. A függvény aktiválásakor ennek a paraméternek az értéke tartalmazza az üzenetsor-üzenet tartalmát.
queueName Deklarálja az üzenetsor nevét a tárfiókban.
connection A tárfiókra mutat kapcsolati sztring.

A QueueOutput annotation paramétere OutputBinding T-példányként> van begépelve.<

Konfiguráció

Csak a Python v1 programozási modellre vonatkozik.

Az alábbi táblázat a metódusnak output.storageQueue() átadott objektumon options beállítható tulajdonságokat ismerteti.

Tulajdonság Leírás
queueName Az üzenetsor neve.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Queueshoz. Lásd: Csatlakozás ions.

Helyi fejlesztéskor adja hozzá az alkalmazásbeállításokat a gyűjtemény local.settings.json fájljáhozValues.

Az alábbi táblázat a function.json fájlban beállított kötéskonfigurációs tulajdonságokat ismerteti.

function.json tulajdonság Leírás
type A beállításnak a queuekövetkezőnek kell lennie: . Ez a tulajdonság automatikusan be van állítva, amikor létrehozza az eseményindítót az Azure Portalon.
direction A beállításnak a outkövetkezőnek kell lennie: . Ez a tulajdonság automatikusan be van állítva, amikor létrehozza az eseményindítót az Azure Portalon.
név Annak a változónak a neve, amely az üzenetsort jelöli a függvénykódban. $return A függvény visszatérési értékére való hivatkozásra van állítva.
queueName Az üzenetsor neve.
Kapcsolat Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat az Azure Queueshoz. Lásd: Csatlakozás ions.

Helyi fejlesztéskor adja hozzá az alkalmazásbeállításokat a gyűjtemény local.settings.json fájljáhozValues.

A teljes példákért tekintse meg a Példa szakaszt .

Használat

A Queue kimeneti kötés használata a bővítménycsomag verziójától és a függvényalkalmazásban használt C# modalitástól függ, amely az alábbiak egyike lehet:

A C# függvényt lefordított izolált feldolgozói folyamatosztály-kódtár a futtatókörnyezettől elkülönített folyamatban fut.

Válasszon egy verziót a mód és a verzió használati adatainak megtekintéséhez.

Ha azt szeretné, hogy a függvény egyetlen üzenetet írjon, az üzenetsor kimeneti kötése a következő típusokhoz köthető:

Típus Leírás
string Az üzenet tartalma sztringként. Akkor használja, ha az üzenet egyszerű szöveg.
byte[] Az üzenet bájtja.
JSON szerializálható típusok Egy JSON-üzenet tartalmát képviselő objektum. A Functions egy egyszerű régi CLR-objektum (POCO) típust próbál JSON-adatokká szerializálni.

Ha azt szeretné, hogy a függvény több üzenetet írjon, az üzenetsor kimeneti kötése a következő típusokhoz kapcsolódhat:

Típus Leírás
T[] hol T található az egyetlen üzenettípus Több üzenet tartalmát tartalmazó tömb. Minden bejegyzés egy üzenetet jelöl.

Egyéb kimeneti forgatókönyvek esetén közvetlenül hozzon létre és használjon típusokat az Azure.Storage.Queues szolgáltatásból.

A QueueOutput széljegyzet használatával kétféleképpen írhat egy üzenetsorba egy függvényből:

  • Visszatérési érték: Ha a jegyzetet a függvényre alkalmazza, a függvény visszatérési értéke az üzenetsorba lesz írva.

  • Imperatív: Az üzenet értékének explicit beállításához alkalmazza a széljegyzetet a típus OutputBinding<T>egy adott paraméterére , ahol T a POJO vagy bármely natív Java-típus található. Ezzel a konfigurációval a metódusnak setValue átadott érték az értéket az üzenetsorba írja.

A kimeneti üzenetsor eleméhez közvetlenül vagy a használatával context.extraOutputs.set()adja vissza az értéket. Az üzenetsorelem hasznos adataihoz használhat sztringet vagy JSON-szerializálható objektumot.

Az üzenetsor üzenetének kimenete olyan argumentumok átadásával Push-OutputBinding érhető el, amelyek megfelelnek a kötés paramétere name által a function.json fájlban megadott névnek.

A függvényből a konfigurált üzenetsorba kétféleképpen írhat:

  • Visszatérési érték: Állítsa a tulajdonságot a name function.json értékre$return. Ezzel a konfigurációval a függvény visszatérési értéke üzenetsortár-üzenetként marad meg.

  • Imperatív: Adjon át egy értéket a Ki típusúként deklarált paraméter beállított metódusának. Az átadott set érték üzenetsortár-üzenetként marad meg.

Kapcsolatok

A connection tulajdonság a környezeti konfigurációra mutató hivatkozás, amely meghatározza, hogy az alkalmazásnak hogyan kell csatlakoznia az Azure Queueshoz. A következőt határozhatja meg:

Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.

Kapcsolati sztring

A kapcsolati sztring beszerzéséhez kövesse a tárfiók hozzáférési kulcsainak kezelése című témakörben ismertetett lépéseket.

Ezt a kapcsolati sztring a kötéskonfiguráció tulajdonsága által connection megadott értéknek megfelelő névvel rendelkező alkalmazásbeállításban kell tárolni.

Ha az alkalmazásbeállítás neve az "AzureWebJobs" névvel kezdődik, itt csak a név fennmaradó részét adhatja meg. Ha például a "MyStorage" értékre van állítvaconnection, a Functions-futtatókörnyezet egy "AzureWebJobsMyStorage" nevű alkalmazásbeállítást keres. Ha üresen hagyjaconnection, a Functions-futtatókörnyezet az alapértelmezett Storage-kapcsolati sztring használja a nevesített AzureWebJobsStoragealkalmazásbeállításban.

Identitásalapú kapcsolatok

Ha a bővítmény 5.x vagy újabb verzióját használja (a 3.x vagy újabb csomag non-.NET nyelvi veremekhez), ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Identitás használatához olyan beállításokat kell megadnia egy közös előtag alatt, amely leképezi a tulajdonságot az connection eseményindító és a kötés konfigurációjában.

Ha az "AzureWebJobsStorage" értékre van állítvaconnection, tekintse meg Csatlakozás a tároló identitással való üzemeltetését. Az összes többi kapcsolat esetében a bővítményhez a következő tulajdonságok szükségesek:

Tulajdonság Környezeti változó sablonja Leírás Példaérték
Üzenetsor-szolgáltatás URI-ja <CONNECTION_NAME_PREFIX>__queueServiceUri1 Annak az üzenetsor-szolgáltatásnak az adatsíkja, amelyhez csatlakozik, a HTTPS-séma használatával. <https:// storage_account_name.queue.core.windows.net>

Az 1<CONNECTION_NAME_PREFIX>__serviceUri aliasként használható. Ha mindkét űrlap meg van adva, a rendszer az queueServiceUri űrlapot használja. Az serviceUri űrlap nem használható, ha az általános kapcsolatkonfigurációt blobokon, üzenetsorokon és/vagy táblákon kell használni.

Más tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.

Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential tulajdonságokkal együtt clientID . Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.

Engedély megadása az identitáshoz

Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.

Fontos

A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.

Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít az üzenetsorhoz. A tulajdonoshoz hasonló felügyeleti szerepkörök nem elegendőek. Az alábbi táblázat olyan beépített szerepköröket mutat be, amelyek a Queue Storage bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.

Kötés típusa Példa beépített szerepkörökre
Eseményindító Storage Queue Data Reader, Storage Queue Data Message Processor
Kimeneti kötés Storage Queue Data Contributor, Storage Queue Data Message Sender

Kivételek és visszatérési kódok

Kötés Referencia
Feldolgozási sor Üzenetsor hibakódjai
Blob, tábla, üzenetsor Tárolási hibakódok
Blob, tábla, üzenetsor Hibaelhárítás

Következő lépések