Azure Service Bus utdatabindning för Azure Functions

Använd Azure Service Bus utdatabindning för att skicka kö- eller ämnesmeddelanden.

Information om konfiguration och konfigurationsinformation finns i översikten.

Viktigt!

Den här artikeln använder flikar för att stödja flera versioner av Node.js programmeringsmodellen. V4-modellen är allmänt tillgänglig och är utformad för att ha en mer flexibel och intuitiv upplevelse för JavaScript- och TypeScript-utvecklare. Mer information om hur v4-modellen fungerar finns i utvecklarguiden Azure Functions Node.js. Mer information om skillnaderna mellan v3 och v4 finns i migreringsguiden.

Azure Functions stöder två programmeringsmodeller för Python. Hur du definierar dina bindningar beror på din valda programmeringsmodell.

Med programmeringsmodellen Python v2 kan du definiera bindningar med hjälp av dekoratörer direkt i din Python funktionskod. Mer information finns i utvecklarguiden Python.

Den här artikeln stöder båda programmeringsmodellerna.

Exempel

Go-stöd finns för närvarande inte tillgängligt för denna bindning.

En C#-funktion kan skapas med något av följande C#-lägen:

  • Isolerad arbetsmodell: Kompilerad C#-funktion som körs i en arbetsprocess som är isolerad från körningen. Isolerad arbetsprocess krävs för att stödja C#-funktioner som körs på LTS- och icke-LTS-versioner .NET och .NET Framework. Tillägg för isolerade arbetsprocessfunktioner använder Microsoft.Azure.Functions.Worker.Extensions.* namnområden.
  • Processmodell: Kompilerad C#-funktion som körs i samma process som Functions-körningen. I en variant av den här modellen kan Functions köras med C#-skript, vilket främst stöds för redigering av C#-portalen. Tillägg för processfunktioner använder Microsoft.Azure.WebJobs.Extensions.* namnområden.

Viktigt!

Supporten upphör för den pågående modellen den 10 november 2026. Vi rekommenderar starkt att du migrerar dina appar till den isolerade arbetsmodellen för fullt stöd.

Den här koden definierar och initierar ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Det här exemplet visar en C#-funktion som tar emot ett meddelande och skriver det till en andra kö:

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

 

I det här exemplet används en HTTP-utlösare med ett OutputType objekt för att både skicka ett HTTP-svar och skriva utdatameddelandet.

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

Den här koden definierar den flera utdatatypen OutputType, som innehåller Service Bus utdatabindningsdefinition på OutputEvent:

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

   public HttpResponseData HttpResponse { get; set; }
}

I följande exempel visas en Java funktion som skickar ett meddelande till en Service Bus kö myqueue när den utlöses av en HTTP-begäran.

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

I Java functions runtime library använder du @QueueOutput-kommentaren på funktionsparametrar vars värde skulle skrivas till en Service Bus kö. Parametertypen ska vara OutputBinding<T>, där T är någon intern Java typ av ett plan som är gammalt Java objekt (POJO).

Java funktioner kan också skriva till ett Service Bus ämne. I följande exempel används kommentaren @ServiceBusTopicOutput för att beskriva konfigurationen för utdatabindningen.

@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();

    }

I följande exempel visas en timerutlöst TypeScript-funktion som skickar ett kömeddelande var femte minut.

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

Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas en timerutlöst JavaScript-funktion som skickar ett kömeddelande var femte minut.

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

Om du vill mata ut flera meddelanden returnerar du en matris i stället för ett enda objekt. Till exempel:

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

I följande exempel visas en Service Bus utdatabindning i en function.jsonfil och en PowerShell-funktion som använder bindningen.

Här är bindningsdata i filen function.json :

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

Här är PowerShell som skapar ett meddelande som funktionens utdata.

param($QueueItem, $TriggerMetadata) 

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

I följande exempel visas hur du skriver ut till ett Service Bus ämnen och Service Bus köer i Python. Exemplet beror på om du använder programmeringsmodellen v1 eller v2 Python.

Det här exemplet visar hur du skriver ut till ett Service Bus ämne.

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'

Det här exemplet visar hur du skriver ut till en Service Bus kö.

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'

Attribut

C#-bibliotek i både processprocess och isolerad arbetsprocess använder attribut för att definiera utdatabindningen. C#-skriptet använder i stället en function.json konfigurationsfil enligt beskrivningen i C#-skriptguiden.

I C#-klassbibliotek använder du ServiceBusOutputAttribute för att definiera kön eller ämnet som skrivs till av utdata.

I följande tabell förklaras de egenskaper som du kan ange med hjälp av attributet:

