Azure Service Bus-Trigger für Azure Functions

  • Artikel

Verwenden Sie den Service Bus-Trigger, um auf Nachrichten von einer Service Bus-Warteschlange oder einem Thema zu reagieren. Beginnend mit der Erweiterungsversion 3.1.0 können Sie Trigger für sitzungsfähige Warteschlangen oder Themen verwenden.

Informationen zu Setup- und Konfigurationsdetails finden Sie in der Übersicht.

Skalierungsentscheidungen von Service Bus für Verbrauchs- und Premium-Pläne werden basierend auf zielbasierter Skalierung getroffen. Weitere Informationen finden Sie unter Zielbasierte Skalierung.

Wichtig

In diesem Artikel werden Registerkarten verwendet, um mehrere Versionen des Node.js-Programmiermodells zu unterstützen. Das v4-Modell ist allgemein verfügbar und bietet JavaScript- und TypeScript-Entwicklern eine flexiblere und intuitivere Erfahrung. Weitere Informationen zur Funktionsweise des v4-Modells finden Sie im Azure Functions Node.js-Entwicklerhandbuch. Weitere Informationen zu den Unterschieden zwischen v3 und v4 finden Sie im Migrationshandbuch.

Azure Functions unterstützt zwei Programmiermodelle für Python. Wie Sie Ihre Bindung definieren, hängt vom gewählten Python-Programmiermodell ab.

Mit dem Python v2-Programmiermodell können Sie Bindungen mithilfe von Decorators direkt im Python-Funktionscode definieren. Weitere Informationen finden Sie im Python Developer-Leitfaden.

In diesem Artikel werden beide Programmiermodelle unterstützt.

Beispiel

Eine C#-Funktion kann mit einem der folgenden C#-Modi erstellt werden:

  • Isoliertes Workermodell: Kompilierte C#-Funktion, die in einem Workerprozess ausgeführt wird, der von der Runtime isoliert ist. Ein isolierter Workerprozess ist erforderlich, um C#-Funktionen zu unterstützen, die in LTS- und Nicht-LTS-Versionen von .NET und .NET Framework ausgeführt werden. Erweiterungen für isolierte Workerprozessfunktionen verwenden Microsoft.Azure.Functions.Worker.Extensions.*-Namespaces.
  • In-Process-Modell: Kompilierte C#-Funktion, die im gleichen Prozess wie die Functions-Runtime ausgeführt wird. In einer Variante dieses Modells kann Functions mithilfe von C#-Skripts ausgeführt werden. Dies wird hauptsächlich für die Bearbeitung im C#-Portal unterstützt. Erweiterungen für In-Process-Funktionen verwenden Microsoft.Azure.WebJobs.Extensions.*-Namespaces.

Wichtig

Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Es wird dringend empfohlen, Ihre Apps zum isolierten Workermodell zu migrieren, um den vollständigen Support zu ermöglichen.

Mit diesem Code wird ILogger definiert und initialisiert:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

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

Dieses Beispiel zeigt eine C#-Funktion, die eine einzelne Service Bus-Warteschlangennachricht empfängt und in die Protokolle schreibt:

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

Dieses Beispiel zeigt eine C#-Funktion, die mehrere Service Bus-Warteschlangennachrichten in einem einzelnen Batch empfängt und in die Protokolle schreibt:

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

Dieses Beispiel zeigt eine C#-Funktion, die mehrere Service Bus-Warteschlangennachrichten empfängt, in die Protokolle schreibt und dann die Nachricht als abgeschlossen festlegt.

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

Die folgende Java-Funktion verwendet die @ServiceBusQueueTrigger-Anmerkung aus der @ServiceBusQueueTrigger, um die Konfiguration für einen Service Bus-Warteschlangentrigger zu beschreiben. Die Funktion ruft die Nachricht aus der Warteschlange ab und fügt sie den Protokollen hinzu.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

Java-Funktionen können auch dadurch ausgelöst werden, dass eine Nachricht einem Service Bus-Thema hinzugefügt wird. Im folgenden Beispiel wird die @ServiceBusTopicTrigger-Anmerkung verwendet, um die Triggerkonfiguration zu beschreiben.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

Das folgende Beispiel zeigt eine TypeScript-Funktion des Service Bus-Triggers. Die Funktion liest Nachrichtenmetadaten und protokolliert eine Service Bus-Warteschlangennachricht.

