Azure Service Bus-Bindungen für Azure FunctionsAzure Service Bus bindings for Azure Functions

Dieser Artikel erläutert das Arbeiten mit Azure Service Bus-Bindungen in Azure Functions.This article explains how to work with Azure Service Bus bindings in Azure Functions. Azure Functions unterstützt Trigger und Ausgabebindungen für Service Bus-Warteschlangen und -Themen.Azure Functions supports trigger and output bindings for Service Bus queues and topics.

Dies sind Referenzinformationen für Azure Functions-Entwickler.This is reference information for Azure Functions developers. Falls Sie mit Azure Functions noch nicht vertraut sind, beginnen Sie mit den folgenden Ressourcen:If you're new to Azure Functions, start with the following resources:

Pakete: Functions 1.xPackages - Functions 1.x

Die Service Bus-Bindungen werden im NuGet-Paket Microsoft.Azure.WebJobs.ServiceBus, Version 2.x bereitgestellt.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x.

Der folgenden Tabelle können Sie entnehmen, wie Sie Unterstützung für diese Bindung in den einzelnen Entwicklungsumgebungen hinzufügen.The following table tells how to add support for this binding in each development environment.

EntwicklungsumgebungDevelopment environment Hinzufügen von Unterstützung inTo add support in
Functions 1.xFunctions 1.x
Lokale Entwicklung – C#-KlassenbibliothekLocal development - C# class library Paket installierenInstall the package
Lokale Entwicklung – C#-Skript, JavaScript, F#Local development - C# script, JavaScript, F# AutomatischAutomatic
Entwicklung im PortalPortal development AutomatischAutomatic

Pakete: Functions 2.xPackages - Functions 2.x

Die Service Bus-Bindungen werden im NuGet-Paket Microsoft.Azure.WebJobs.Extensions.ServiceBus, Version 3.x, bereitgestellt.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.Extensions.ServiceBus NuGet package, version 3.x. Den Quellcode für das Paket finden Sie im GitHub-Repository azure-webjobs-sdk.Source code for the package is in the azure-webjobs-sdk GitHub repository.

Der folgenden Tabelle können Sie entnehmen, wie Sie Unterstützung für diese Bindung in den einzelnen Entwicklungsumgebungen hinzufügen.The following table tells how to add support for this binding in each development environment.

EntwicklungsumgebungDevelopment environment Hinzufügen von Unterstützung inTo add support in
Functions 2.xFunctions 2.x
Lokale Entwicklung – C#-KlassenbibliothekLocal development - C# class library Paket installierenInstall the package
Lokale Entwicklung – C#-Skript, JavaScript, F#, Java und PythonLocal development - C# script, JavaScript, F#, Java and Python Erweiterung registrierenRegister the extension
Entwicklung im PortalPortal development Installieren beim Hinzufügen einer AusgabebindungInstall when adding output binding

Informationen zum Aktualisieren der vorhandenen Bindungserweiterungen im Portal ohne erneute Veröffentlichung Ihres Funktions-App-Projekts finden Sie unter Manually install or update Azure Functions binding extensions from the portal (Manuelles Installieren oder Aktualisieren von Azure Functions-Bindungserweiterungen über das Portal).To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

TriggerTrigger

Verwenden Sie den Service Bus-Trigger, um auf Nachrichten von einer Service Bus-Warteschlange oder einem Thema zu reagieren.Use the Service Bus trigger to respond to messages from a Service Bus queue or topic.

Trigger: BeispielTrigger - example

Sehen Sie sich das sprachspezifische Beispiel an:See the language-specific example:

Trigger: C#-BeispielTrigger - C# example

Das folgende Beispiel zeigt eine C#-Funktion, die Nachrichtenmetadaten liest und eine Service Bus-Warteschlangennachricht protokolliert:The following example shows a C# function that reads message metadata and logs a Service Bus queue message:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", AccessRights.Manage, Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

Dieses Beispiel bezieht sich auf Azure Functions Version 1.x.This example is for Azure Functions version 1.x. Damit dieser Code für 2.x funktioniert:To make this code work for 2.x:

Trigger: C#-SkriptbeispielTrigger - C# script example

Das folgende Beispiel zeigt eine Service Bus-Triggerbindung in einer Datei vom Typ function.json sowie eine C#-Skriptfunktion, die die Bindung verwendet.The following example shows a Service Bus trigger binding in a function.json file and a C# script function that uses the binding. Die Funktion liest Nachrichtenmetadaten und protokolliert eine Service Bus-Warteschlangennachricht.The function reads message metadata and logs a Service Bus queue message.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Der C#-Skriptcode sieht wie folgt aus:Here's the C# script code:

using System;

public static void Run(string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");

    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"DeliveryCount={deliveryCount}");
    log.Info($"MessageId={messageId}");
}

