Azure Functions-Muster für BindungsausdrückeAzure Functions binding expression patterns

Eines der leistungsstärksten Merkmale von Triggern und Bindungen sind Bindungsausdrücke.One of the most powerful features of triggers and bindings is binding expressions. In der Datei function.json, in Funktionsparametern und in Code können Sie Ausdrücke verwenden, die mit Werten aus verschiedenen Quellen aufgelöst werden.In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

Die meisten Ausdrücke sind von geschweiften Klammern umschlossen.Most expressions are identified by wrapping them in curly braces. Beispielsweise wird in einer Trigger-Funktion für die Eingabewarteschlange {queueTrigger} in den Text der Warteschlangenmeldung aufgelöst.For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. Lautet die Eigenschaft path für eine Blobausgabebindung container/{queueTrigger}, und wird die Funktion durch eine Warteschlangennachricht HelloWorld ausgelöst, so wird ein Blob mit dem Namen HelloWorld erstellt.If the path property for a blob output binding is container/{queueTrigger} and the function is triggered by a queue message HelloWorld, a blob named HelloWorld is created.

Arten von BindungsausdrückenTypes of binding expressions

Bindungsausdrücke – App-EinstellungenBinding expressions - app settings

Es hat sich bewährt, Geheimnisse und Verbindungszeichenfolgen nicht in Konfigurationsdateien, sondern über App-Einstellungen zu verwalten.As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. Dies schränkt den Zugriff auf diese Geheimnisse ein und ermöglicht das sichere Speichern von Dateien wie function.json in öffentlichen Repositorys zur Quellcodeverwaltung.This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

App-Einstellungen sind auch nützlich, wenn Sie die jeweilige Konfiguration entsprechend der Umgebung ändern möchten.App settings are also useful whenever you want to change configuration based on the environment. Beispielsweise kann es sein, dass Sie in einer Testumgebung eine andere Warteschlange oder einen anderen Blob Storage-Container überwachen möchten.For example, in a test environment, you may want to monitor a different queue or blob storage container.

Bindungsausdrücke für App-Einstellungen werden anders dargestellt als andere Bindungsausdrücke: Sie sind von Prozentzeichen anstatt von geschweiften Klammern umschlossen.App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. Wenn der Pfad der Blobausgabebindung z.B. %Environment%/newblob.txt und der Wert der App-Einstellung Environment lautet Development, wird ein Blob im Container Development erstellt.For example if the blob output binding path is %Environment%/newblob.txt and the Environment app setting value is Development, a blob will be created in the Development container.

Beim lokalen Ausführen einer Funktion werden die App-Einstellungen aus der Datei local.settings.json verwendet.When a function is running locally, app setting values come from the local.settings.json file.

Die Eigenschaft connection von Triggern und Bindungen ist ein Sonderfall, denn für sie werden Werte automatisch als App-Einstellungen ohne Prozentzeichen aufgelöst.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

Im folgenden Beispiel ist ein Azure Queue Storage-Trigger gezeigt, in dem die App-Einstellung %input-queue-name% verwendet wird, um die Warteschlange anzugeben, für die die Auslösung erfolgen werden soll.The following example is an Azure Queue Storage trigger that uses an app setting %input-queue-name% to define the queue to trigger on.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input-queue-name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

Sie können den gleichen Ansatz auch in Klassenbibliotheken verwenden:You can use the same approach in class libraries:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input-queue-name%")]string myQueueItem, 
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

Name der TriggerdateiTrigger file name

Der path für einen Blob-Trigger kann ein Muster sein, mit dem Sie auf den Namen des auslösenden Blobs in anderen Bindungen und Funktionscode verweisen.The path for a Blob trigger can be a pattern that lets you refer to the name of the triggering blob in other bindings and function code. Das Muster kann auch Filterkriterien enthalten, die angeben, welche Blobs einen Funktionsaufruf auslösen können.The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

Das Muster path für die Blobtriggerbindung im folgenden Beispiel ist sample-images/{filename}. Sie erstellt einen Bindungsausdruck mit dem Namen filename:For example, in the following Blob trigger binding, the path pattern is sample-images/{filename}, which creates a binding expression named filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

Der Ausdruck filename kann dann in einer Ausgabebindung verwendet werden, um den Namen des erstellten Blobs anzugeben:The expression filename can then be used in an output binding to specify the name of the blob being created:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

Der Funktionscode hat Zugriff auf diesen Wert, da er filename als Parametername verwendet:Function code has access to this same value by using filename as a parameter name:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)  
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
} 

Sie haben auch die Möglichkeit, Bindungsausdrücke und -muster für Attribute in Klassenbibliotheken zu verwenden.The same ability to use binding expressions and patterns applies to attributes in class libraries. Im folgenden Beispiel sind die Parameter des Attributkonstruktors dieselben path-Werte wie in den vorigen Beispielen für function.json:In the following example, the attribute constructor parameters are the same path values as the preceding function.json examples:

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger log)
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
}

Sie können auch Ausdrücke für Teile des Dateinamens erstellen, z.B. die Erweiterung.You can also create expressions for parts of the file name such as the extension. Weitere Informationen zum Verwenden von Ausdrücken und Mustern in der Blob-Pfadzeichenfolge finden Sie im Artikel zu Azure Blob Storage-Bindungen.For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

Metadaten für TriggerTrigger metadata

Viele Trigger stellen zusätzlich zur Datennutzlast (z.B. der Inhalt der Warteschlangennachricht, von der eine Funktion ausgelöst wurde) weitere Metadatenwerte bereit.In addition to the data payload provided by a trigger (such as the content of the queue message that triggered a function), many triggers provide additional metadata values. Diese Werte können als Eingabeparameter in C# und F# oder als Eigenschaften für das context.bindings-Objekt in JavaScript verwendet werden.These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

