Uitvoerbindingen voor Azure Queue Storage voor Azure Functions

  • Artikel

Azure Functions kan nieuwe Azure Queue Storage-berichten maken door een uitvoerbinding in te stellen.

Zie het overzicht voor informatie over het instellen en configureren van details.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Met het Python v2-programmeermodel kunt u bindingen definiëren met behulp van decorators rechtstreeks in uw Python-functiecode. Zie de Ontwikkelaarshandleiding voor Python voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

U kunt een C#-functie maken met behulp van een van de volgende C#-modi:

  • Geïsoleerd werkrolmodel: gecompileerde C#-functie die wordt uitgevoerd in een werkproces dat is geïsoleerd van de runtime. Geïsoleerd werkproces is vereist voor de ondersteuning van C#-functies die worden uitgevoerd op LTS- en niet-LTS-versies .NET en .NET Framework. Extensies voor geïsoleerde werkprocesfuncties maken gebruik van Microsoft.Azure.Functions.Worker.Extensions.* naamruimten.
  • In-process model: gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime. In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Extensies voor in-process-functies maken gebruik van Microsoft.Azure.WebJobs.Extensions.* naamruimten.

Belangrijk

De ondersteuning wordt beëindigd voor het in-process model op 10 november 2026. We raden u ten zeerste aan uw apps te migreren naar het geïsoleerde werkrolmodel voor volledige ondersteuning.

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

In het volgende voorbeeld ziet u een Java-functie die een wachtrijbericht maakt voor wanneer deze wordt geactiveerd door een HTTP-aanvraag.

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

Gebruik in de Runtime-bibliotheek van Java-functies de @QueueOutput aantekening voor parameters waarvan de waarde naar Queue Storage wordt geschreven. Het parametertype moet zijn OutputBinding<T>, waarbij T elk systeemeigen Java-type van een POJO is.

In het volgende voorbeeld ziet u een door HTTP geactiveerde TypeScript-functie waarmee een wachtrijitem wordt gemaakt voor elke ontvangen HTTP-aanvraag.

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

Als u meerdere berichten wilt uitvoeren, retourneert u een matrix in plaats van één object. Voorbeeld:

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

In het volgende voorbeeld ziet u een door HTTP geactiveerde JavaScript-functie waarmee een wachtrijitem wordt gemaakt voor elke ontvangen HTTP-aanvraag.

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

Als u meerdere berichten wilt uitvoeren, retourneert u een matrix in plaats van één object. Voorbeeld:

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

In de volgende codevoorbeelden ziet u hoe u een wachtrijbericht uitvoert van een door HTTP geactiveerde functie. De configuratiesectie met de type definitie van queue de uitvoerbinding.

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

Met deze bindingsconfiguratie kan een PowerShell-functie een wachtrijbericht maken met behulp van Push-OutputBinding. In dit voorbeeld wordt een bericht gemaakt op basis van een querytekenreeks of hoofdtekstparameter.

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

Als u meerdere berichten tegelijk wilt verzenden, definieert u een berichtenmatrix en gebruikt Push-OutputBinding u deze om berichten naar de wachtrijuitvoerbinding te verzenden.

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

In het volgende voorbeeld ziet u hoe u één en meerdere waarden naar opslagwachtrijen uitvoert. De configuratie die nodig is voor function.json is op beide manieren hetzelfde. Het voorbeeld is afhankelijk van of u het python-programmeermodel v1 of v2 gebruikt.

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'

Kenmerken

Het kenmerk dat een uitvoerbinding definieert in C#-bibliotheken, is afhankelijk van de modus waarin de C#-klassebibliotheek wordt uitgevoerd.

Wanneer u wordt uitgevoerd in een geïsoleerd werkproces, gebruikt u queueOutputAttribute, die de naam van de wachtrij gebruikt, zoals wordt weergegeven in het volgende voorbeeld:

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

Alleen geretourneerde variabelen worden ondersteund wanneer ze worden uitgevoerd in een geïsoleerd werkproces. Uitvoerparameters kunnen niet worden gebruikt.

Decorators

Is alleen van toepassing op het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met behulp van een decorator, zijn de volgende eigenschappen op het queue_outputvolgende:

Eigenschappen Beschrijving
arg_name De naam van de variabele die de wachtrij in functiecode vertegenwoordigt.
queue_name De naam van de wachtrij.
connection De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Queues. Zie Verbinding maken ions.

Zie de sectie Configuratie voor Python-functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Met de aantekening queueOutput kunt u een bericht schrijven als uitvoer van een functie. In het volgende voorbeeld ziet u een door HTTP geactiveerde functie waarmee een wachtrijbericht wordt gemaakt.

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();
    }
}
Eigenschappen Beschrijving
name Declareert de parameternaam in de functiehandtekening. Wanneer de functie wordt geactiveerd, heeft de waarde van deze parameter de inhoud van het wachtrijbericht.
queueName Declareert de naam van de wachtrij in het opslagaccount.
connection Verwijst naar het opslagaccount verbindingsreeks.

De parameter die is gekoppeld aan de annotatie queueOutput , wordt getypt als een OutputBinding<T-exemplaar> .

Configuratie

Is alleen van toepassing op het Python v1-programmeermodel.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de output.storageQueue() methode is doorgegeven.

Eigenschappen Beschrijving
queueName De naam van de wachtrij.
verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Queues. Zie Verbinding maken ions.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op queue. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
direction Moet worden ingesteld op out. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
name De naam van de variabele die de wachtrij in functiecode vertegenwoordigt. Ingesteld om $return te verwijzen naar de retourwaarde van de functie.
queueName De naam van de wachtrij.
verbinding De naam van een app-instelling of verzameling die aangeeft hoe verbinding moet worden gemaakt met Azure Queues. Zie Verbinding maken ions.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Zie de sectie Voorbeeld voor volledige voorbeelden.