import { app, InvocationContext } from '@azure/functions';

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

Das folgende Beispiel zeigt eine JavaScript-Funktion des Service Bus-Triggers. Die Funktion liest Nachrichtenmetadaten und protokolliert eine Service Bus-Warteschlangennachricht.

const { app } = require('@azure/functions');

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

Das folgende Beispiel zeigt eine Service Bus-Triggerbindung in einer Datei function.json sowie eine PowerShell-Funktion, die die Bindung verwendet.

Bindungsdaten in der Datei function.json:

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Dies ist die Funktion, die ausgeführt wird, wenn eine Service Bus-Nachricht gesendet wird.

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

Das folgende Beispiel zeigt, wie Sie eine Service Bus-Warteschlangennachricht mittels Trigger lesen. Das Beispiel hängt davon ab, ob Sie das Python-Programmiermodell v1 oder v2 verwenden.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

Das folgende Beispiel zeigt, wie ein Service Bus-Warteschlangenthema über einen Trigger gelesen wird.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

Attributes

Sowohl von C#-Bibliotheken vom Typ In-Process als auch von C#-Bibliotheken vom Typ Isolierter Workerprozess wird das ServiceBusTriggerAttribute-Attribut verwendet, um die Funktionstrigger zu definieren. Das C#-Skript verwendet stattdessen eine Konfigurationsdatei function.json, wie im C#-Skript-Handbuch beschrieben.

In der folgenden Tabelle werden die Eigenschaften erläutert, die mithilfe des Triggerattributs festgelegt werden können:

Eigenschaft BESCHREIBUNG
QueueName Der Name der zu überwachenden Warteschlange. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).
TopicName Der Name des zu überwachenden Themas. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
SubscriptionName Der Name des zu überwachenden Abonnements. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
Connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Service Bus hergestellt wird Siehe Verbindungen.
IsBatched Nachrichten werden in Batches übermittelt. Es ist ein Array oder ein Sammlungstyp erforderlich.
IsSessionsEnabled true, wenn eine Verbindung mit einer true Warteschlange oder einem Abonnement hergestellt wird. Andernfalls false, wobei es sich um den Standardwert handelt.
AutoCompleteMessages true wenn der Trigger die Nachricht nach einem erfolgreichen Aufruf automatisch abschließen soll. false sollte dies nicht erfolgen, z. B. wenn Sie die Meldungsabrechnung im Code behandeln. Wenn nicht explizit festgelegt, basiert das Verhalten auf der Konfiguration in host.json.autoCompleteMessages

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Decorator-Elemente

Gilt nur für das Python v2-Programmiermodell.

Für Python v2-Funktionen, die mithilfe eines Decorators definiert wurden, gelten die folgenden Eigenschaften für service_bus_queue_trigger:

Eigenschaft BESCHREIBUNG
arg_name Der Name der Variablen, die die Warteschlangen- oder Themanachricht im Funktionscode darstellt.
queue_name Der Name der zu überwachenden Warteschlange. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Service Bus hergestellt wird Siehe Verbindungen.

Informationen zu Python-Funktionen, die mithilfe von function.json definiert wurden, finden Sie im Abschnitt Konfiguration.

Anmerkungen

Mit der ServiceBusQueueTrigger-Anmerkung können Sie eine Funktion erstellen, die ausgeführt wird, wenn eine Service Bus-Warteschlangennachricht erstellt wird. Zu den verfügbaren Konfigurationsoptionen gehören die folgenden Eigenschaften:

Eigenschaft Beschreibung
name Der Name der Variablen, die die Warteschlangen- oder Themanachricht im Funktionscode darstellt.
queueName Der Name der zu überwachenden Warteschlange. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).
topicName Der Name des zu überwachenden Themas. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
subscriptionName Der Name des zu überwachenden Abonnements. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Service Bus hergestellt wird Siehe Verbindungen.

Mit der ServiceBusTopicTrigger-Anmerkung können Sie ein Thema und ein Abonnement festlegen, um zu bestimmen, welche Daten die Funktion auslösen.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Weitere Details finden Sie unter Trigger – Beispiel.

Konfiguration

Gilt nur für das Python v1-Programmiermodell.

In der folgenden Tabelle werden die Eigenschaften erläutert, die Sie für das options-Objekt festlegen können, das an die Methoden app.serviceBusQueue() oder app.serviceBusTopic() übergeben wird.