Trigger: F#-BeispielTrigger - F# example

Das folgende Beispiel zeigt eine Service Bus-Triggerbindung in einer Datei vom Typ function.json sowie eine F#-Funktion, die die Bindung verwendet.The following example shows a Service Bus trigger binding in a function.json file and an F# function that uses the binding. Die Funktion protokolliert eine Service Bus-Warteschlangennachricht.The function logs a Service Bus queue message.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Der F#-Skriptcode sieht wie folgt aus:Here's the F# script code:

let Run(myQueueItem: string, log: ILogger) =
    log.LogInformation(sprintf "F# ServiceBus queue trigger function processed message: %s" myQueueItem)

Trigger: Java-BeispielTrigger - Java example

Die folgende Java-Funktion verwendet die @ServiceBusQueueTrigger-Anmerkung aus der Java-Funktions-Laufzeitbibliothek, um die Konfiguration für einen Service Bus-Warteschlangentrigger zu beschreiben.The following Java function uses the @ServiceBusQueueTrigger annotation from the Java functions runtime library to describe the configuration for a Service Bus queue trigger. Die Funktion greift die Nachricht aus der Warteschlange ab und fügt sie den Protokollen hinzu.The function grabs the message placed on the queue and adds it to the logs.

@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.Java functions can also be triggered when a message is added to a Service Bus topic. Im folgenden Beispiel wird die @ServiceBusTopicTrigger-Anmerkung verwendet, um die Triggerkonfiguration zu beschreiben.The following example uses the @ServiceBusTopicTrigger annotation to describe the trigger configuration.

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

Trigger: JavaScript-BeispielTrigger - JavaScript example

Das folgende Beispiel zeigt eine Service Bus-Triggerbindung in einer Datei vom Typ function.json sowie eine JavaScript-Funktion, die die Bindung verwendet.The following example shows a Service Bus trigger binding in a function.json file and a JavaScript function that uses the binding. Die Funktion liest Nachrichtenmetadaten und protokolliert eine Service Bus-Warteschlangennachricht.The function reads message metadata and logs a Service Bus queue message.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Der JavaScript-Skriptcode sieht wie folgt aus:Here's the JavaScript script code:

module.exports = function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
    context.done();
};

Trigger: Beispiel für PythonTrigger - Python example

Das folgende Beispiel zeigt, wie Sie eine ServiceBus-Warteschlangennachricht mittels Trigger lesen.The following example demonstrates how to read a ServiceBus queue message via a trigger.

Eine ServiceBus-Bindung ist in function.json definiert, wobei type auf serviceBusTrigger festgelegt ist.A ServiceBus binding is defined in function.json where type is set to serviceBusTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Der Code in _init_.py deklariert einen Parameter als func.ServiceBusMessage, was es Ihnen ermöglicht, die Warteschlangennachricht in ihrer Funktion zu lesen.The code in _init_.py declares a parameter as func.ServiceBusMessage which allows you to read the queue message in your function.

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

Trigger: AttributeTrigger - attributes

