Azure Service Bus uitvoerbinding voor Azure Functions

Gebruik Azure Service Bus uitvoerbinding om wachtrij- of onderwerpberichten te verzenden.

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 Azure Functions Node.js ontwikkelaarshandleiding voor meer informatie over de werking van het v4-model. 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 Python ontwikkelaarshandleiding voor meer informatie.

Dit artikel ondersteunt beide programmeermodellen.

Opmerking

Go-ondersteuning is momenteel niet beschikbaar voor deze binding.

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 het .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.

Met deze code wordt het ILoggervolgende gedefinieerd en geïnitialiseerd:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

In dit voorbeeld ziet u een C#-functie die een bericht ontvangt en naar een tweede wachtrij schrijft:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

 

In dit voorbeeld wordt een HTTP-trigger met een OutputType object gebruikt om zowel een HTTP-antwoord te verzenden als het uitvoerbericht te schrijven.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Deze code definieert het meerdere uitvoertype OutputType, waaronder de definitie van de Service Bus uitvoerbinding op OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

In het volgende voorbeeld ziet u een Java-functie waarmee een bericht wordt verzonden naar een Service Bus wachtrij myqueue wanneer deze wordt geactiveerd door een HTTP-aanvraag.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

Gebruik in de Java functions runtime-bibliotheek de aantekening @QueueOutput voor functieparameters waarvan de waarde naar een Service Bus wachtrij zou worden geschreven. Het parametertype moet worden OutputBinding<T>, waarbij T een systeemeigen Java type van een oud Java-object (POJO) van een plan is.

Java functies kunnen ook schrijven naar een Service Bus onderwerp. In het volgende voorbeeld wordt de @ServiceBusTopicOutput aantekening gebruikt om de configuratie voor de uitvoerbinding te beschrijven.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

In het volgende voorbeeld ziet u een door een timer geactiveerde TypeScript-functie die elke 5 minuten een wachtrijbericht verzendt.

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

In het volgende voorbeeld ziet u een door een timer geactiveerde JavaScript-functie waarmee elke 5 minuten een wachtrijbericht wordt verzonden.

const { app, output } = require('@azure/functions');

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

In het volgende voorbeeld ziet u een Service Bus uitvoerbinding in een bestand function.json en een PowerShell-functie die gebruikmaakt van de binding.

Dit zijn de bindingsgegevens in het bestand function.json :

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Hier ziet u de PowerShell waarmee een bericht wordt gemaakt als uitvoer van de functie.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

In het volgende voorbeeld ziet u hoe u schrijft naar een Service Bus onderwerpen en Service Bus wachtrijen in Python. Het voorbeeld is afhankelijk van of u het v1 of v2 Python programmeermodel gebruikt.

In dit voorbeeld ziet u hoe u naar een Service Bus onderwerp schrijft.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="AzureServiceBusConnectionString",
                              topic_name="outTopic")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

In dit voorbeeld ziet u hoe u naar een Service Bus wachtrij schrijft.

import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_queue_output(
    arg_name="msg",
    connection="AzureServiceBusConnectionString",
    queue_name="outqueue")
def put_message(req: func.HttpRequest, msg: func.Out[str]):
    msg.set(req.get_body().decode('utf-8'))
    return 'OK'

Kenmerken

Zowel in-processals geïsoleerde werkproces C#-bibliotheken gebruiken kenmerken om de uitvoerbinding te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

Gebruik in C#-klassebibliotheken de ServiceBusOutputAttribute om de wachtrij of het onderwerp te definiëren dat is geschreven door de uitvoer.

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen met behulp van het kenmerk:

Eigenschappen Beschrijving
EntityType Hiermee stelt u het entiteitstype in als Queue voor het verzenden van berichten naar een wachtrij of Topic wanneer u berichten naar een onderwerp verzendt.
QueueOrTopicName De naam van het onderwerp of de wachtrij waar berichten naartoe moeten worden verzonden. Hiermee EntityType kunt u het doeltype instellen.
Verbinding De naam van een app-instelling of instellingsverzameling waarmee wordt aangegeven hoe u verbinding maakt met Service Bus. Zie verbindingen.

Decorateurs

Alleen aan het Python v2-programmeermodel.

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

Eigenschappen Beschrijving
arg_name De naam van de variabele die de wachtrij of het onderwerpbericht in functiecode vertegenwoordigt.
queue_name De naam van de wachtrij. Alleen instellen als wachtrijberichten worden verzonden, niet voor een onderwerp.
topic_name Naam van het onderwerp. Alleen instellen als u onderwerpberichten verzendt, niet voor een wachtrij.
connection De naam van een app-instelling of instellingsverzameling waarmee wordt aangegeven hoe u verbinding maakt met Service Bus. Zie verbindingen.

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

