Výstupní vazba služby Azure Service Bus pro Azure Functions

  • Článek

Výstupní vazba služby Azure Service Bus slouží k odesílání zpráv fronty nebo tématu.

Informace o nastavení a konfiguraci najdete v přehledu.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Azure Functions podporuje dva programovací modely pro Python. Způsob, jakým definujete vazby, závisí na zvoleném programovacím modelu.

Programovací model Pythonu v2 umožňuje definovat vazby pomocí dekorátorů přímo v kódu funkce Pythonu. Další informace najdete v příručce pro vývojáře Pythonu.

Tento článek podporuje oba programovací modely.

Příklad

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Důležité

Podpora modelu v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovního procesu pro plnou podporu.

Tento kód definuje a inicializuje ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Tento příklad ukazuje funkci jazyka C#, která obdrží zprávu a zapíše ji do druhé fronty:

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

 

Tento příklad používá trigger HTTP s OutputType objektem k odeslání odpovědi HTTP i zápisu výstupní zprávy.

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

Tento kód definuje více výstupních typů OutputType, které zahrnují definici výstupní vazby služby Service Bus na OutputEvent:

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

   public HttpResponseData HttpResponse { get; set; }
}

Následující příklad ukazuje funkci Java, která odesílá zprávu do fronty myqueue služby Service Bus při aktivaci požadavkem HTTP.

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

V knihovně modulu runtime funkcí Java použijte poznámku @QueueOutput k parametrům funkce, jejichž hodnota by byla zapsána do fronty služby Service Bus. Typ parametru by měl být OutputBinding<T>, kde T je jakýkoli nativní typ Javy POJO.

Funkce Java můžou také zapisovat do tématu služby Service Bus. Následující příklad používá poznámku @ServiceBusTopicOutput k popisu konfigurace výstupní vazby.

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

    }

Následující příklad ukazuje časovač aktivovanou funkci TypeScript, která každých 5 minut odesílá zprávu fronty.

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

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje časovač aktivovanou javascriptovou funkci , která každých 5 minut odesílá zprávu fronty.

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

Pokud chcete vytvořit výstup více zpráv, vraťte místo jednoho objektu pole. Příklad:

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

Následující příklad ukazuje výstupní vazbu služby Service Bus v souboru function.json a funkci PowerShellu, která používá vazbu.

Tady jsou data vazby v souboru function.json :

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

Tady je PowerShell, který vytvoří zprávu jako výstup funkce.

param($QueueItem, $TriggerMetadata) 

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

Následující příklad ukazuje, jak zapisovat do fronty Service Bus v Pythonu. Tento příklad závisí na tom, jestli používáte programovací model v1 nebo v2 Pythonu.

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'

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají atributy k definování výstupní vazby. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

V knihovnách tříd jazyka C# použijte ServiceBusOutputAttribute k definování fronty nebo tématu zapsaného výstupem.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit pomocí atributu:

Vlastnost Popis
EntityType Nastaví typ entity buď Queue pro odesílání zpráv do fronty, nebo Topic při odesílání zpráv do tématu.
QueueOrTopicName Název tématu nebo fronty pro odesílání zpráv. Slouží EntityType k nastavení cílového typu.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Service Bus. Viz Připojení iony.

Dekoratéry

Platí pouze pro programovací model Pythonu v2.

Pro funkce Pythonu v2 definované pomocí dekorátoru následující vlastnosti:service_bus_topic_output

Vlastnost Popis
arg_name Název proměnné, která představuje zprávu fronty nebo tématu v kódu funkce.
queue_name Název fronty Nastavit pouze v případě odesílání zpráv fronty, nikoli pro téma.
topic_name Název tématu Nastavit pouze v případě odesílání zpráv tématu, ne pro frontu.
connection Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Service Bus. Viz Připojení iony.

Informace o funkcích Pythonu definovaných pomocí function.json najdete v části Konfigurace .

Poznámky

Poznámky ServiceBusQueueOutput a ServiceBusTopicOutput poznámky jsou k dispozici pro zápis zprávy jako výstup funkce. Parametr zdobený těmito poznámkami musí být deklarován jako OutputBinding<T> typ, který T odpovídá typu zprávy.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Konfigurace

Platí pouze pro programovací model Pythonu v1.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.serviceBusQueue() .

Vlastnost Popis
queueName Název fronty
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Service Bus. Viz Připojení iony.

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.serviceBusTopic() .

Vlastnost Popis
topicName Název tématu
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Service Bus. Viz Připojení iony.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json a atributu ServiceBus .

vlastnost function.json Popis
type Musí být nastavená na "serviceBus". Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
direction Musí být nastavená na "out". Tato vlastnost se nastaví automaticky při vytváření triggeru na webu Azure Portal.
Jméno Název proměnné, která představuje zprávu fronty nebo tématu v kódu funkce. Pokud chcete odkazovat na návratnou hodnotu funkce, nastavte hodnotu $return.
queueName Název fronty Nastavit pouze v případě odesílání zpráv fronty, nikoli pro téma.
topicName Název tématu Nastavit pouze v případě odesílání zpráv tématu, ne pro frontu.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Service Bus. Viz Připojení iony.
accessRights (pouze v1) Přístupová práva pro připojovací řetězec Dostupné hodnoty jsou manage a listen. Výchozí hodnota je manage, což označuje, že connection má oprávnění Spravovat . Pokud používáte připojovací řetězec, který nemá oprávnění Spravovat, nastavte accessRights na "listen". Jinak může modul runtime služby Functions selhat při pokusu o provádění operací, které vyžadují práva pro správu. Ve službě Azure Functions verze 2.x a vyšší není tato vlastnost dostupná, protože nejnovější verze sady Service Bus SDK nepodporuje operace správy.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Kompletní příklady najdete v části Příklad.