Verwenden Sie in C#-Klassenbibliotheken die folgenden Attribute, um einen Service Bus-Trigger zu konfigurieren:In C# class libraries, use the following attributes to configure a Service Bus trigger:

  • ServiceBusTriggerAttributeServiceBusTriggerAttribute

    Der Konstruktor des Attributs nimmt den Namen der Warteschlange oder des Themas und des Abonnements an.The attribute's constructor takes the name of the queue or the topic and subscription. In Version 1.x von Azure Functions können Sie auch die Zugriffsrechte der Verbindung angeben.In Azure Functions version 1.x, you can also specify the connection's access rights. Wenn Sie keine Zugriffsrechte angeben, ist der Standardwert Manage.If you don't specify access rights, the default is Manage. Weitere Informationen finden Sie im Abschnitt Trigger: Konfiguration.For more information, see the Trigger - configuration section.

    Das folgende Beispiel zeigt das mit einem Zeichenfolgenparameter verwendete Attribut:Here's an example that shows the attribute used with a string parameter:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue")] string myQueueItem, ILogger log)
    {
        ...
    }
    

    Durch Festlegen der Eigenschaft Connection können Sie das zu verwendende Service Bus-Konto angeben, wie das folgende Beispiel zeigt:You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
        string myQueueItem, ILogger log)
    {
        ...
    }
    

    Ein vollständiges Beispiel finden Sie unter Trigger: C#-Beispiel.For a complete example, see Trigger - C# example.

  • ServiceBusAccountAttributeServiceBusAccountAttribute

    Eine weitere Möglichkeit zum Angeben des zu verwendenden Service Bus-Kontos.Provides another way to specify the Service Bus account to use. Der Konstruktor nimmt den Namen einer App-Einstellung mit einer Service Bus-Verbindungszeichenfolge an.The constructor takes the name of an app setting that contains a Service Bus connection string. Das Attribut kann auf Parameter-, Methoden- oder Klassenebene angewendet werden.The attribute can be applied at the parameter, method, or class level. Das folgende Beispiel zeigt die Anwendung auf Klassen- und Methodenebene:The following example shows class level and method level:

    [ServiceBusAccount("ClassLevelServiceBusAppSetting")]
    public static class AzureFunctions
    {
        [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
        [FunctionName("ServiceBusQueueTriggerCSharp")]
        public static void Run(
            [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
            string myQueueItem, ILogger log)
    {
        ...
    }
    

Das zu verwendende Service Bus-Konto wird in der folgendem Reihenfolge bestimmt:The Service Bus account to use is determined in the following order:

  • Die Eigenschaft Connection des Attributs ServiceBusTrigger.The ServiceBusTrigger attribute's Connection property.
  • Das Attribut ServiceBusAccount, das auf den gleichen Parameter angewendet wird wie das Attribut ServiceBusTrigger.The ServiceBusAccount attribute applied to the same parameter as the ServiceBusTrigger attribute.
  • Das Attribut ServiceBusAccount, das auf die Funktion angewendet wird.The ServiceBusAccount attribute applied to the function.
  • Das Attribut ServiceBusAccount, das auf die Klasse angewendet wird.The ServiceBusAccount attribute applied to the class.
  • Die App-Einstellung „AzureWebJobsServiceBus“.The "AzureWebJobsServiceBus" app setting.

Trigger: KonfigurationTrigger - configuration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut ServiceBusTrigger festlegen:The following table explains the binding configuration properties that you set in the function.json file and the ServiceBusTrigger attribute.

Eigenschaft von „function.json“function.json property AttributeigenschaftAttribute property BESCHREIBUNGDescription
typetype n/a Muss auf „serviceBusTrigger“ festgelegt werden.Must be set to "serviceBusTrigger". Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/a Muss auf „in“ festgelegt werden.Must be set to "in". Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
namename n/a Der Name der Variablen, die die Warteschlangen- oder Themanachricht im Funktionscode darstellt.The name of the variable that represents the queue or topic message in function code. Legen Sie diesen Wert auf „$return“ fest, um auf den Rückgabewert der Funktion zu verweisen.Set to "$return" to reference the function return value.
queueNamequeueName QueueNameQueueName Der Name der zu überwachenden Warteschlange.Name of the queue to monitor. Legen Sie diesen nur fest, wenn Sie eine Warteschlange überwachen (nicht für ein Thema).Set only if monitoring a queue, not for a topic.
topicNametopicName TopicNameTopicName Der Name des zu überwachenden Themas.Name of the topic to monitor. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).Set only if monitoring a topic, not for a queue.
subscriptionNamesubscriptionName SubscriptionNameSubscriptionName Der Name des zu überwachenden Abonnements.Name of the subscription to monitor. Legen Sie diesen nur fest, wenn Sie ein Thema überwachen (nicht für eine Warteschlange).Set only if monitoring a topic, not for a queue.
Verbindungconnection ConnectionConnection Der Name einer App-Einstellung, die die Service Bus-Verbindungszeichenfolge für diese Bindung enthält.The name of an app setting that contains the Service Bus connection string to use for this binding. Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie nur den Rest des Namens angeben.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. Wenn Sie connection also beispielsweise auf „MyServiceBus“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyServiceBus“.For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus." Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Service Bus-Verbindungszeichenfolge aus der App-Einstellung „AzureWebJobsServiceBus“.If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

Um die Verbindungszeichenfolge zu erhalten, führen Sie die Schritte unter Abrufen der Verwaltungsanmeldeinformationen aus.To obtain a connection string, follow the steps shown at Get the management credentials. Die Verbindungszeichenfolge muss für einen Service Bus-Namespace gelten und darf nicht auf eine bestimmte Warteschlange oder ein Thema beschränkt sein.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights zugreifenAccess Zugriffsberechtigungen für die Verbindungszeichenfolge.Access rights for the connection string. Verfügbare Werte sind manage und listen.Available values are manage and listen. Die Standardeinstellung ist manage, d.h. heißt, dass die connection die Berechtigung Manage hat.The default is manage, which indicates that the connection has the Manage permission. Wenn Sie eine Verbindungszeichenfolge verwenden, die nicht über die Berechtigung Manage verfügt, legen Sie accessRights auf „listen“ fest.If you use a connection string that does not have the Manage permission, set accessRights to "listen". Andernfalls versucht die Functions-Runtime ggf. erfolglos Vorgänge auszuführen, die Verwaltungsrechte erfordern.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. In Version 2.x von Azure Functions ist diese Eigenschaft nicht verfügbar, da die aktuelle Version des Storage SDK Verwaltungsvorgänge nicht unterstützt.In Azure Functions version 2.x, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.When you're developing locally, app settings go into the local.settings.json file.

Trigger: VerwendungTrigger - usage

In C#- und C#-Skripts können Sie die folgenden Parametertypen für die Warteschlangen- oder Themanachricht verwenden:In C# and C# script, you can use the following parameter types for the queue or topic message:

  • string: Wenn es sich bei der Nachricht um Text handelt.string - If the message is text.
  • byte[]: Nützlich für Binärdaten.byte[] - Useful for binary data.
  • Ein benutzerdefinierter Typ: Wenn die Nachricht JSON enthält, versucht Azure Functions, die JSON-Daten zu deserialisieren.A custom type - If the message contains JSON, Azure Functions tries to deserialize the JSON data.
  • BrokeredMessage: Gibt die deserialisierte Nachricht mit der BrokeredMessage.GetBody<T>()-Methode zurück.BrokeredMessage - Gives you the deserialized message with the BrokeredMessage.GetBody<T>() method.

Diese Parameter gelten für Azure Functions Version 1.x. Verwenden Sie für 2.x Message anstelle von BrokeredMessage.These parameters are for Azure Functions version 1.x; for 2.x, use Message instead of BrokeredMessage.

Greifen Sie in JavaScript auf die Warteschlangen- oder Themanachricht mit context.bindings.<name from function.json> zu.In JavaScript, access the queue or topic message by using context.bindings.<name from function.json>. Die Service Bus-Nachricht wird als Zeichenfolge oder als JSON-Objekt an die Funktion übergeben.The Service Bus message is passed into the function as either a string or JSON object.

Trigger: Nicht verarbeitbare NachrichtenTrigger - poison messages

Die Verarbeitung von nicht verarbeitbaren Nachricht kann nicht in Azure Functions gesteuert oder konfiguriert werden.Poison message handling can't be controlled or configured in Azure Functions. Service Bus verarbeitet nicht verarbeitbare Nachrichten selbst.Service Bus handles poison messages itself.

Trigger: PeekLock-VerhaltenTrigger - PeekLock behavior

Die Functions-Laufzeit empfängt eine Nachricht im PeekLock Modus.The Functions runtime receives a message in PeekLock mode. Sie ruft bei erfolgreicher Ausführung der Funktion Complete für die Nachricht auf. Ist die Ausführung nicht erfolgreich, wird Abandon aufgerufen.It calls Complete on the message if the function finishes successfully, or calls Abandon if the function fails. 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.If the function runs longer than the PeekLock timeout, the lock is automatically renewed as long as the function is running.

Die maxAutoRenewDuration kann in der Datei host.json konfiguriert werden, die OnMessageOptions.MaxAutoRenewDuration zugeordnet ist.The maxAutoRenewDuration is configurable in host.json, which maps to OnMessageOptions.MaxAutoRenewDuration. Der maximal zulässige Wert für diese Einstellung beträgt entsprechend der Service Bus-Dokumentation 5 Minuten, wohingegen Sie den Standardwert von 5 Minuten für das Functions-Zeitlimit auf 10 Minuten erhöhen können.The maximum allowed for this setting is 5 minutes according to the Service Bus documentation, whereas you can increase the Functions time limit from the default of 5 minutes to 10 minutes. Bei Service Bus-Funktionen sollten Sie dies nicht tun, da Sie den Service Bus-Verlängerungsgrenzwert übersteigen würden.For Service Bus functions you wouldn’t want to do that then, because you’d exceed the Service Bus renewal limit.

Trigger: NachrichtenmetadatenTrigger - message metadata

Der Service Bus-Trigger stellt mehrere Metadateneigenschaften bereit.The Service Bus trigger provides several metadata properties. Diese Eigenschaften können als Teil der Bindungsausdrücke in anderen Bindungen oder als Parameter im Code verwendet werden.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Dies sind Eigenschaften der BrokeredMessage-Klasse.These are properties of the BrokeredMessage class.

EigenschaftProperty TypType BESCHREIBUNGDescription
DeliveryCount Int32 Die Anzahl der Übermittlungen.The number of deliveries.
DeadLetterSource string Die Quelle von unzustellbaren Nachrichten.The dead letter source.
ExpiresAtUtc DateTime Die Ablaufzeit in UTC.The expiration time in UTC.
EnqueuedTimeUtc DateTime Die in die Warteschlange eingereihte Uhrzeit in UTC.The enqueued time in UTC.
MessageId string Benutzerdefinierter Wert, mit dem Service Bus doppelte Nachrichten ermitteln kann (sofern aktiviert).A user-defined value that Service Bus can use to identify duplicate messages, if enabled.
ContentType string Ein Inhaltstypbezeichner, der vom Sender und Empfänger für anwendungsspezifische Logik verwendet wird.A content type identifier utilized by the sender and receiver for application specific logic.
ReplyTo string Die Antwort auf die Warteschlangenadresse.The reply to queue address.
SequenceNumber Int64 Eindeutige Nummer, die vom Service Bus einer Nachricht zugewiesen wird.The unique number assigned to a message by the Service Bus.
To string Die Zieladresse.The send to address.
Label string Die anwendungsspezifische Bezeichnung.The application specific label.
CorrelationId string Die Korrelations-ID.The correlation ID.

Hinweis

Zurzeit ist der Service Bus-Trigger, der mit sitzungsaktivierten Warteschlangen und Abonnements funktioniert, in der Vorschauphase.Currently, Service bus trigger that works with session enabled queues and subscriptions is in preview. Verfolgen Sie dieses Element, um alle weiteren Updates zu dieser Funktion zu erhalten.Please track this item for any further updates regarding this.

Codebeispiele mit diesen Eigenschaften finden Sie weiter oben in diesem Artikel.See code examples that use these properties earlier in this article.

Trigger: Eigenschaften von „host.json“Trigger - host.json properties

Die Datei host.json enthält Einstellungen, mit denen das Verhalten des Service Bus-Triggers gesteuert werden kann.The host.json file contains settings that control Service Bus trigger behavior.

{
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "maxAutoRenewDuration": "00:05:00"
    }
}
EigenschaftProperty StandardDefault BESCHREIBUNGDescription
maxConcurrentCallsmaxConcurrentCalls 1616 Die maximale Anzahl gleichzeitiger Aufrufe für den Rückruf, der vom Nachrichtensystem initiiert werden soll.The maximum number of concurrent calls to the callback that the message pump should initiate. Die Functions-Runtime verarbeitet standardmäßig mehrere Nachrichten gleichzeitig.By default, the Functions runtime processes multiple messages concurrently. Um die Runtime anzuweisen, jeweils nur eine Warteschlangen- oder Themennachricht zu verarbeiten, legen Sie maxConcurrentCalls auf „1“ fest.To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCountprefetchCount n/a Das standardmäßige PrefetchCount, das von dem zugrunde liegenden MessageReceiver verwendet wird.The default PrefetchCount that will be used by the underlying MessageReceiver.
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 Die maximale Zeitspanne, in der die Nachrichtensperre automatisch erneuert wird.The maximum duration within which the message lock will be renewed automatically.

OutputOutput

Verwendet Azure Service Bus-Ausgabebindung zum Senden von Warteschlangen- oder Themanachrichten.Use Azure Service Bus output binding to send queue or topic messages.

Ausgabe: BeispielOutput - example

Sehen Sie sich das sprachspezifische Beispiel an:See the language-specific example:

Ausgabe: C#-BeispielOutput - C# example

Das folgende Beispiel zeigt eine C#-Funktion, die eine Service Bus-Warteschlangennachricht sendet:The following example shows a C# function that sends a Service Bus queue message:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, ILogger log)
{
    log.LogInformation($"C# function processed: {input.Text}");
    return input.Text;
}

Ausgabe: C#-SkriptbeispielOutput - C# script example

Das folgende Beispiel zeigt eine Service Bus-Ausgabebindung in einer Datei vom Typ function.json sowie eine C#-Skriptfunktion, die die Bindung verwendet.The following example shows a Service Bus output binding in a function.json file and a C# script function that uses the binding. Die Funktion verwendet einen Timertrigger, um alle 15 Sekunden eine Warteschlangennachricht zu senden.The function uses a timer trigger to send a queue message every 15 seconds.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Der folgende C#-Skriptcode erstellt eine einzelne Nachricht:Here's C# script code that creates a single message:

public static void Run(TimerInfo myTimer, ILogger log, out string outputSbQueue)
{
    string message = $"Service Bus queue message created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue = message;
}

Der folgende C#-Skriptcode erstellt mehrere Nachrichten:Here's C# script code that creates multiple messages:

public static void Run(TimerInfo myTimer, ILogger log, ICollector<string> outputSbQueue)
{
    string message = $"Service Bus queue messages created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue.Add("1 " + message);
    outputSbQueue.Add("2 " + message);
}

Ausgabe: F#-BeispielOutput - F# example

Das folgende Beispiel zeigt eine Service Bus-Ausgabebindung in einer Datei vom Typ function.json sowie eine F#-Skriptfunktion, die die Bindung verwendet.The following example shows a Service Bus output binding in a function.json file and an F# script function that uses the binding. Die Funktion verwendet einen Timertrigger, um alle 15 Sekunden eine Warteschlangennachricht zu senden.The function uses a timer trigger to send a queue message every 15 seconds.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Der folgende F#-Skriptcode erstellt eine einzelne Nachricht:Here's F# script code that creates a single message:

let Run(myTimer: TimerInfo, log: ILogger, outputSbQueue: byref<string>) =
    let message = sprintf "Service Bus queue message created at: %s" (DateTime.Now.ToString())
    log.LogInformation(message)
    outputSbQueue = message

Ausgabe: Java-BeispielOutput - Java example

Das folgende Beispiel zeigt eine Java-Funktion, die eine Nachricht an die Service Bus-Warteschlange myqueue sendet, wenn sie durch eine HTTP-Anforderung ausgelöst wird.The following example shows a Java function that sends a message to a Service Bus queue myqueue when triggered by a HTTP request.

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

Verwenden Sie die @QueueOutput-Anmerkung in der Laufzeitbibliothek für Java-Funktionen für Funktionsparameter, deren Wert in eine Service Bus-Warteschlange geschrieben wird.In the Java functions runtime library, use the @QueueOutput annotation on function parameters whose value would be written to a Service Bus queue. Der Parametertyp sollte OutputBinding<T> lauten, wobei „T“ für einen beliebigen nativen Java-Typ eines POJO steht.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Java-Funktionen können auch in ein Service Bus-Thema schreiben.Java functions can also write to a Service Bus topic. Im folgenden Beispiel wird die @ServiceBusTopicOutput-Anmerkung verwendet, um die Konfiguration für die Ausgabebindung zu beschreiben.The following example uses the @ServiceBusTopicOutput annotation to describe the configuration for the output binding.

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

Ausgabe: JavaScript-BeispielOutput - JavaScript example

Das folgende Beispiel zeigt eine Service Bus-Ausgabebindung in einer Datei vom Typ function.json sowie eine JavaScript-Funktion, die die Bindung verwendet.The following example shows a Service Bus output binding in a function.json file and a JavaScript function that uses the binding. Die Funktion verwendet einen Timertrigger, um alle 15 Sekunden eine Warteschlangennachricht zu senden.The function uses a timer trigger to send a queue message every 15 seconds.

Bindungsdaten in der Datei function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Der folgende JavaScript-Skriptcode erstellt eine einzelne Nachricht:Here's JavaScript script code that creates a single message:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
    context.done();
};