Eigenschaft BESCHREIBUNG
queueName Der Name der zu überwachenden Warteschlange. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).
topicName Der Name des zu überwachenden Themas. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
subscriptionName Der Name des zu überwachenden Abonnements. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Service Bus hergestellt wird Siehe Verbindungen.
accessRights Zugriffsberechtigungen für die Verbindungszeichenfolge. Verfügbare Werte sind manage und listen. Die Standardeinstellung ist manage, d.h. heißt, dass die connection die Berechtigung manage hat. Wenn Sie eine Verbindungszeichenfolge verwenden, die nicht über die Berechtigung Manage verfügt, legen Sie accessRights auf „listen“ fest. Andernfalls versucht die Functions-Runtime ggf. erfolglos Vorgänge auszuführen, die Verwaltungsrechte erfordern. In Version 2.x und höheren Versionen von Azure Functions ist diese Eigenschaft nicht verfügbar, da die aktuelle Version des Service Bus SDK Verwaltungsvorgänge nicht unterstützt.
isSessionsEnabled true, wenn eine Verbindung mit einer true Warteschlange oder einem Abonnement hergestellt wird. Andernfalls false, wobei es sich um den Standardwert handelt.
autoComplete Muss für Funktionen, die nicht C# sind, true sein. Das bedeutet, dass der Trigger entweder automatisch nach der Verarbeitung abgeschlossen wird oder der Funktionscode manuell abgeschlossen wird.

Wenn der Wert auf true festgelegt ist, wird die Nachricht automatisch durch den Triggervorgang abgeschlossen, sofern die Ausführung der Funktion erfolgreich war, andernfalls wird die Meldung verworfen.

Ausnahmen führen in der Funktion dazu, dass die Runtime abandonAsync im Hintergrund aufruft. Wenn keine Ausnahme auftritt, wird completeAsync im Hintergrund aufgerufen. Diese Eigenschaft ist nur in Azure Functions ab Version 2.x und höher verfügbar.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json festlegen.

function.json-Eigenschaft BESCHREIBUNG
type Muss auf serviceBusTrigger festgelegt sein. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
direction Muss auf „in“ festgelegt werden. Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.
name Der Name der Variablen, die die Warteschlangen- oder Themanachricht im Funktionscode darstellt.
queueName Der Name der zu überwachenden Warteschlange. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).
topicName Der Name des zu überwachenden Themas. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
subscriptionName Der Name des zu überwachenden Abonnements. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).
connection Der Name einer App-Einstellung oder -Einstellungssammlung, die angibt, wie eine Verbindung mit Service Bus hergestellt wird Siehe Verbindungen.
accessRights Zugriffsberechtigungen für die Verbindungszeichenfolge. Verfügbare Werte sind manage und listen. Die Standardeinstellung ist manage, d.h. heißt, dass die connection die Berechtigung manage hat. Wenn Sie eine Verbindungszeichenfolge verwenden, die nicht über die Berechtigung Manage verfügt, legen Sie accessRights auf „listen“ fest. Andernfalls versucht die Functions-Runtime ggf. erfolglos Vorgänge auszuführen, die Verwaltungsrechte erfordern. In Version 2.x und höheren Versionen von Azure Functions ist diese Eigenschaft nicht verfügbar, da die aktuelle Version des Service Bus SDK Verwaltungsvorgänge nicht unterstützt.
isSessionsEnabled true, wenn eine Verbindung mit einer true Warteschlange oder einem Abonnement hergestellt wird. Andernfalls false, wobei es sich um den Standardwert handelt.
autoComplete Muss für Funktionen, die nicht C# sind, true sein. Das bedeutet, dass der Trigger entweder automatisch nach der Verarbeitung abgeschlossen wird oder der Funktionscode manuell abgeschlossen wird.

Wenn der Wert auf true festgelegt ist, wird die Nachricht automatisch durch den Triggervorgang abgeschlossen, sofern die Ausführung der Funktion erfolgreich war, andernfalls wird die Meldung verworfen.

Ausnahmen führen in der Funktion dazu, dass die Runtime abandonAsync im Hintergrund aufruft. Wenn keine Ausnahme auftritt, wird completeAsync im Hintergrund aufgerufen. Diese Eigenschaft ist nur in Azure Functions ab Version 2.x und höher verfügbar.

