Bindingsexpressiepatronen in Azure Functions

Artikel
10/17/2024

Een van de krachtigste functies van triggers en bindingen is bindingexpressies. In het function.json-bestand en in functieparameters en -code kunt u expressies gebruiken die worden omgezet in waarden uit verschillende bronnen.

De meeste expressies worden geïdentificeerd door ze tussen accolades te plaatsen. In een wachtrijtriggerfunctie {queueTrigger} wordt bijvoorbeeld omgezet in de tekst van het wachtrijbericht. Als de path eigenschap voor een blobuitvoerbinding is container/{queueTrigger} en de functie wordt geactiveerd door een wachtrijbericht HelloWorld, wordt er een blob met de naam HelloWorld gemaakt.

Typen bindingexpressies

App-instellingen
Bestandsnaam activeren
Metagegevens activeren
JSON-nettoladingen
Nieuwe GUID
Huidige datum en tijd

Bindingexpressies - app-instellingen

Als best practice moeten geheimen en verbindingsreeks s worden beheerd met behulp van app-instellingen, in plaats van configuratiebestanden. Dit beperkt de toegang tot deze geheimen en maakt het veilig om bestanden zoals function.json op te slaan in openbare opslagplaatsen voor broncodebeheer.

App-instellingen zijn ook handig wanneer u de configuratie wilt wijzigen op basis van de omgeving. In een testomgeving wilt u bijvoorbeeld een andere wachtrij of blobopslagcontainer bewaken.

Bindingexpressies voor app-instellingen worden anders geïdentificeerd dan andere bindingexpressies: ze worden verpakt in procenttekens in plaats van accolades. Als het bindingspad voor blobuitvoer bijvoorbeeld is %Environment%/newblob.txt en de waarde van de Environment app-instelling is Development, wordt er een blob gemaakt in de Development container.

Wanneer een functie lokaal wordt uitgevoerd, komen app-instellingswaarden uit het local.settings.json-bestand .

Notitie

De connection eigenschap van triggers en bindingen is een speciaal geval en lost automatisch waarden op als app-instellingen, zonder procenttekens.

Het volgende voorbeeld is een Azure Queue Storage-trigger die gebruikmaakt van een app-instelling %input_queue_name% om de wachtrij te definiëren waarop moet worden geactiveerd.

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

U kunt dezelfde methode gebruiken in klassebibliotheken:

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

Trigger-bestandsnaam

Het path voor een blobtrigger kan een patroon zijn waarmee u kunt verwijzen naar de naam van de triggerende blob in andere bindingen en functiecode. Het patroon kan ook filtercriteria bevatten die aangeven welke blobs een functie-aanroep kunnen activeren.

In de volgende blobtriggerbinding is sample-images/{filename}het patroon bijvoorbeeld , waarmee een bindingexpressie met de path naam wordt gemaaktfilename:

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

De expressie filename kan vervolgens worden gebruikt in een uitvoerbinding om de naam op te geven van de blob die wordt gemaakt:

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

Functiecode heeft toegang tot dezelfde waarde met behulp van filename een parameternaam:

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

Dezelfde mogelijkheid om bindingexpressies en patronen te gebruiken, is van toepassing op kenmerken in klassebibliotheken. In het volgende voorbeeld zijn de parameters van de kenmerkconstructor dezelfde path waarden als de voorgaande function.json voorbeelden:

[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}");
    // ...
}

U kunt ook expressies maken voor onderdelen van de bestandsnaam. In het volgende voorbeeld wordt de functie alleen geactiveerd voor bestandsnamen die overeenkomen met een patroon: anyname-anyfile.csv

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

Zie de naslaginformatie over de blob-blobbinding voor meer informatie over het gebruik van expressies en patronen in de tekenreeks van het blobpad.

Trigger-metagegevens

Naast de nettolading van gegevens die wordt geleverd door een trigger (zoals de inhoud van het wachtrijbericht dat een functie heeft geactiveerd), bieden veel triggers aanvullende metagegevenswaarden. Deze waarden kunnen worden gebruikt als invoerparameters in C# en F# of eigenschappen voor het context.bindings object in JavaScript.

Een Azure Queue Storage-trigger ondersteunt bijvoorbeeld de volgende eigenschappen:

QueueTrigger - berichtinhoud activeren als een geldige tekenreeks
DequeueCount
ExpirationTime
ID
InsertionTime
NextVisibleTime
PopReceipt