Der folgende JavaScript-Skriptcode mehrere Nachrichten:Here's JavaScript script code that creates multiple messages:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = [];
    context.bindings.outputSbQueue.push("1 " + message);
    context.bindings.outputSbQueue.push("2 " + message);
    context.done();
};

Ausgabe: Beispiel für PythonOutput - Python example

Das folgende Beispiel zeigt, wie Sie Ausgaben in eine ServiceBus-Warteschlange in Python schreiben.The following example demonstrates how to write out to a ServiceBus queue in Python.

Eine ServiceBus-Bindungsdefinition ist in function.json definiert, wobei type auf serviceBus festgelegt ist.A ServiceBue binding definition is defined in function.json where type is set to serviceBus.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "msg",
      "queueName": "outqueue"
    }
  ]
}

In _init_.py können Sie eine Nachricht als Ausgabe in die Warteschlange schreiben, indem Sie einen Wert an die set-Methode übergeben.In _init_.py, you can write out a message to the queue by passing a value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Ausgabe: AttributeOutput - attributes

In C#-Klassenbibliotheken verwenden Sie die ServiceBusAttribute.In C# class libraries, use the ServiceBusAttribute.

Der Konstruktor des Attributs nimmt den Namen der Warteschlange oder des Themas und des Abonnements an.The attribute's constructor takes the name of the queue or the topic and subscription. Sie können auch die Zugriffsrechte der Verbindung angeben.You can also specify the connection's access rights. Wie Sie die Einstellung für die Zugriffsrechte auswählen, wird im Abschnitt Ausgabe: Konfiguration erläutert.How to choose the access rights setting is explained in the Output - configuration section. Das folgende Beispiel zeigt, wie das Attribut auf den Rückgabewert der Funktion angewendet wird:Here's an example that shows the attribute applied to the return value of the function:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