Využití

Všechny způsoby a verze rozšíření jazyka C# podporují následující typy výstupních parametrů:

Typ Popis
System.string Používá se, když je zpráva určená k zápisu jednoduchého textu. Pokud je hodnota parametru při ukončení funkce null, funkce nevytvoří zprávu.
byte[] Slouží k zápisu binárních datových zpráv. Pokud je hodnota parametru při ukončení funkce null, funkce nevytvoří zprávu.
Objekt Pokud zpráva obsahuje JSON, funkce serializuje objekt do datové části zprávy JSON. Pokud je hodnota parametru při ukončení funkce null, vytvoří funkce zprávu s objektem null.

Typy parametrů specifických pro zasílání zpráv obsahují další metadata zpráv. Konkrétní typy podporované výstupní vazbou závisí na verzi modulu runtime služby Functions, verzi balíčku rozšíření a použitém režimu jazyka C#.

Pokud chcete, aby funkce zapisuje jednu zprávu, výstupní vazba služby Service Bus může svázat s následujícími typy:

Typ Popis
string Zpráva jako řetězec. Používá se, když je zpráva jednoduchá.
byte[] Bajty zprávy.
Serializovatelné typy JSON Objekt představující zprávu. Funkce se pokusí serializovat prostý starý typ objektu CLR (POCO) do dat JSON.

Pokud chcete, aby funkce zapisuje více zpráv, výstupní vazba služby Service Bus může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single message types Pole obsahující více zpráv. Každá položka představuje jednu zprávu.

V případě jiných výstupních scénářů můžete přímo vytvářet a používat typy z Azure.Messaging.ServiceBus .

V Azure Functions 1.x modul runtime vytvoří frontu, pokud neexistuje a máte nastavenou accessRights hodnotu manage. Ve službě Azure Functions verze 2.x a vyšší musí fronta nebo téma již existovat; Pokud zadáte frontu nebo téma, které neexistuje, funkce selže.

Místo předdefinované výstupní vazby používejte sadu SDK služby Azure Service Bus.

Přístup k výstupní zprávě vrácením hodnoty přímo nebo pomocí context.extraOutputs.set().

Výstup služby Service Bus je k dispozici prostřednictvím Push-OutputBinding rutiny, kde předáte argumenty, které odpovídají názvu určenému parametrem názvu vazby v souboru function.json .

Místo předdefinované výstupní vazby používejte sadu SDK služby Azure Service Bus.

Úplný příklad najdete v části s příklady.

Propojení

Vlastnost connection je odkazem na konfiguraci prostředí, která určuje, jak se má aplikace připojit ke službě Service Bus. Může zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Pokud chcete získat připojovací řetězec, postupujte podle kroků uvedených v části Získání přihlašovacích údajů pro správu. Připojovací řetězec musí být pro obor názvů služby Service Bus, nikoli pouze pro konkrétní frontu nebo téma.

Tato připojovací řetězec by měla být uložena v nastavení aplikace s názvem, který connection odpovídá hodnotě určené vlastností konfigurace vazby.

Pokud název nastavení aplikace začíná na AzureWebJobs, můžete zadat pouze zbytek názvu. Pokud například nastavíte connection "MyServiceBus", modul runtime služby Functions vyhledá nastavení aplikace s názvem AzureWebJobsMyServiceBus. Pokud necháte connection prázdný, modul runtime Služby Functions použije výchozí připojovací řetězec Service Bus v nastavení aplikace s názvem AzureWebJobsServiceBus.

Připojení založená na identitách

Pokud používáte rozšíření verze 5.x nebo vyšší, můžete místo použití připojovací řetězec s tajným kódem použít aplikaci identitu Microsoft Entra. K tomu byste definovali nastavení pod běžnou předponou, která se mapuje na connection vlastnost v konfiguraci triggeru a vazby.

V tomto režimu rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Plně kvalifikovaný obor názvů <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Plně kvalifikovaný obor názvů služby Service Bus. <>service_bus_namespace.servicebus.windows.net

Pro přizpůsobení připojení je možné nastavit další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Poznámka:

Při použití konfigurace Aplikace Azure nebo služby Key Vault k poskytnutí nastavení pro připojení spravované identity by názvy nastavení měly používat platný oddělovač klíčů, například : místo /__ názvu, aby se názvy správně přeložily.

Například <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Budete muset vytvořit přiřazení role, které poskytuje přístup k vašim tématům a frontám za běhu. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Service Bus v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí
Aktivační událost1 Příjemce dat služby Azure Service Bus, vlastník dat služby Azure Service Bus
Výstupní vazba Odesílatel dat služby Azure Service Bus

1 Pro aktivaci z témat služby Service Bus musí přiřazení role mít efektivní rozsah nad prostředkem předplatného služby Service Bus. Pokud je zahrnuto pouze téma, dojde k chybě. Někteří klienti, například web Azure Portal, nezpřístupňují prostředek předplatného služby Service Bus jako obor pro přiřazení role. V takových případech se místo toho může použít Azure CLI. Další informace najdete v tématu Předdefinované role Azure pro Azure Service Bus.

Výjimky a návratové kódy

Vazba Reference
Service Bus Kódy chyb služby Service Bus
Service Bus Omezení služby Service Bus

Další kroky