Gebruik

Het gebruik van de queue-uitvoerbinding is afhankelijk van de versie van het extensiepakket en de C#-modaliteit die wordt gebruikt in uw functie-app. Dit kan een van de volgende zijn:

Een geïsoleerde werkprocesklassebibliotheek gecompileerde C#-functie wordt uitgevoerd in een proces dat is geïsoleerd van de runtime.

Kies een versie om gebruiksgegevens voor de modus en versie te bekijken.

Wanneer u wilt dat de functie één bericht schrijft, kan de wachtrijuitvoerbinding worden gekoppeld aan de volgende typen:

Type Description
string De inhoud van het bericht als een tekenreeks. Gebruik dit bericht wanneer het bericht eenvoudige tekst is.
byte[] De bytes van het bericht.
JSON serialiseerbare typen Een object dat de inhoud van een JSON-bericht weergeeft. Functions probeert een eenvoudig oud CLR-objecttype (POCO) te serialiseren in JSON-gegevens.

Wanneer u wilt dat de functie meerdere berichten schrijft, kan de uitvoerbinding van de wachtrij worden gekoppeld aan de volgende typen:

Type Description
T[] waarbij T een van de typen één bericht is Een matrix met inhoud voor meerdere berichten. Elk item vertegenwoordigt één bericht.

Voor andere uitvoerscenario's maakt en gebruikt u rechtstreeks typen van Azure.Storage.Queues .

Er zijn twee opties voor het schrijven naar een wachtrij vanuit een functie met behulp van de annotatie QueueOutput :

  • Retourwaarde: Door de aantekening toe te passen op de functie zelf, wordt de retourwaarde van de functie naar de wachtrij geschreven.

  • Imperatief: Als u de berichtwaarde expliciet wilt instellen, past u de aantekening toe op een specifieke parameter van het type OutputBinding<T>, waarbij T een POJO of een systeemeigen Java-type is. Met deze configuratie schrijft het doorgeven van een waarde aan de setValue methode de waarde naar de wachtrij.

Open het item in de uitvoerwachtrij door de waarde rechtstreeks of met behulp van context.extraOutputs.set(). U kunt een tekenreeks of een JSON-serialiseerbare object gebruiken voor de nettolading van het wachtrijitem.

De uitvoer van het wachtrijbericht is beschikbaar via Push-OutputBinding de plaats waar u argumenten doorgeeft die overeenkomen met de naam die is aangewezen door de parameter van name de binding in het function.json bestand.

Er zijn twee opties voor het schrijven van uw functie naar de geconfigureerde wachtrij:

  • Retourwaarde: Stel de name eigenschap in function.json in op $return. Met deze configuratie blijft de retourwaarde van de functie behouden als een wachtrijopslagbericht.

  • Imperatief: Geef een waarde door aan de ingestelde methode van de parameter die is gedeclareerd als een Out-type . De waarde die wordt set doorgegeven, wordt behouden als een wachtrijopslagbericht.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Azure Queues. Het kan het volgende opgeven:

Als de geconfigureerde waarde zowel een exacte overeenkomst is voor één instelling als een voorvoegselovereenkomst voor andere instellingen, wordt de exacte overeenkomst gebruikt.

Connection string

Als u een verbindingsreeks wilt verkrijgen, volgt u de stappen in Toegangssleutels voor het opslagaccount beheren.

Deze verbindingsreeks moet worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de connection eigenschap van de bindingsconfiguratie.

Als de naam van de app-instelling begint met 'AzureWebJobs', kunt u hier alleen de rest van de naam opgeven. Als u bijvoorbeeld instelt op connection 'MyStorage', zoekt de Functions-runtime naar een app-instelling met de naam 'AzureWebJobsMyStorage'. Als u leeg laatconnection, gebruikt de Functions-runtime de standaardopslag-verbindingsreeks in de app-instelling met de naamAzureWebJobsStorage.

Op identiteit gebaseerde verbindingen

Als u versie 5.x of hoger van de extensie gebruikt (bundel 3.x of hoger voor non-.NET taalstacks), in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Als u een identiteit wilt gebruiken, definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toegewezen aan de connection eigenschap in de trigger- en bindingsconfiguratie.

Als u 'AzureWebJobsStorage' insteltconnection, raadpleegt u Verbinding maken voor het hosten van opslag met een identiteit. Voor alle andere verbindingen vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Wachtrijservice-URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 De gegevensvlak-URI van de wachtrijservice waarmee u verbinding maakt, met behulp van het HTTPS-schema. <https:// storage_account_name.queue.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri kan als alias worden gebruikt. Als beide formulieren worden opgegeven, wordt het queueServiceUri formulier gebruikt. Het serviceUri formulier kan niet worden gebruikt wanneer de algemene verbindingsconfiguratie moet worden gebruikt in blobs, wachtrijen en/of tabellen.

Andere eigenschappen kunnen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw wachtrij. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Queue Storage-extensie in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen
Trigger Storage Queue Data Reader, Storage Queue Data Message Processor
Uitvoerbinding Inzender voor opslagwachtrijgegevens, afzender van opslagwachtrijgegevensbericht

Uitzonderingen en retourcodes

Binding Verwijzing
Queue Wachtrijfoutcodes
Blob, Tabel, Wachtrij Foutcodes voor opslag
Blob, Tabel, Wachtrij Problemen oplossen

Volgende stappen