Durch Festlegen der Eigenschaft Connection können Sie das zu verwendende Service Bus-Konto angeben, wie das folgende Beispiel zeigt:You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

Ein vollständiges Beispiel finden Sie unter Ausgabe: C#-Beispiel.For a complete example, see Output - C# example.

Mit dem Attribut ServiceBusAccount können Sie das zu verwendende Service Bus-Konto auf Klassen-, Methoden- oder Parameterebene angeben.You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. Weitere Informationen finden Sie unter Trigger: Attribute.For more information, see Trigger - attributes.

Ausgabe: KonfigurationOutput - configuration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut ServiceBus festlegen:The following table explains the binding configuration properties that you set in the function.json file and the ServiceBus attribute.

Eigenschaft von „function.json“function.json property AttributeigenschaftAttribute property BESCHREIBUNGDescription
typetype n/a Muss auf „serviceBus“ festgelegt werden.Must be set to "serviceBus". Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
directiondirection n/a Muss auf „out“ festgelegt werden.Must be set to "out". Diese Eigenschaft wird automatisch festgelegt, wenn Sie den Trigger im Azure Portal erstellen.This property is set automatically when you create the trigger in the Azure portal.
namename n/a Der Name der Variablen, die die Warteschlange oder das Thema im Funktionscode darstellt.The name of the variable that represents the queue or topic in function code. Legen Sie diesen Wert auf „$return“ fest, um auf den Rückgabewert der Funktion zu verweisen.Set to "$return" to reference the function return value.
queueNamequeueName QueueNameQueueName Name der Warteschlange.Name of the queue. Legen Sie diesen nur fest, wenn Warteschlangennachrichten gesendet werden (nicht für ein Thema).Set only if sending queue messages, not for a topic.
topicNametopicName TopicNameTopicName Der Name des zu überwachenden Themas.Name of the topic to monitor. Legen Sie diesen nur fest, wenn Themanachrichten gesendet werden (nicht für eine Warteschlange).Set only if sending topic messages, not for a queue.
Verbindungconnection ConnectionConnection Der Name einer App-Einstellung, die die Service Bus-Verbindungszeichenfolge für diese Bindung enthält.The name of an app setting that contains the Service Bus connection string to use for this binding. Falls der Name der App-Einstellung mit „AzureWebJobs“ beginnt, können Sie nur den Rest des Namens angeben.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. Wenn Sie connection also beispielsweise auf „MyServiceBus“ festlegen, sucht die Functions-Laufzeit nach einer App-Einstellung namens „AzureWebJobsMyServiceBus“.For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus." Ohne Angabe für connection verwendet die Functions-Laufzeit die standardmäßige Service Bus-Verbindungszeichenfolge aus der App-Einstellung „AzureWebJobsServiceBus“.If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