Wenn Sie die Entwicklung lokal ausführen, fügen Sie Ihre Anwendungseinstellungen in der Datei local.settings.json in der Values-Sammlung hinzu.

Vollständige Beispiele finden Sie im Abschnitt Beispiele.

Verwendung

Die folgenden Parametertypen werden von allen C#-Modalitäten und Erweiterungsversionen unterstützt:

Typ BESCHREIBUNG
System.String Verwenden Sie diesen Parameter, wenn es sich bei der Nachricht um einfachen Text handelt.
byte[] Wird für binäre Datenmeldungen verwendet
Object Wenn eine Nachricht JSON enthält, versucht Functions, die JSON-Daten in einen bekannten, einfachen („plain old“) CLR-Objekttyp zu deserialisieren.

Messagingspezifische Parametertypen enthalten zusätzliche Nachrichtenmetadaten. Der vom Service Bus-Trigger unterstützten spezifischen Parametertypen hängen von der Runtimeversion von Functions, von der Version des Erweiterungspakets sowie von der verwendeten C#-Modalität ab.

Wenn die Funktion eine einzelne Nachricht verarbeiten soll, kann der Service Bus-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
string Die Nachricht als Zeichenfolge. Verwenden Sie diesen Parameter, wenn es sich bei der Nachricht um einfachen Text handelt.
byte[] Die Bytes der Nachricht.
Serialisierbare JSON-Typen Wenn ein Ereignis JSON-Daten enthält, versucht Azure Functions, die JSON-Daten in einen POCO-Typ (Plain Old CLR Object) zu deserialisieren.
ServiceBusReceivedMessage1 Das Nachrichtenobjekt.

Bei der Bindung an ServiceBusReceivedMessagekönnen Sie optional auch einen Parameter vom Typ ServiceBusMessageActions1,2 einschließen, um Nachrichtenabrechnungsaktionen auszuführen.

Wenn die Funktion einen Nachrichtenbatch verarbeiten soll, kann der Service Bus-Trigger an die folgenden Typen gebunden werden:

type BESCHREIBUNG
T[], wobei T einer der einzelnen Nachrichtentypen ist Ein Array von Ereignissen aus dem Batch. Jeder Eintrag stellt ein Ereignis dar.

Bei der Bindung an ServiceBusReceivedMessage[]können Sie optional auch einen Parameter vom Typ ServiceBusMessageActions1,2 einschließen, um Nachrichtenabrechnungsaktionen auszuführen.

1 Um diese Typen zu verwenden, müssen Sie auf Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 oder höher und die gemeinsamen Abhängigkeiten für SDK-Typbindungen verweisen.

2 Legen Sie bei Verwendung ServiceBusMessageActionsdie AutoCompleteMessages Eigenschaft des Trigger-Attributs auf false. Dadurch wird verhindert, dass die Laufzeit nach einem erfolgreichen Funktionsaufruf versucht, Nachrichten abzuschließen.

Wenn die Connection-Eigenschaft nicht definiert ist, sucht Functions nach einer App-Einstellung mit dem Namen AzureWebJobsServiceBus. Dies ist der Standardname für die Service Bus-Verbindungszeichenfolge. Sie können die Connection-Eigenschaft auch festlegen, um den Namen einer Anwendungseinstellung anzugeben, die die zu verwendende Service Bus-Verbindungszeichenfolge enthält.

Die eingehende Service Bus-Nachricht ist über einen ServiceBusQueueMessage- oder ServiceBusTopicMessage-Parameter verfügbar.

Greifen Sie auf die Warteschlange oder die Themennachricht als erstes Argument für Ihre Funktion zu. Die Service Bus-Nachricht wird als Zeichenfolge oder als JSON-Objekt an die Funktion übergeben.

Die Service Bus-Instanz ist über den Parameter verfügbar, der in der name-Eigenschaft der Datei function.json konfiguriert ist.

Die Warteschlangennachricht ist über einen als func.ServiceBusMessage typisierten Parameter für die Funktion verfügbar. Die Service Bus-Nachricht wird als Zeichenfolge oder als JSON-Objekt an die Funktion übergeben.

Ein vollständiges Beispiel finden Sie im Beispielabschnitt.

Verbindungen

Die connection-Eigenschaft ist ein Verweis auf eine Umgebungskonfiguration, die angibt, wie sich die App mit Service Bus verbinden soll. Folgendes kann angegeben werden:

Wenn der konfigurierte Wert sowohl eine genaue Übereinstimmung für eine einzelne Einstellung als auch eine Präfix-Übereinstimmung für andere Einstellungen ist, wird die genaue Übereinstimmung verwendet.

Verbindungszeichenfolge

Um die Verbindungszeichenfolge zu erhalten, führen Sie die Schritte unter Abrufen der Verwaltungsanmeldeinformationen aus. Die Verbindungszeichenfolge muss für einen Service Bus-Namespace gelten und darf nicht auf eine bestimmte Warteschlange oder ein Thema beschränkt sein.

Diese Verbindungszeichenfolge sollte in einer Anwendungseinstellung mit einem Namen gespeichert werden, der dem in der Eigenschaft connection der Bindungskonfiguration angegebenen Wert entspricht.

Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie nur den Rest des Namens angeben. Wenn Sie connection also beispielsweise auf „MyServiceBus“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyServiceBus“. Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Service Bus-Verbindungszeichenfolge aus der App-Einstellung „AzureWebJobsServiceBus“.

Identitätsbasierte Verbindungen

Wenn Sie Version 5.x oder eine höhere Version der Erweiterung verwenden, kann die App anstelle einer Verbindungszeichenfolge mit einem Geheimnis eine Microsoft Entra-Identität verwenden. Dazu definieren Sie Einstellungen unter einem gemeinsamen Präfix, das der Eigenschaft connection in der Trigger- und Bindungskonfiguration entspricht.

In diesem Modus benötigt die Erweiterung die folgenden Eigenschaften:

Eigenschaft Vorlage für Umgebungsvariable BESCHREIBUNG Beispielwert
Vollqualifizierter Namespace <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Der vollqualifizierte Service Bus-Namespace. <service_bus_namespace>.servicebus.windows.net

Zusätzliche Eigenschaften können festgelegt werden, um die Verbindung anzupassen. Weitere Informationen finden Sie unter Allgemeine Eigenschaften für identitätsbasierte Verbindungen.

Hinweis

Wenn Sie Azure App Configuration oder Key Vault verwenden, um Einstellungen für Verbindungen mit verwalteter Identität bereitzustellen, sollten die Namen der Einstellungen ein gültiges Schlüsseltrennzeichen wie : oder / anstelle von __ verwenden, um sicherzustellen, dass die Namen richtig aufgelöst werden.

Beispiel: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Identitätsbasierte Verbindungen verwenden eine verwaltete Identität, wenn sie im Azure Functions-Dienst gehostet werden. Standardmäßig wird eine vom System zugewiesene Identität verwendet, auch wenn mit den Eigenschaften credential und clientID eine vom Benutzer zugewiesene Identität angegeben werden kann. Beachten Sie, dass das Konfigurieren einer benutzerseitig zugewiesenen Identität mit einer Ressourcen-ID nicht unterstützt wird. Bei Ausführung in anderen Kontexten (z. B. bei der lokalen Entwicklung) wird stattdessen Ihre Entwickleridentität verwendet, Dieses Verhalten kann angepasst werden. Weitere Informationen finden Sie unter Lokale Entwicklung mit identitätsbasierten Verbindungen.

Erteilen der Berechtigung für die Identität

Unabhängig davon, welche Identität verwendet wird, muss diese über Berechtigungen zum Ausführen der vorgesehenen Aktionen verfügen. Daher müssen Sie für die meisten Azure-Dienste eine Rolle in Azure RBAC zuweisen, indem Sie entweder integrierte oder benutzerdefinierte Rollen verwenden, die diese Berechtigungen bieten.

Wichtig

Vom Zieldienst werden möglicherweise einige nicht für alle Kontexte erforderliche Berechtigungen verfügbar gemacht. Befolgen Sie nach Möglichkeit das Prinzip der geringsten Berechtigung, und gewähren Sie der Identität nur die erforderlichen Berechtigungen. Wenn die App beispielsweise nur Daten aus einer Datenquelle lesen muss, verwenden Sie eine Rolle, die nur über Leseberechtigungen verfügt. Es wäre nicht angemessen, eine Rolle zu zuweisen, die auch das Schreiben in diesen Dienst zulässt, da dies eine übermäßige Berechtigung für einen Lesevorgang wäre. Ebenso sollten Sie sicherstellen, dass die Rollenzuweisung auf die Ressourcen begrenzt ist, die gelesen werden müssen.

