Wzorce wyrażeń powiązań usługi Azure Functions

Artykuł
10/16/2024

Jedną z najbardziej zaawansowanych funkcji wyzwalaczy i powiązań jest wyrażenie powiązania. W pliku function.json i w parametrach funkcji i kodzie można użyć wyrażeń, które są rozpoznawane jako wartości z różnych źródeł.

Większość wyrażeń identyfikuje się przez umieszczenie ich w nawiasach klamrowych. Na przykład w funkcji {queueTrigger} wyzwalacza kolejki jest rozpoznawany tekst komunikatu kolejki. path Jeśli właściwość powiązania wyjściowego obiektu blob jest container/{queueTrigger} i funkcja jest wyzwalana przez komunikat HelloWorldkolejki, tworzony jest obiekt blob o nazwieHelloWorld.

Typy wyrażeń powiązania

Ustawienia aplikacji
Nazwa pliku wyzwalacza
Metadane wyzwalacza
Ładunki JSON
Nowy identyfikator GUID
Bieżąca data i godzina

Wyrażenia powiązań — ustawienia aplikacji

Najlepszym rozwiązaniem jest zarządzanie wpisami tajnymi i parametry połączenia przy użyciu ustawień aplikacji, a nie plików konfiguracji. Ogranicza to dostęp do tych wpisów tajnych i umożliwia bezpieczne przechowywanie plików, takich jak function.json w repozytoriach kontroli źródła publicznego.

Ustawienia aplikacji są również przydatne za każdym razem, gdy chcesz zmienić konfigurację na podstawie środowiska. Na przykład w środowisku testowym możesz monitorować inny kontener kolejki lub magazynu obiektów blob.

Wyrażenia powiązań ustawień aplikacji są identyfikowane inaczej niż inne wyrażenia powiązań: są one opakowane w znaki procentowe, a nie nawiasy klamrowe. Jeśli na przykład ścieżka powiązania wyjściowego obiektu blob to %Environment%/newblob.txt , a Environment wartość ustawienia aplikacji to Development, w kontenerze Development zostanie utworzony obiekt blob.

Gdy funkcja jest uruchomiona lokalnie, wartości ustawień aplikacji pochodzą z pliku local.settings.json .

Uwaga

Właściwość connection wyzwalaczy i powiązań jest specjalnym przypadkiem i automatycznie rozpoznaje wartości jako ustawienia aplikacji bez znaków procentu.

Poniższy przykład to wyzwalacz usługi Azure Queue Storage, który używa ustawienia %input_queue_name% aplikacji do zdefiniowania kolejki do wyzwolenia.

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

Możesz użyć tego samego podejścia w bibliotekach klas:

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

Nazwa pliku wyzwalacza

Wyzwalacz path obiektu blob może być wzorcem, który umożliwia odwoływanie się do nazwy wyzwalającego obiektu blob w innych powiązaniach i kodzie funkcji. Wzorzec może również zawierać kryteria filtrowania, które określają, które obiekty blob mogą wyzwalać wywołanie funkcji.

Na przykład w poniższym powiązaniu path wyzwalacza obiektu blob wzorzec to sample-images/{filename}, który tworzy wyrażenie powiązania o nazwie filename:

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

Wyrażenie filename można następnie użyć w powiązaniu wyjściowym, aby określić nazwę tworzonego obiektu blob:

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

Kod funkcji ma dostęp do tej samej wartości przy użyciu filename nazwy parametru:

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

Ta sama możliwość używania wyrażeń powiązań i wzorców ma zastosowanie do atrybutów w bibliotekach klas. W poniższym przykładzie parametry konstruktora atrybutu są tymi samymi path wartościami co poprzednie function.json przykłady:

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

Można również tworzyć wyrażenia dla części nazwy pliku. W poniższym przykładzie funkcja jest wyzwalana tylko dla nazw plików, które pasują do wzorca: anyname-anyfile.csv

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

Aby uzyskać więcej informacji na temat używania wyrażeń i wzorców w ciągu ścieżki obiektu blob, zobacz dokumentację powiązania obiektu blob usługi Storage.

Metadane wyzwalacza

Oprócz ładunku danych dostarczonego przez wyzwalacz (na przykład zawartość komunikatu kolejki, który wyzwolił funkcję), wiele wyzwalaczy udostępnia dodatkowe wartości metadanych. Te wartości mogą być używane jako parametry wejściowe w języku C# i F# lub właściwości obiektu context.bindings w języku JavaScript.

Na przykład wyzwalacz usługi Azure Queue Storage obsługuje następujące właściwości:

QueueTrigger — wyzwalanie zawartości komunikatu, jeśli prawidłowy ciąg
DequeueCount
Czas wygaśnięcia
Id
InsertionTime
NextVisibleTime
PopReceipt