Um die Verbindungszeichenfolge zu erhalten, führen Sie die Schritte unter Abrufen der Verwaltungsanmeldeinformationen aus.To obtain a connection string, follow the steps shown at Get the management credentials. Die Verbindungszeichenfolge muss für einen Service Bus-Namespace gelten und darf nicht auf eine bestimmte Warteschlange oder ein Thema beschränkt sein.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights zugreifenAccess Zugriffsberechtigungen für die Verbindungszeichenfolge.Access rights for the connection string. Verfügbare Werte sind manage und listen.Available values are manage and listen. Die Standardeinstellung ist manage, d.h. heißt, dass die connection die Berechtigung Manage hat.The default is manage, which indicates that the connection has the Manage permission. Wenn Sie eine Verbindungszeichenfolge verwenden, die nicht über die Berechtigung Manage verfügt, legen Sie accessRights auf „listen“ fest.If you use a connection string that does not have the Manage permission, set accessRights to "listen". Andernfalls versucht die Functions-Runtime ggf. erfolglos Vorgänge auszuführen, die Verwaltungsrechte erfordern.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. In Version 2.x von Azure Functions ist diese Eigenschaft nicht verfügbar, da die aktuelle Version des Storage SDK Verwaltungsvorgänge nicht unterstützt.In Azure Functions version 2.x, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