Sie müssen eine Rollenzuweisung erstellen, die zur Laufzeit Zugriff auf Ihre Themen und Warteschlangen ermöglicht. Verwaltungsrollen wie Besitzer sind nicht ausreichend. Die folgende Tabelle zeigt integrierte Rollen, die für die Service Bus-Erweiterung im Normalbetrieb empfohlen werden. Ihre Anwendung erfordert möglicherweise zusätzliche Berechtigungen basierend auf dem von Ihnen geschriebenen Code.

Bindungstyp Integrierte Beispielrollen
Trigger1 Azure Service Bus-Datenempfänger, Azure Service Bus-Datenbesitzer
Ausgabebindung Azure Service Bus-Datensender

1 Zum Auslösen von Service Bus-Themen muss die Rollenzuweisung einen effektiven Bereich für die Service Bus-Abonnementressource aufweisen. Wenn nur das Thema eingeschlossen wird, tritt ein Fehler auf. Einige Clients (z. B. das Azure-Portal) stellen die Service Bus-Abonnementressource nicht als Bereich für die Rollenzuweisung bereit. In solchen Fällen kann die Azure CLI stattdessen verwendet werden. Weitere Informationen finden Sie unter Integrierte Azure-Rollen für Azure Service Bus.

Nicht verarbeitbare Nachrichten

Die Verarbeitung von nicht verarbeitbaren Nachricht kann nicht in Azure Functions gesteuert oder konfiguriert werden. Service Bus verarbeitet nicht verarbeitbare Nachrichten selbst.

PeekLock-Verhalten

Die Functions-Laufzeit empfängt eine Nachricht im PeekLock Modus.

Standardmäßig ruft die Laufzeit die Nachricht auf Complete , wenn die Funktion erfolgreich abgeschlossen ist, oder aufruft Abandon , wenn die Funktion fehlschlägt. Sie können den automatischen Abschluss mit der autoCompleteMessages Eigenschaft in host.jsondeaktivieren.

Standardmäßig ruft die Laufzeit die Nachricht auf Complete , wenn die Funktion erfolgreich abgeschlossen ist, oder aufruft Abandon , wenn die Funktion fehlschlägt. Sie können den automatischen Abschluss mit der autoCompleteMessages Eigenschaft in host.json oder über eine Eigenschaft für das Trigger-Attribut deaktivieren. Sie sollten den automatischen Abschluss deaktivieren, wenn der Funktionscode die Meldungsabrechnung verarbeitet.

Wenn die Funktion länger als im PeekLock-Timeout angegeben ausgeführt wird, wird die Sperre automatisch verlängert, solange die Funktion ausgeführt wird. Die maxAutoRenewDuration kann in der Datei host.json konfiguriert werden, die ServiceBusProcessor.MaxAutoLockRenewalDuration zugeordnet ist. Der Standardwert dieser Einstellung ist 5 Minuten.

Metadaten von Nachrichten

Messagingspezifische Typen ermöglichen das einfache Abrufen von Metadaten als Eigenschaften des Objekts. Diese Eigenschaften hängen von der Runtimeversion von Functions, der Version des Erweiterungspakets und der verwendeten C#-Variante ab.

Diese Eigenschaften sind Mitglieder der ServiceBusReceivedMessage-Klasse.

Eigenschaft Typ BESCHREIBUNG
ApplicationProperties ApplicationProperties Eigenschaften, die vom Absender festgelegt werden.
ContentType string Ein Inhaltstypbezeichner, der vom Sender und Empfänger für anwendungsspezifische Logik verwendet wird.
CorrelationId string Die Korrelations-ID.
DeliveryCount Int32 Die Anzahl der Übermittlungen.
EnqueuedTime DateTime Die in die Warteschlange eingereihte Uhrzeit in UTC.
ScheduledEnqueueTimeUtc DateTime Die in die Warteschlange eingereihte geplante Uhrzeit in UTC
ExpiresAt DateTime Die Ablaufzeit in UTC.
MessageId string Benutzerdefinierter Wert, mit dem Service Bus doppelte Nachrichten ermitteln kann (sofern aktiviert).
ReplyTo string Die Antwort auf die Warteschlangenadresse.
Subject string Die anwendungsspezifische Bezeichnung, die statt der Metadateneigenschaft Label verwendet werden kann.
To string Die Zieladresse.

Nächste Schritte