Azure Functions mönster för bindningsuttryck

Artikel
09/03/2023

En av de mest kraftfulla funktionerna i utlösare och bindningar är bindningsuttryck. I filen function.json och i funktionsparametrar och kod kan du använda uttryck som matchar värden från olika källor.

De flesta uttryck kan identifieras genom att de omsluts av klammerparenteser. I till exempel en köutlösarfunktion {queueTrigger} matchas till kömeddelandetexten. path Om egenskapen för en blobutdatabindning är container/{queueTrigger} och funktionen utlöses av ett kömeddelande HelloWorldskapas en blob med namnet HelloWorld .

Typer av bindande uttryck

Appinställningar
Filnamn för utlösare
Utlösarmetadata
JSON-nyttolaster
Ny GUID
Aktuell dag och tid

Bindningsuttryck – appinställningar

Vi rekommenderar att hemligheter och anslutningssträngar hanteras med appinställningar i stället för konfigurationsfiler. Detta begränsar åtkomsten till dessa hemligheter och gör det säkert att lagra filer som function.json på lagringsplatser för offentlig källkontroll.

Appinställningar är också användbara när du vill ändra konfigurationen baserat på miljön. I en testmiljö kanske du till exempel vill övervaka en annan kö eller bloblagringscontainer.

Bindningsuttryck för appinställningar identifieras annorlunda än andra bindningsuttryck: de omsluts i procenttecken i stället för klammerparenteser. Om bindningssökvägen för blobutdata till exempel är %Environment%/newblob.txt och appinställningsvärdet Environment är Developmentskapas en blob i containern Development .

När en funktion körs lokalt kommer appinställningsvärden från filen local.settings.json .

Anteckning

Egenskapen connection för utlösare och bindningar är ett specialfall och löser automatiskt värden som appinställningar, utan procenttecken.

Följande exempel är en Azure Queue Storage-utlösare som använder en appinställning %input_queue_name% för att definiera kön som ska utlösas.

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

Du kan använda samma metod i klassbibliotek:

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

Filnamn för utlösare

path För en blob-utlösare kan vara ett mönster som gör att du kan referera till namnet på den utlösande bloben i andra bindningar och funktionskod. Mönstret kan också innehålla filtreringsvillkor som anger vilka blobar som kan utlösa ett funktionsanrop.

I följande blobutlösarbindning path är sample-images/{filename}till exempel mönstret , vilket skapar ett bindningsuttryck med namnet filename:

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

filename Uttrycket kan sedan användas i en utdatabindning för att ange namnet på bloben som skapas:

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

Funktionskoden har åtkomst till samma värde med hjälp filename av som ett parameternamn:

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

Samma möjlighet att använda bindningsuttryck och mönster gäller för attribut i klassbibliotek. I följande exempel är attributkonstruktorparametrarna samma path värden som föregående function.json-exempel :

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

Du kan också skapa uttryck för delar av filnamnet. I följande exempel utlöses funktionen endast på filnamn som matchar ett mönster: anyname-anyfile.csv

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

Mer information om hur du använder uttryck och mönster i blobsökvägssträngen finns i referensen för Storage-blobbindning.

Utlösarmetadata

Förutom datanyttolasten som tillhandahålls av en utlösare (till exempel innehållet i kömeddelandet som utlöste en funktion) tillhandahåller många utlösare ytterligare metadatavärden. Dessa värden kan användas som indataparametrar i C# och F# eller egenskaper för context.bindings objektet i JavaScript.

Till exempel stöder en Azure Queue Storage-utlösare följande egenskaper:

QueueTrigger – utlöser meddelandeinnehåll om en giltig sträng
DequeueCount
ExpirationTime
Id
InsertionTime
NextVisibleTime
PopReceipt

Dessa metadatavärden är tillgängliga i egenskaperna för filen function.json . Anta till exempel att du använder en köutlösare och att kömeddelandet innehåller namnet på en blob som du vill läsa. I filen function.json kan du använda queueTrigger metadataegenskapen i blobegenskapen path , som du ser i följande exempel:

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

Information om metadataegenskaper för varje utlösare beskrivs i motsvarande referensartikel. Ett exempel finns i metadata för köutlösare. Dokumentationen finns också på fliken Integrera i portalen i avsnittet Dokumentation under bindningskonfigurationsområdet.

JSON-nyttolaster

I vissa fall kan du referera till utlösarnyttolastens egenskaper i konfigurationen för andra bindningar i samma funktion och i funktionskoden. Detta kräver att utlösarnyttolasten är JSON och är mindre än ett tröskelvärde som är specifikt för varje utlösare. Normalt måste nyttolaststorleken vara mindre än 100 MB, men du bör kontrollera referensinnehållet för varje utlösare. Användning av utlösarnyttolastegenskaper kan påverka programmets prestanda och tvingar utlösarparametertypen att vara enkla typer som strängar eller en anpassad objekttyp som representerar JSON-data. Den kan inte användas med strömmar, klienter eller andra SDK-typer.

I följande exempel visas filen function.json för en webhook-funktion som tar emot ett blobnamn i JSON: {"BlobName":"HelloWorld.txt"}. En blobindatabindning läser bloben och HTTP-utdatabindningen returnerar blobinnehållet i HTTP-svaret. Observera att blobindatabindningen hämtar blobnamnet genom att referera direkt till BlobName egenskapen ("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"
    }
  ]
}

För att detta ska fungera i C# och F# behöver du en klass som definierar fälten som ska deserialiseras, som i följande exempel:

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

I JavaScript utförs JSON-deserialisering automatiskt.

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

Punktnotation

Om vissa av egenskaperna i JSON-nyttolasten är objekt med egenskaper kan du referera till dem direkt med punktnotation (.). Den här notationen fungerar inte för Azure Cosmos DB - eller Table Storage-bindningar .

Anta till exempel att din JSON ser ut så här:

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

Du kan referera direkt till FileName som BlobName.FileName. Med det här JSON-formatet skulle egenskapen i föregående exempel se ut så här path :

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

I C# behöver du två klasser:

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

Skapa GUID

Bindningsuttrycket {rand-guid} skapar ett GUID. Följande blobsökväg i en function.json fil skapar en blob med ett namn som 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

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

Aktuell tid

Bindningsuttrycket DateTime matchas till DateTime.UtcNow. Följande blobsökväg i en function.json fil skapar en blob med ett namn som 2018-02-16T17-59-55Z.txt.

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

Bindning vid körning

I C# och andra .NET-språk kan du använda ett imperativt bindningsmönster, till skillnad från deklarativa bindningar i function.json och attribut. Imperativ bindning är användbart när bindningsparametrar behöver beräknas vid körning i stället för designtid. Mer information finns i C#-utvecklarreferensen eller C#-skriptets utvecklarreferens.

Nästa steg

Använda azure-funktionens returvärde

Dela via