Wenn Sie lokal entwickeln, werden App-Einstellungen in der Datei „local.settings.json“ gespeichert.When you're developing locally, app settings go into the local.settings.json file.

Ausgabe: VerwendungOutput - usage

In Azure Functions 1.x erstellt die Runtime die Warteschlange, falls sie nicht vorhanden ist und Sie accessRights auf manage festgelegt haben.In Azure Functions 1.x, the runtime creates the queue if it doesn't exist and you have set accessRights to manage. In Functions-Version 2.x muss die Warteschlange oder das Thema bereits vorhanden sein. Wenn Sie eine nicht vorhandene Warteschlange oder ein nicht vorhandenes Thema angeben, tritt bei der Funktion ein Fehler auf.In Functions version 2.x, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function will fail.

In C#- und C#-Skripts können Sie die folgenden Parametertypen für die Ausgabebindung verwenden:In C# and C# script, you can use the following parameter types for the output binding:

  • out T paramName - T kann jeder JSON-serialisierbare Typ sein.out T paramName - T can be any JSON-serializable type. Wenn der Parameterwert NULL ist, wenn die Funktion beendet wird, erstellt Functions die Nachricht mit einem NULL-Objekt.If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string: Wenn der Parameterwert NULL ist, sobald die Funktion beendet wird, erstellt Functions keine Nachricht.out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[]: Wenn der Parameterwert NULL ist, sobald die Funktion beendet wird, erstellt Functions keine Nachricht.out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage: Wenn der Parameterwert NULL ist, sobald die Funktion beendet wird, erstellt Functions keine Nachricht (für Functions 1.x).out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message (for Functions 1.x)
  • out Message: Wenn der Parameterwert NULL ist, sobald die Funktion beendet wird, erstellt Functions keine Nachricht (für Functions 2.x).out Message - If the parameter value is null when the function exits, Functions does not create a message (for Functions 2.x)
  • ICollector<T> oder IAsyncCollector<T>: Zum Erstellen mehrerer Nachrichten.ICollector<T> or IAsyncCollector<T> - For creating multiple messages. Beim Aufrufen der Add -Methode wird eine Nachricht erstellt.A message is created when you call the Add method.

