Azure Service Bus-uitvoerbinding voor Azure Functions

  • Artikel

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

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 die een bericht verzendt 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 Runtime-bibliotheek van Java-functies de @QueueOutput aantekening voor functieparameters waarvan de waarde naar een Service Bus-wachtrij wordt geschreven. Het parametertype moet zijn OutputBinding<T>, waarbij T elk systeemeigen Java-type van een POJO 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 function.json-bestand 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-wachtrij in Python. 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.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    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 door de uitvoer is geschreven.

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 die aangeeft hoe verbinding moet worden gemaakt met Service Bus. Zie Verbinding maken ions.

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 service_bus_topic_outputvolgende:

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 die aangeeft hoe verbinding moet worden gemaakt met Service Bus. Zie Verbinding maken ions.

Zie de sectie Configuratie 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

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.serviceBusQueue() methode is doorgegeven.

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

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 die aangeeft hoe verbinding moet worden gemaakt met Service Bus. Zie Verbinding maken ions.

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
type Moet zijn ingesteld op 'serviceBus'. 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 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 die aangeeft hoe verbinding moet worden gemaakt met Service Bus. Zie Verbinding maken ions.
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 waarvoor de machtiging Beheren niet is ingesteld, stelt u 'listen' inaccessRights. 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

De volgende typen uitvoerparameters worden ondersteund door alle C#-modaliteiten en extensieversies:

Type Description
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 aanvullende metagegevens van berichten. 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:

Type Description
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:

Type Description
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 rechtstreeks typen van Azure.Messaging.ServiceBus .

In Azure Functions 1.x maakt de runtime de wachtrij als deze niet bestaat en u hebt ingesteld op accessRightsmanage. 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().

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

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

Zie de sectie Voorbeelden voor een volledig voorbeeld.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met Service Bus. 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 die worden weergegeven in De beheerreferenties ophalen. De verbindingsreeks moet voor een Service Bus-naamruimte zijn, niet beperkt tot een specifieke wachtrij of onderwerp.

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 alleen de rest van de naam opgeven. Als u bijvoorbeeld instelt op connection 'MyServiceBus', zoekt de Functions-runtime naar een app-instelling met de naam 'AzureWebJobsMyServiceBus'. Als u leeg laatconnection, gebruikt de Functions-runtime de standaardService Bus-verbindingsreeks in de app-instelling met de naam AzureWebJobsServiceBus.

Op identiteit gebaseerde verbindingen

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

In deze modus vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Volledig gekwalificeerde naamruimte <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace De volledig gekwalificeerde Service Bus-naamruimte. <>service_bus_namespace.servicebus.windows.net

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

Notitie

Wanneer u Azure-app Configuratie of Key Vault gebruikt om instellingen voor beheerde identiteitverbindingen te bieden, moeten instellingsnamen een geldig sleutelscheidingsteken gebruiken, zoals : of / in plaats van de __ sleutelkluis om ervoor te zorgen dat namen correct worden omgezet.

Bijvoorbeeld: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

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 onderwerpen en wachtrijen. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Service Bus-extensie in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen
Trigger1 Azure Service Bus-gegevensontvanger, Azure Service Bus-gegevenseigenaar
Uitvoerbinding Azure Service Bus-gegevenszender

1 Voor triggering vanuit Service Bus-onderwerpen moet de roltoewijzing een effectief bereik hebben voor de Service Bus-abonnementsresource. Als alleen het onderwerp is opgenomen, treedt er een fout op. Sommige clients, zoals de Azure Portal, maken de Service Bus-abonnementsresource niet beschikbaar als een bereik voor roltoewijzing. In dergelijke gevallen kan de Azure CLI worden gebruikt. Zie ingebouwde Azure-rollen voor Azure Service Bus voor meer informatie.

Uitzonderingen en retourcodes

Binding Verwijzing
Service Bus Service Bus-foutcodes
Service Bus Service Bus-limieten

Volgende stappen