Deze metagegevenswaarden zijn toegankelijk in function.json bestandseigenschappen. Stel dat u een wachtrijtrigger gebruikt en het wachtrijbericht de naam bevat van een blob die u wilt lezen. In het function.json-bestand kunt u metagegevenseigenschap in de blob-eigenschap path gebruikenqueueTrigger, zoals wordt weergegeven in het volgende voorbeeld:

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

Details van metagegevenseigenschappen voor elke trigger worden beschreven in het bijbehorende referentieartikel. Zie bijvoorbeeld metagegevens van wachtrijtriggers. Documentatie is ook beschikbaar op het tabblad Integreren van de portal, in de sectie Documentatie onder het gebied bindingsconfiguratie.

JSON-nettoladingen

In sommige scenario's kunt u verwijzen naar de eigenschappen van de nettolading van de trigger in de configuratie voor andere bindingen in dezelfde functie en in functiecode. Dit vereist dat de nettolading van de trigger JSON is en kleiner is dan een drempelwaarde die specifiek is voor elke trigger. Normaal gesproken moet de grootte van de nettolading kleiner zijn dan 100 MB, maar u moet de referentie-inhoud voor elke trigger controleren. Het gebruik van eigenschappen van de triggerpayload kan van invloed zijn op de prestaties van uw toepassing en het triggerparametertype kan eenvoudige typen zijn, zoals tekenreeksen of een aangepast objecttype dat JSON-gegevens vertegenwoordigt. Het kan niet worden gebruikt met streams, clients of andere SDK-typen.

In het volgende voorbeeld ziet u het function.json-bestand voor een webhookfunctie die een blobnaam ontvangt in JSON: {"BlobName":"HelloWorld.txt"}. Een Blob-invoerbinding leest de blob en de HTTP-uitvoerbinding retourneert de blob-inhoud in het HTTP-antwoord. U ziet dat de blob-invoerbinding de naam van de blob ophaalt door rechtstreeks naar de BlobName eigenschap ("path": "strings/{BlobName}") te verwijzen

{
  "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"
    }
  ]
}

Als u dit wilt doen in C# en F#, hebt u een klasse nodig waarmee de velden worden gedeserialiseerd, zoals in het volgende voorbeeld:

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 wordt JSON-deserialisatie automatisch uitgevoerd.

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

Punt notatie

Als sommige eigenschappen in uw JSON-nettolading objecten met eigenschappen zijn, kunt u deze rechtstreeks raadplegen met behulp van punt(.) notatie. Deze notatie werkt niet voor Azure Cosmos DB - of Table Storage-bindingen .

Stel dat uw JSON er als volgt uitziet:

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

U kunt rechtstreeks verwijzen naar FileName BlobName.FileName. Met deze JSON-indeling ziet de path eigenschap in het voorgaande voorbeeld er als volgt uit:

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

In C# hebt u twee klassen nodig:

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

GUID's maken

Met de {rand-guid} bindingsexpressie wordt een GUID gemaakt. Met het volgende blobpad in een function.json bestand wordt een blob gemaakt met een naam zoals 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

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

Huidige tijd

De bindingexpressie DateTime wordt omgezet in DateTime.UtcNow. Met het volgende blobpad in een function.json bestand wordt een blob gemaakt met een naam zoals 2018-02-16T17-59-55Z.txt.

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

Binding tijdens runtime

In C# en andere .NET-talen kunt u een imperatief bindingspatroon gebruiken in plaats van de declaratieve bindingen in function.json en kenmerken. Imperatieve binding is handig wanneer bindingsparameters tijdens runtime moeten worden berekend in plaats van ontwerptijd. Zie de C#-naslaginformatie voor ontwikkelaars of de naslaginformatie voor C#-scriptontwikkelaars voor meer informatie.

Concepten van Azure Functions-triggers en -bindingen

Delen via

Bindingsexpressiepatronen in Azure Functions

Bindingexpressies - app-instellingen

Trigger-bestandsnaam

Trigger-metagegevens

JSON-nettoladingen

Punt notatie

GUID's maken

Huidige tijd

Binding tijdens runtime

Feedback

Aanvullende resources

Delen via

Bindingsexpressiepatronen in Azure Functions

Bindingexpressies - app-instellingen

Trigger-bestandsnaam

Trigger-metagegevens

JSON-nettoladingen

Punt notatie

GUID's maken

Huidige tijd

Binding tijdens runtime

Gerelateerde inhoud

Feedback

Aanvullende resources