Beim Arbeiten mit C# Funktionen:When working with C# functions:

  • Asynchrone Funktionen benötigen anstelle eines out-Parameters einen Rückgabewert oder IAsyncCollector.Async functions need a return value or IAsyncCollector instead of an out parameter.

  • Um auf die Sitzungs-ID zuzugreifen, erstellen Sie eine Bindung an einen Message-Typ und verwenden die Eigenschaft sessionId.To access the session ID, bind to a Message type and use the sessionId property.

Greifen Sie in JavaScript auf die Warteschlange oder das Thema mit context.bindings.<name from function.json> zu.In JavaScript, access the queue or topic by using context.bindings.<name from function.json>. Sie können context.binding.<name> eine Zeichenfolge, ein Bytearray oder ein JavaScript-Objekt (deserialisiert in JSON) zuweisen.You can assign a string, a byte array, or a JavaScript object (deserialized into JSON) to context.binding.<name>.

Um eine Nachricht in einer anderen Sprache als C# an eine sitzungsfähige Warteschlange zu senden, verwenden Sie das Azure Service Bus SDK anstelle der integrierten Ausgabebindung.To send a message to a session-enabled queue in non-C# languages, use the Azure Service Bus SDK rather than the built-in output binding.

Ausnahmen und RückgabecodesExceptions and return codes

BindungBinding VerweisReference
Service BusService Bus Service Bus-FehlercodesService Bus Error Codes
Service BusService Bus Service Bus-GrenzwerteService Bus Limits

Einstellungen für „host.json“host.json settings

In diesem Abschnitt werden die verfügbaren globalen Konfigurationseinstellungen für diese Bindung in Version 2.x beschrieben.This section describes the global configuration settings available for this binding in version 2.x. Die nachfolgende Beispieldatei „host.json“ enthält nur die Einstellungen für Version 2.x für diese Bindung.The example host.json file below contains only the version 2.x settings for this binding. Weitere Informationen zu globalen Konfigurationseinstellungen in Version 2.x finden Sie unter host.json-Referenz für Azure Functions 2.x.For more information about global configuration settings in version 2.x, see host.json reference for Azure Functions version 2.x.

Hinweis

Eine Referenz für „host.json“ in Functions 1.x finden Sie unter host.json-Referenz für Azure Functions 1.x.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": false,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:55:00"
            }
        }
    }
}
EigenschaftProperty StandardDefault BESCHREIBUNGDescription
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 Die maximale Zeitspanne, in der die Nachrichtensperre automatisch erneuert wird.The maximum duration within which the message lock will be renewed automatically.
autoCompleteautoComplete truetrue Ob der Trigger sofort als vollständig markiert werden soll (Autovervollständigung) oder ob er darauf wartet, dass die Verarbeitung abgeschlossen wird.Whether the trigger should immediately mark as complete (autocomplete) or wait for processing to call complete.
maxConcurrentCallsmaxConcurrentCalls 1616 Die maximale Anzahl gleichzeitiger Aufrufe für den Rückruf, der vom Nachrichtensystem initiiert werden soll.The maximum number of concurrent calls to the callback that the message pump should initiate. Die Functions-Runtime verarbeitet standardmäßig mehrere Nachrichten gleichzeitig.By default, the Functions runtime processes multiple messages concurrently. Um die Runtime anzuweisen, jeweils nur eine Warteschlangen- oder Themennachricht zu verarbeiten, legen Sie maxConcurrentCalls auf „1“ fest.To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCountprefetchCount n/a Das standardmäßige PrefetchCount, das von dem zugrunde liegenden MessageReceiver verwendet wird.The default PrefetchCount that will be used by the underlying MessageReceiver.

Nächste SchritteNext steps