Fastighet beskrivning
EntityType Anger entitetstypen som antingen Queue för att skicka meddelanden till en kö eller Topic när meddelanden skickas till ett ämne.
QueueOrTopicName Namnet på ämnet eller kön som meddelanden ska skickas till. Använd EntityType för att ange måltypen.
Anslutning Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Service Bus. Se Anslutningar.

Dekoratörer

Applies endast till programmeringsmodellen Python v2.

För Python v2-funktioner som definierats med hjälp av en dekoratör, följande egenskaper på service_bus_topic_output:

Fastighet beskrivning
arg_name Namnet på variabeln som representerar kön eller ämnesmeddelandet i funktionskoden.
queue_name Namn på kön. Ange endast om du skickar kömeddelanden, inte för ett ämne.
topic_name Namnet på ämnet. Ange endast om du skickar ämnesmeddelanden, inte för en kö.
connection Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Service Bus. Se Anslutningar.

Information om Python funktioner som definieras med hjälp av function.json finns i avsnittet Configuration.

Kommentarer

Anteckningarna ServiceBusQueueOutput och ServiceBusTopicOutput är tillgängliga för att skriva ett meddelande som ett funktionsutdata. Parametern som är dekorerad med dessa anteckningar måste deklareras som en OutputBinding<T> där T är den typ som motsvarar meddelandets typ.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Konfiguration

Applies endast till programmeringsmodellen Python v1.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.serviceBusQueue() till metoden.

Fastighet beskrivning
queueName Namn på kön.
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Service Bus. Se Anslutningar.

I följande tabell förklaras de egenskaper som du kan ange för objektet options som skickas output.serviceBusTopic() till metoden.

Fastighet beskrivning
topicName Namnet på ämnet.
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Service Bus. Se Anslutningar.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

I följande tabell förklaras de bindningskonfigurationsegenskaper som du anger i function.json-filen och ServiceBus attributet.

function.json egenskap beskrivning
typ Måste anges till serviceBus. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure portalen.
riktning Måste anges till out. Den här egenskapen anges automatiskt när du skapar utlösaren i Azure portalen.
Namn Namnet på variabeln som representerar kön eller ämnesmeddelandet i funktionskoden. Ange till "$return" för att referera till funktionens returvärde.
queueName Namn på kön. Ange endast om du skickar kömeddelanden, inte för ett ämne.
topicName Namnet på ämnet. Ange endast om du skickar ämnesmeddelanden, inte för en kö.
samband Namnet på en appinställning eller inställningssamling som anger hur du ansluter till Service Bus. Se Anslutningar.
accessRights (endast v1) Åtkomsträttigheter för reťazec pripojenia. Tillgängliga värden är manage och listen. Standardvärdet är manage, vilket anger att connection har behörigheten Hantera . Om du använder en reťazec pripojenia som inte har behörigheten Manage anger du accessRights till "lyssna". Annars kan Functions-körningen misslyckas med att utföra åtgärder som kräver hanteringsrättigheter. I Azure Functions version 2.x och senare är den här egenskapen inte tillgänglig eftersom den senaste versionen av Service Bus SDK inte stöder hanteringsåtgärder.

När du utvecklar lokalt lägger du till dina programinställningar i den local.settings.json filen i Values samlingen.

Se avsnittet Exempel för fullständiga exempel.

Förbrukning

Alla C#-modaliteter och tilläggsversioner stöder följande typer av utdataparametrar:

Typ beskrivning
System.String Använd när meddelandet som ska skrivas är enkel text. När parametervärdet är null när funktionen avslutas skapar Functions inte något meddelande.
byte[] Används för att skriva binära datameddelanden. När parametervärdet är null när funktionen avslutas skapar Functions inte något meddelande.
Objekt När ett meddelande innehåller JSON serialiserar Functions objektet till en nyttolast för JSON-meddelanden. När parametervärdet är null när funktionen avslutas skapar Functions ett meddelande med ett null-objekt.

Meddelandespecifika parametertyper innehåller extra meddelandemetadata och är inte kompatibla med JSON-serialisering. Därför går det inte att använda ServiceBusMessage med utdatabindningen i den isolerade modellen. De specifika typer som stöds av utdatabindningen beror på functions-körningsversionen, tilläggspaketversionen och den C#-modalitet som används.

När du vill att funktionen ska skriva ett enda meddelande kan den Service Bus utdatabindningen binda till följande typer:

Typ beskrivning
string Meddelandet som en sträng. Använd när meddelandet är enkel text.
byte[] Byte för meddelandet.
JSON-serialiserbara typer Ett objekt som representerar meddelandet. Functions försöker serialisera en vanlig CLR-objekttyp (POCO) till JSON-data.

När du vill att funktionen ska skriva flera meddelanden kan den Service Bus utdatabindningen binda till följande typer:

Typ beskrivning
T[] där T är en av de enskilda meddelandetyperna En matris som innehåller flera meddelanden. Varje post representerar ett meddelande.

För andra utdatascenarier skapar och använder du en ServiceBusClient med andra typer från Azure. Messaging.ServiceBus direkt. Se Register Azure-klienter för ett exempel på hur du använder beroendeinmatning för att skapa en klienttyp från Azure SDKs.

I Azure Functions 1.x skapar körningen kön om den inte finns och du har angett accessRights till manage. I Azure Functions version 2.x och senare måste kön eller ämnet redan finnas. Om du anger en kö eller ett ämne som inte finns misslyckas funktionen.

Använd Azure Service Bus SDK i stället för den inbyggda utdatabindningen.

Få åtkomst till utdatameddelandet genom att returnera värdet direkt eller med hjälp av context.extraOutputs.set().

Utdata till Service Bus är tillgängliga via cmdleten Push-OutputBinding där du skickar argument som matchar namnet som anges av bindningens namnparameter i filen function.json.

Utdatafunktionsparametern måste definieras som func.Out[str] eller func.Out[bytes]. Mer information finns i utdataexemplet . Du kan också använda Azure Service Bus SDK i stället för den inbyggda utdatabindningen.

Ett fullständigt exempel finns i avsnittet exempel.

anslutningar

Egenskapen connection är en referens till en nyckel i applikationsinställningar som returnerar ett värde som används av Functions-runtimen för att ansluta till Service Bus-instansen som används av tillägget. Värdet på anslutningsegenskapsinställningen beror på typen av anslutning:

  • Managed identity-anslutning: Egenskapen connection<CONNECTION_NAME_PREFIX> delas av en grupp inställningar som tillsammans definierar en identitetsbaserad anslutning till Service Bus. För mer information, se Definiera identitetskopplingar.
  • Key Vault-referens: Egendomsinställningen connection returnerar en Azure Key Vault-referens till platsen där reťazec pripojenia underhålls centralt. För mer information, se Definiera Key Vault-anslutningar.
  • App Configuration Reference: Egenskapsinställningen connection returnerar en Azure App Configuration-referens som returnerar en reťazec pripojenia eller en Key Vault-referens. För mer information, se Azure App Configuration i artikeln om anslutningar.
  • Connection string: Egenskapsinställningen connection returnerar den faktiska reťazec pripojenia för Service Bus-instansen. Eftersom reťazec pripojenia innehåller delade hemliga nycklar bör du överväga att använda en managed identity-anslutning när det är möjligt. För mer information, se Definiera kopplingar.

För att lära dig mer om bindningsanslutningar, se Hantera anslutning i Azure Functions.

För att få en anslutningssträng följer du stegen som visas i Hämta autentiseringsuppgifterna för hantering. Anslutningssträng måste vara för ett Service Bus-namnområde, inte begränsat till en specifik kö eller ett visst ämne.

Om appens namn börjar med AzureWebJobs, kan du ange endast resten av namnet. Om du till exempel anger connection till MyServiceBussöker Functions-körningen efter en appinställning med namnet AzureWebJobsMyServiceBus. Om du lämnar connection det tomt använder Functions-runtimen standardinställningen Service Bus reťazec pripojenia i appinställningen som heter AzureWebJobsServiceBus.

Skalningsbehörigheter

Service Bus-tillägget använder Service Bus Administration API (GetQueueRuntimePropertiesAsync / GetSubscriptionRuntimePropertiesAsync) för att hämta exakta meddelanderäkningar för skalningsbeslut. Detta API kräver ytterligare behörigheter utöver vad som krävs för att skicka eller ta emot meddelanden:

  • SAS-anslutningssträngar: SAS-policyn måste inkludera rätten Hantera åtkomst.
  • Identitetsbaserade anslutningar: Identiteten måste tilldelas rollen Azure Service Bus Data Owner, eller en anpassad roll som inkluderar Microsoft.ServiceBus/namespaces/*/read.

När anslutningen saknar dessa behörigheter ser du inga fel vid uppstart. Istället faller tillägget tyst tillbaka på att använda peek-baserad meddelandeuppskattning, vilket är mindre exakt och kan leda till fördröjda eller felaktiga skalningsbeslut.

Tips/Råd

För produktionsarbetsbelastningar som är beroende av automatisk skalning, inkludera behörigheten Hantera åtkomst (SAS) eller tilldela rollen Azure Service Bus Data Owner (identitetsbaserade anslutningar) för att säkerställa korrekt skalbeteende. reťazec pripojenia i app-inställningen som heter AzureWebJobsServiceBus.

Undantag och returkoder

Bindning Referens
Service Bus Service Bus felkoder
Service Bus Service Bus gränser

Nästa steg

  • Last updated on