Beispielsweise unterstützt ein Azure Queue Storage-Trigger die folgenden Eigenschaften:For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigger – Auslösen von Nachrichteninhalt, wenn gültige ZeichenfolgeQueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • IdId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

Der Zugriff auf diese Metadatenwerte ist über die function.json-Dateieigenschaften möglich.These metadata values are accessible in function.json file properties. Angenommen, Sie verwenden einen Warteschlangentrigger und die Warteschlangennachricht enthält den Namen eines Blobs, den Sie lesen möchten.For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. In der function.json-Datei können Sie die Metadateneigenschaft queueTrigger in der Blobeigenschaft path verwenden, wie im folgenden Beispiel gezeigt:In the function.json file, you can use queueTrigger metadata property in the blob path property, as shown in the following example:

  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]

Details der Metadateneigenschaften für jeden Trigger sind im entsprechenden Referenzartikel beschrieben.Details of metadata properties for each trigger are described in the corresponding reference article. Ein Beispiel finden Sie unter Warteschlangentrigger-Metadaten.For an example, see queue trigger metadata. Dokumentation ist auch im Portal auf der Registerkarte Integrieren im Abschnitt Dokumentation verfügbar, der sich unter dem Bereich für Bindungskonfigurationen befindet.Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

JSON-NutzlastenJSON payloads

Wenn eine Triggernutzlast JSON ist, finden Sie die Eigenschaften in der Konfiguration für andere Bindungen in der gleichen Funktion und im gleichen Funktionscode.When a trigger payload is JSON, you can refer to its properties in configuration for other bindings in the same function and in function code.

Das folgende Beispiel zeigt die Datei function.json für eine Webhook-Funktion, die einen Blobnamen im JSON-Format erhält: {"BlobName":"HelloWorld.txt"}.The following example shows the function.json file for a webhook function that receives a blob name in JSON: {"BlobName":"HelloWorld.txt"}. Eine Blobeingabebindung liest den Blob, und die HTTP-Ausgabebindung gibt den Blob-Inhalt in der HTTP-Antwort zurück.A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. Beachten Sie, dass die Blob-Eingabebindung den Blobnamen abruft, indem sie direkt auf die BlobName-Eigenschaft verweist ("path": "strings/{BlobName}")Notice that the Blob input binding gets the blob name by referring directly to the BlobName property ("path": "strings/{BlobName}")

{
  "bindings": [
    {
      "name": "info",
      "type": "httpTrigger",
      "direction": "in",
      "webHookType": "genericJson"
    },
    {
      "name": "blobContents",
      "type": "blob",
      "direction": "in",
      "path": "strings/{BlobName}",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ]
}

Damit das in C# und F# funktioniert, benötigen Sie eine Klasse, die die zu deserialisierenden Felder im folgenden Beispiel definiert:For this to work in C# and F#, you need a class that defines the fields to be deserialized, as in the following example:

using System.Net;
using Microsoft.Extensions.Logging;

public class BlobInfo
{
    public string BlobName { get; set; }
}
  
public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents, ILogger log)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    log.LogInformation($"Processing: {info.BlobName}");

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

In JavaScript wird JSON-Deserialisierung automatisch ausgeführt.In JavaScript, JSON deserialization is automatically performed.

module.exports = function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
    context.done();
}

PunktnotationDot notation

Wenn einige der Eigenschaften in Ihrer JSON-Nutzlast Objekte mit Eigenschaften sind, finden Sie diese durch die Punktnotation.If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. Nehmen wir beispielsweise an, dass Ihr JSON wie folgt aussieht:For example, suppose your JSON looks like this:

{
  "BlobName": {
    "FileName":"HelloWorld",
    "Extension":"txt"
  }
}

Sie können direkt auf FileName verweisen: BlobName.FileName.You can refer directly to FileName as BlobName.FileName. In diesem JSON-Format sieht die Eigenschaft path im vorherigen Beispiel folgendermaßen aus:With this JSON format, here's what the path property in the preceding example would look like:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

In C# benötigen Sie zwei Klassen:In C#, you would need two classes:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

Erstellen von GUIDsCreate GUIDs

Der Bindungsausdruck {rand-guid} erstellt eine GUID.The {rand-guid} binding expression creates a GUID. Der folgende Blobpfad in einer function.json-Datei erstellt einen Blob mit einem Namen wie 50710cb5-84b9 - 4D 87 9d 83-a03d6976a682.txt.The following blob path in a function.json file creates a blob with a name like 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}"
}

Die aktuelle ZeitCurrent time

Der Bindungsausdruck DateTime wird in DateTime.UtcNow aufgelöst.The binding expression DateTime resolves to DateTime.UtcNow. Der folgende Blobpfad in einer function.json-Datei erstellt einen Blob mit einem Namen wie 2018-02-16T17-59-55Z.txt.The following blob path in a function.json file creates a blob with a name like 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}"
}

Binden zur LaufzeitBinding at runtime

In C# und anderen .NET-Sprachen können Sie ein imperatives Bindungsmuster verwenden, im Gegensatz zu den deklarativen Bindungen in function.json und Attributen.In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json and attributes. Imperative Bindung eignet sich, wenn Bindungsparameter zur Laufzeit statt zur Entwurfszeit berechnet werden müssen.Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. Weitere Informationen finden Sie in der C#-Entwicklerreferenz oder in der C#-Skriptentwicklerreferenz.To learn more, see the C# developer reference or the C# script developer reference.

Nächste SchritteNext steps