Dela via

Azure Service Bus-utdatabindning för Azure Functions

  • Artikel

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 för 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 python-funktionskoden. Mer information finns i utvecklarguiden för Python.

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

Exempel

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 in-process-funktioner 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-utdatabindningsdefinitionen för 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 Körningsbiblioteket för Java-funktioner använder du anteckningen @QueueOutput för funktionsparametrar vars värde skulle skrivas till en Service Bus-kö. Parametertypen ska vara OutputBinding<T>, där T är alla inbyggda Java-typer av en 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.json-fil 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 en Service Bus-kö i Python. Exemplet beror på om du använder python-programmeringsmodellen v1 eller v2.

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'

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:

Property 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

Gäller endast för python v2-programmeringsmodellen.

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

Property 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 definierats med hjälp av function.json finns i avsnittet Konfiguration .

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

Gäller endast 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.

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

Property 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 Portal.
riktning Måste anges till "out". Den här egenskapen anges automatiskt när du skapar utlösaren i Azure Portal.
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 anslutningssträng. 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 anslutningssträng som inte har behörigheten Hantera 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

Följande typer av utdataparametrar stöds av alla C#-modaliteter och tilläggsversioner:

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 ytterligare meddelandemetadata. 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 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 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 Registrera Azure-klienter för ett exempel på hur du använder beroendeinmatning för att skapa en klienttyp från Azure SDK.

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 .

Använd 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 miljökonfigurationen som anger hur appen ska ansluta till Service Bus. Den kan ange:

Om det konfigurerade värdet både är en exakt matchning för en enskild inställning och en prefixmatchning för andra inställningar används den exakta matchningen.

Connection string

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.

Den här anslutningssträng ska lagras i en programinställning med ett namn som matchar det värde som anges av connection egenskapen för bindningskonfigurationen.

Om namnet på appinställningen börjar med "AzureWebJobs" kan du bara ange resten av namnet. Om du till exempel anger connection "MyServiceBus" letar Functions-körningen efter en appinställning med namnet "AzureWebJobsMyServiceBus". Om du lämnar connection tomt använder Functions-körningen standardinställningen Service Bus anslutningssträng i appinställningen med namnet "AzureWebJobsServiceBus".

Identitetsbaserade anslutningar

Om du använder version 5.x eller senare av tillägget kan du i stället för att använda en anslutningssträng med en hemlighet låta appen använda en Microsoft Entra-identitet. För att göra detta definierar du inställningar under ett vanligt prefix som mappar till connection egenskapen i utlösar- och bindningskonfigurationen.

I det här läget kräver tillägget följande egenskaper:

Property Miljövariabelmall beskrivning Exempelvärde
Fullständigt kvalificerat namnområde <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Det fullständigt kvalificerade Service Bus-namnområdet. <>service_bus_namespace.servicebus.windows.net

Ytterligare egenskaper kan anges för att anpassa anslutningen. Se Vanliga egenskaper för identitetsbaserade anslutningar.

Kommentar

När du använder Azure App Configuration eller Key Vault för att ange inställningar för hanterade identitetsanslutningar bör inställningsnamn använda en giltig nyckelavgränsare, till exempel : eller / i stället __ för att säkerställa att namnen matchas korrekt.

Exempel: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace

När identitetsbaserade anslutningar finns i Azure Functions-tjänsten använder de en hanterad identitet. Den systemtilldelade identiteten används som standard, även om en användartilldelad identitet kan anges med credential egenskaperna och clientID . Observera att det inte går att konfigurera en användartilldelad identitet med ett resurs-ID. När den körs i andra sammanhang, till exempel lokal utveckling, används utvecklaridentiteten i stället, även om den kan anpassas. Se Lokal utveckling med identitetsbaserade anslutningar.

Bevilja behörighet till identiteten

Den identitet som används måste ha behörighet att utföra de avsedda åtgärderna. För de flesta Azure-tjänster innebär det att du måste tilldela en roll i Azure RBAC med hjälp av antingen inbyggda eller anpassade roller som ger dessa behörigheter.

Viktigt!

Vissa behörigheter kan exponeras av måltjänsten som inte är nödvändiga för alla kontexter. Om möjligt följer du principen om minsta behörighet och beviljar identiteten endast nödvändiga privilegier. Om appen till exempel bara behöver kunna läsa från en datakälla använder du en roll som bara har behörighet att läsa. Det skulle vara olämpligt att tilldela en roll som också tillåter skrivning till tjänsten, eftersom detta skulle vara överdriven behörighet för en läsåtgärd. På samma sätt vill du se till att rolltilldelningen endast är begränsad till de resurser som behöver läsas.

Du måste skapa en rolltilldelning som ger åtkomst till dina ämnen och köer vid körning. Hanteringsroller som Ägare räcker inte. Följande tabell visar inbyggda roller som rekommenderas när du använder Service Bus-tillägget i normal drift. Programmet kan kräva ytterligare behörigheter baserat på den kod du skriver.

Bindningstyp Exempel på inbyggda roller
Utlösare1 Azure Service Bus-datamottagare, Azure Service Bus-dataägare
Utdatabindning Azure Service Bus-datasändare

1 För att utlösa från Service Bus-ämnen måste rolltilldelningen ha ett effektivt omfång för Service Bus-prenumerationsresursen. Om bara ämnet ingår uppstår ett fel. Vissa klienter, som Azure-portalen, exponerar inte Service Bus-prenumerationsresursen som ett omfång för rolltilldelning. I sådana fall kan Azure CLI användas i stället. Mer information finns i Inbyggda Azure-roller för Azure Service Bus.

Undantag och returkoder

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

Nästa steg