Azure Functions-Muster für Bindungsausdrücke

  • Artikel

Eines der leistungsstärksten Merkmale von Triggern und Bindungen sind Bindungsausdrücke. 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.

Die meisten Ausdrücke sind von geschweiften Klammern umschlossen. Beispielsweise wird in einer Trigger-Funktion für die Eingabewarteschlange {queueTrigger} in den Text der Warteschlangenmeldung aufgelöst. 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.

Arten von Bindungsausdrücken

Bindungsausdrücke – App-Einstellungen

Es hat sich bewährt, Geheimnisse und Verbindungszeichenfolgen nicht in Konfigurationsdateien, sondern über App-Einstellungen zu verwalten. 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.

App-Einstellungen sind auch nützlich, wenn Sie die jeweilige Konfiguration entsprechend der Umgebung ändern möchten. Beispielsweise kann es sein, dass Sie in einer Testumgebung eine andere Warteschlange oder einen anderen Blob Storage-Container überwachen möchten.

Bindungsausdrücke für App-Einstellungen werden anders dargestellt als andere Bindungsausdrücke: Sie sind von Prozentzeichen anstatt von geschweiften Klammern umschlossen. 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.

Beim lokalen Ausführen einer Funktion werden die App-Einstellungen aus der Datei local.settings.json verwendet.

Hinweis

Die Eigenschaft connection von Triggern und Bindungen ist ein Sonderfall, denn für sie werden Werte automatisch als App-Einstellungen ohne Prozentzeichen aufgelöst.

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.

{
  "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:

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

Name der Triggerdatei

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. Das Muster kann auch Filterkriterien enthalten, die angeben, welche Blobs einen Funktionsaufruf auslösen können.

Das Muster path für die Blobtriggerbindung im folgenden Beispiel ist sample-images/{filename}. Sie erstellt einen Bindungsausdruck mit dem Namen 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:

    ...
    {
      "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:

// 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. Im folgenden Beispiel sind die Parameter des Attributkonstruktors dieselben path-Werte wie in den vorigen Beispielen für path:

[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. Im folgenden Beispiel wird die Funktion nur für Dateinamen ausgelöst, die einem Muster entsprechen: anyname-anyfile.csv

{
    "name": "myBlob",
    "type": "blobTrigger",
    "direction": "in",
    "path": "testContainerName/{date}-{filetype}.csv",
    "connection": "OrderStorageConnection"
}

Weitere Informationen zum Verwenden von Ausdrücken und Mustern in der Blob-Pfadzeichenfolge finden Sie im Artikel zu Azure Blob Storage-Bindungen.

Metadaten für Trigger

Viele Trigger stellen zusätzlich zur Datennutzlast (z.B. der Inhalt der Warteschlangennachricht, von der eine Funktion ausgelöst wurde) weitere Metadatenwerte bereit. Diese Werte können als Eingabeparameter in C# und F# oder als Eigenschaften für das context.bindings-Objekt in JavaScript verwendet werden.

Beispielsweise unterstützt ein Azure Queue Storage-Trigger die folgenden Eigenschaften:

  • QueueTrigger – Auslösen von Nachrichteninhalt, wenn gültige Zeichenfolge
  • DequeueCount
  • ExpirationTime
  • Id
  • InsertionTime
  • NextVisibleTime
  • PopReceipt

Der Zugriff auf diese Metadatenwerte ist über die function.json-Dateieigenschaften möglich. Angenommen, Sie verwenden einen Warteschlangentrigger und die Warteschlangennachricht enthält den Namen eines Blobs, den Sie lesen möchten. In der function.json-Datei können Sie die Metadateneigenschaft queueTrigger in der Blobeigenschaft path verwenden, wie im folgenden Beispiel gezeigt:

{
  "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. Ein Beispiel finden Sie unter Warteschlangentrigger-Metadaten. Dokumentation ist auch im Portal auf der Registerkarte Integrieren im Abschnitt Dokumentation verfügbar, der sich unter dem Bereich für Bindungskonfigurationen befindet.

JSON-Nutzlasten

In einigen Szenarien können Sie in der Konfiguration für andere Bindungen in derselben Funktion und im Funktionscode auf die Eigenschaften der Triggernutzdaten verweisen. Dies erfordert, dass die Triggernutzdaten JSON sind und kleiner als ein Schwellenwert sind, der für jeden Trigger spezifisch ist. In der Regel muss die Nutzdatengröße kleiner als 100 MB sein, aber Sie sollten den Verweisinhalt für jeden Trigger überprüfen. Die Verwendung von Eigenschaften der Triggernutzdaten kann sich auf die Leistung Ihrer Anwendung auswirken und zwingt den Triggerparametertyp zu einfachen Typen wie Zeichenfolgen oder einem benutzerdefinierten Objekttyp, der JSON-Daten darstellt. Sie können nicht mit Streams, Clients oder anderen SDK-Typen verwendet werden.

Das folgende Beispiel zeigt die Datei function.json für eine Webhook-Funktion, die einen Blobnamen im JSON-Format erhält: {"BlobName":"HelloWorld.txt"}. Eine Blobeingabebindung liest den Blob, und die HTTP-Ausgabebindung gibt den Blob-Inhalt in der HTTP-Antwort zurück. Beachten Sie, dass die Blob-Eingabebindung den Blobnamen abruft, indem sie direkt auf die BlobName-Eigenschaft verweist ("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:

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.

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

Punktnotation

Wenn einige der Eigenschaften in Ihren JSON-Nutzdaten Objekte mit Eigenschaften sind, finden Sie diese durch die Punktnotation (.). Diese Notation funktioniert nicht für Azure Cosmos DB- oder Tabellenspeicherbindungen.

Nehmen wir beispielsweise an, dass Ihr JSON wie folgt aussieht:

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

Sie können direkt auf FileName verweisen: BlobName.FileName. In diesem JSON-Format sieht die Eigenschaft path im vorherigen Beispiel folgendermaßen aus:

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

In C# benötigen Sie zwei Klassen:

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

Erstellen von GUIDs

Der Bindungsausdruck {rand-guid} erstellt eine GUID. Der folgende Blobpfad in einer function.json-Datei erstellt einen Blob mit einem Namen wie function.json.

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

Die aktuelle Zeit

Der Bindungsausdruck DateTime wird in DateTime.UtcNow aufgelöst. Der folgende Blobpfad in einer function.json-Datei erstellt einen Blob mit einem Namen wie function.json.

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

Binden zur Laufzeit

In C# und anderen .NET-Sprachen können Sie ein imperatives Bindungsmuster verwenden, im Gegensatz zu den deklarativen Bindungen in function.json und Attributen. Imperative Bindung eignet sich, wenn Bindungsparameter zur Laufzeit statt zur Entwurfszeit berechnet werden müssen. Weitere Informationen finden Sie in der C#-Entwicklerreferenz oder in der C#-Skriptentwicklerreferenz.

Zugehöriger Inhalt