Aantekeningen

De ServiceBusQueueOutput en ServiceBusTopicOutput aantekeningen zijn beschikbaar om een bericht als functie-uitvoer te schrijven. De parameter die met deze aantekeningen is ingericht, moet worden gedeclareerd als een OutputBinding<T> locatie waar T het type is dat overeenkomt met het type van het bericht.

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

Configuratie

Alleen aan het programmeermodel Python v1.

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

Eigenschappen Beschrijving
queueName De naam van de wachtrij.
verbinding De naam van een app-instelling of instellingsverzameling waarmee wordt aangegeven hoe u verbinding maakt met Service Bus. Zie verbindingen.

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

Eigenschappen Beschrijving
topicName Naam van het onderwerp.
verbinding De naam van een app-instelling of instellingsverzameling waarmee wordt aangegeven hoe u verbinding maakt met Service Bus. Zie verbindingen.

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

De volgende tabel bevat informatie over de bindingsconfiguratie-eigenschappen die u instelt in het bestand function.json en het kenmerk ServiceBus.

function.json-eigenschap Beschrijving
soort Moet worden ingesteld op serviceBus. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
richting Moet worden ingesteld op out. Deze eigenschap wordt automatisch ingesteld wanneer u de trigger maakt in de Azure-portal.
naam De naam van de variabele die de wachtrij of het onderwerpbericht in functiecode vertegenwoordigt. Ingesteld op '$return' om te verwijzen naar de retourwaarde van de functie.
queueName De naam van de wachtrij. Alleen instellen als wachtrijberichten worden verzonden, niet voor een onderwerp.
topicName Naam van het onderwerp. Alleen instellen als u onderwerpberichten verzendt, niet voor een wachtrij.
verbinding De naam van een app-instelling of instellingsverzameling waarmee wordt aangegeven hoe u verbinding maakt met Service Bus. Zie verbindingen.
accessRights (alleen v1) Toegangsrechten voor de verbindingsreeks. Beschikbare waarden zijn manage en listen. De standaardwaarde ismanage, wat aangeeft dat de connection machtiging Beheren is ingesteld. Als u een verbindingsreeks gebruikt die niet beschikt over de machtiging Manage, stelt u accessRights in op 'listen'. Anders kan de Functions-runtime mislukken bij het uitvoeren van bewerkingen waarvoor beheerrechten zijn vereist. In Azure Functions versie 2.x en hoger is deze eigenschap niet beschikbaar omdat de nieuwste versie van de Service Bus SDK geen ondersteuning biedt voor beheerbewerkingen.

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

Alle C#-modaliteiten en extensieversies ondersteunen de volgende typen uitvoerparameters:

Typologie Beschrijving
System.String Gebruik wanneer het bericht om te schrijven eenvoudige tekst is. Wanneer de parameterwaarde null is wanneer de functie wordt afgesloten, wordt er geen bericht gemaakt.
byte[] Gebruiken voor het schrijven van binaire gegevensberichten. Wanneer de parameterwaarde null is wanneer de functie wordt afgesloten, wordt er geen bericht gemaakt.
Object Wanneer een bericht JSON bevat, serialiseert Functions het object in een nettolading van een JSON-bericht. Wanneer de parameterwaarde null is wanneer de functie wordt afgesloten, maakt Functions een bericht met een null-object.

Berichtspecifieke parametertypen bevatten extra metagegevens van berichten en zijn niet compatibel met JSON-serialisatie. Als gevolg hiervan is het niet mogelijk om te gebruiken ServiceBusMessage met de uitvoerbinding in het geïsoleerde model. De specifieke typen die door de uitvoerbinding worden ondersteund, zijn afhankelijk van de runtimeversie van Functions, de versie van het extensiepakket en de gebruikte C#-modaliteit.

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

Typologie Beschrijving
string Het bericht als tekenreeks. Gebruik dit bericht wanneer het bericht eenvoudige tekst is.
byte[] De bytes van het bericht.
JSON serialiseerbare typen Een object dat het bericht vertegenwoordigt. Functions probeert een normaal oud CLR-objecttype (POCO) te serialiseren in JSON-gegevens.

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

Typologie Beschrijving
T[] waarbij T een van de typen één bericht is Een matrix met meerdere berichten. Elk item vertegenwoordigt één bericht.

Voor andere uitvoerscenario's maakt en gebruikt u een ServiceBusClient met andere typen uit Azure. Messaging.ServiceBus rechtstreeks. Zie Register Azure clients voor een voorbeeld van het gebruik van afhankelijkheidsinjectie om een clienttype te maken op basis van de Azure SDK.