Te wartości metadanych są dostępne we właściwościach function.json pliku. Załóżmy na przykład, że używasz wyzwalacza kolejki, a komunikat kolejki zawiera nazwę obiektu blob, który chcesz odczytać. W pliku function.json można użyć queueTrigger właściwości metadanych we właściwości obiektu blobpath, jak pokazano w poniższym przykładzie:

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

Szczegółowe informacje o właściwościach metadanych dla każdego wyzwalacza opisano w odpowiednim artykule referencyjnym. Aby zapoznać się z przykładem, zobacz metadane wyzwalacza kolejki. Dokumentacja jest również dostępna na karcie Integracja portalu w sekcji Dokumentacja poniżej obszaru konfiguracji powiązania.

Ładunki JSON

W niektórych scenariuszach można odwołać się do właściwości ładunku wyzwalacza w konfiguracji dla innych powiązań w tej samej funkcji i w kodzie funkcji. Wymaga to, aby ładunek wyzwalacza był JSON i jest mniejszy niż próg specyficzny dla każdego wyzwalacza. Zazwyczaj rozmiar ładunku musi być mniejszy niż 100 MB, ale należy sprawdzić zawartość referencyjną dla każdego wyzwalacza. Użycie właściwości ładunku wyzwalacza może mieć wpływ na wydajność aplikacji i wymusza, aby typ parametru wyzwalacza był prostymi typami, takimi jak ciągi lub niestandardowy typ obiektu reprezentujący dane JSON. Nie można jej używać ze strumieniami, klientami ani innymi typami zestawu SDK.

W poniższym przykładzie przedstawiono plik function.json dla funkcji elementu webhook, która odbiera nazwę obiektu blob w formacie JSON: {"BlobName":"HelloWorld.txt"}. Powiązanie wejściowe obiektu blob odczytuje obiekt blob, a powiązanie wyjściowe HTTP zwraca zawartość obiektu blob w odpowiedzi HTTP. Zwróć uwagę, że powiązanie wejściowe obiektu blob pobiera nazwę obiektu blob, odwołując się bezpośrednio do BlobName właściwości ("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"
    }
  ]
}

W tym celu należy pracować w językach C# i F#, która definiuje pola do deserializacji, jak w poniższym przykładzie:

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

W języku JavaScript deserializacja JSON jest wykonywana automatycznie.

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

Notacja kropkowa

Jeśli niektóre właściwości w ładunku JSON są obiektami z właściwościami, możesz odwołać się do tych bezpośrednio za pomocą notacji kropkowej (.). Ta notacja nie działa w przypadku powiązań usługi Azure Cosmos DB ani usługi Table Storage .

Załóżmy na przykład, że kod JSON wygląda następująco:

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

Możesz odwoływać się bezpośrednio do FileName .BlobName.FileName W tym formacie JSON poniżej path przedstawiono właściwość w poprzednim przykładzie:

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

W języku C#potrzebne byłyby dwie klasy:

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

Tworzenie identyfikatorów GUID

Wyrażenie {rand-guid} powiązania tworzy identyfikator GUID. Następująca ścieżka obiektu blob w function.json pliku tworzy obiekt blob o nazwie takiej jak 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

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

Bieżący czas

Wyrażenie DateTime powiązania jest rozpoznawane jako DateTime.UtcNow. Następująca ścieżka obiektu blob w function.json pliku tworzy obiekt blob o nazwie takiej jak 2018-02-16T17-59-55Z.txt.

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

Wiązanie w czasie wykonywania

W języku C# i innych językach platformy .NET można użyć wzorca powiązania imperatywnego, w przeciwieństwie do powiązań deklaratywnych w function.json i atrybutach. Powiązanie imperatywne jest przydatne, gdy parametry powiązania muszą być obliczane w czasie wykonywania, a nie w czasie projektowania. Aby dowiedzieć się więcej, zobacz dokumentację dla deweloperów języka C# lub dokumentację dla deweloperów skryptów języka C#.

Pojęcia powiązań i wyzwalaczy usługi Azure Functions

Udostępnij za pośrednictwem

Wzorce wyrażeń powiązań usługi Azure Functions

Wyrażenia powiązań — ustawienia aplikacji

Nazwa pliku wyzwalacza

Metadane wyzwalacza

Ładunki JSON

Notacja kropkowa

Tworzenie identyfikatorów GUID

Bieżący czas

Wiązanie w czasie wykonywania

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Wzorce wyrażeń powiązań usługi Azure Functions

Wyrażenia powiązań — ustawienia aplikacji

Nazwa pliku wyzwalacza

Metadane wyzwalacza

Ładunki JSON

Notacja kropkowa

Tworzenie identyfikatorów GUID

Bieżący czas

Wiązanie w czasie wykonywania

Powiązana zawartość

Opinia

Dodatkowe zasoby