Výstupní vazba služby Azure Service Bus pro Azure Functions
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í. |
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í. |
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í. |
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í. |
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í. |
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.
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 .
Ú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:
- Název nastavení aplikace obsahující připojovací řetězec
- Název sdílené předpony pro více nastavení aplikace, společně definující připojení založené na identitě.
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é Namespace | <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 |