In Azure Functions 1.x wordt de wachtrij gemaakt als deze niet bestaat en u accessRights hebt ingesteld op manage. In Azure Functions versie 2.x en hoger moet de wachtrij of het onderwerp al bestaan. Als u een wachtrij of onderwerp opgeeft dat niet bestaat, mislukt de functie.

Gebruik de Azure Service Bus SDK in plaats van de ingebouwde uitvoerbinding.

Open het uitvoerbericht door de waarde rechtstreeks of met behulp van context.extraOutputs.set().

De uitvoer naar het Service Bus is beschikbaar via de cmdlet Push-OutputBinding waar u argumenten doorgeeft die overeenkomen met de naamparameter van de binding in het bestand function.json.

De parameter van de uitvoerfunctie moet worden gedefinieerd als func.Out[str] of func.Out[bytes]. Raadpleeg het uitvoervoorbeeld voor meer informatie. U kunt ook de Azure Service Bus SDK gebruiken in plaats van de ingebouwde uitvoerbinding.

Zie de sectie Voorbeelden voor een volledig voorbeeld.

Connecties

De connection eigenschap is een verwijzing naar een sleutel in applicatieinstellingen die een waarde teruggeeft die door de Functions-runtime wordt gebruikt om verbinding te maken met de Service Bus-instantie die door de extensie wordt gebruikt. De waarde van de connectie-eigenschapsinstelling hangt af van het type verbinding:

  • Managed identity-verbinding: De connection eigenschap wordt <CONNECTION_NAME_PREFIX> gedeeld door een groep instellingen die samen een identiteitsgebaseerde verbinding met de Service Bus definiëren. Voor meer informatie, zie Definieer identiteitsverbindingen.
  • Key Vault-referentie: De connection property-instelling geeft een Azure Key Vault-referentie terug naar de locatie waar de verbindingsreeks centraal wordt onderhouden. Voor meer informatie, zie Define Key Vault-verbindingen.
  • App Configuration referentie: De connection property-instelling geeft een Azure App Configuration-referentie terug die een verbindingsreeks of een Key Vault-referentie teruggeeft. Voor meer informatie, zie Azure App Configuration in het artikel over verbindingen.
  • Connection string: De connection property-instelling geeft de daadwerkelijke verbindingsreeks terug voor de Service Bus-instantie. Omdat de verbindingsreeks gedeelde geheime sleutels bevat, zou je moeten overwegen een managed identity-verbinding te gebruiken, waar mogelijk. Voor meer informatie, zie Verbindingen definiëren.

Voor meer informatie over bindingsverbindingen, zie Verbinding beheren in Azure Functions.

Als u een verbindingsreeks wilt verkrijgen, volgt u de stappen die worden weergegeven in De beheerreferenties ophalen. De verbindingsreeks moet voor een Service Bus-naamruimte zijn, niet beperkt tot een specifieke wachtrij of onderwerp.

Als de naam van de app-instelling begint met AzureWebJobs, kun je alleen de rest van de naam opgeven. Als u bijvoorbeeld instelt connectionMyServiceBusop , zoekt de Functions-runtime naar een app-instelling met de naam AzureWebJobsMyServiceBus. Als je leeg laatconnection, gebruikt de Functions-runtime de standaard Service Bus verbindingsreeks in de app-instelling die de naam AzureWebJobsServiceBusheeft.

Schaalmachtigingen

De Service Bus-extensie gebruikt de Service Bus Administration API (GetQueueRuntimePropertiesAsync / GetSubscriptionRuntimePropertiesAsync) om nauwkeurige berichtentellingen op te halen voor schaalbeslissingen. Deze API vereist extra rechten bovenop wat nodig is om berichten te verzenden of ontvangen:

  • SAS-verbindingsstrings: Het SAS-beleid moet het Recht op Beheren van toegang bevatten.
  • Identiteitsgebaseerde verbindingen: De identiteit moet de rol Azure Service Bus Data Owner toegewezen krijgen, of een aangepaste rol die bestaat uit Microsoft.ServiceBus/namespaces/*/read.

Wanneer de verbinding deze rechten mist, zie je geen fouten bij het opstarten. In plaats daarvan valt de extensie stilletjes terug op peek-gebaseerde berichtschatting, wat minder nauwkeurig is en kan leiden tot vertraagde of onjuiste schaalbeslissingen.

Aanbeveling

Voor productieworkloads die afhankelijk zijn van automatische schaalverbreding, neem het Manage access right (SAS) toe of wijs de rol Azure Service Bus Data Owner toe (identiteitsgebaseerde verbindingen) om nauwkeurig schaalgedrag te waarborgen. verbindingsreeks in de app-instelling die . heet AzureWebJobsServiceBus.

Uitzonderingen en retourcodes

Verbindend Verwijzing
Service Bus Service Bus foutcodes
Service Bus Service Bus Limieten

Volgende stappen

  • Last updated on