Шаблоны выражений привязки функций AzureAzure Functions binding expression patterns

Одной из самых эффективных функций триггеров и привязок являются выражения привязки.One of the most powerful features of triggers and bindings is binding expressions. В файле function.json и в параметрах функции и коде можно использовать выражения, которые разрешаются в значения из различных источников.In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

Большинство выражений определяются путем их заключения в фигурные скобки.Most expressions are identified by wrapping them in curly braces. Например, в функции триггера очереди {queueTrigger} разрешается в текст сообщения очереди.For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. Если свойство path для выходной привязки большого двоичного объекта — container/{queueTrigger}, а функция активируется сообщением очереди HelloWorld, создается большой двоичный объект с именем HelloWorld.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.

Типы выражений привязкиTypes of binding expressions

Выражения привязки. Параметры приложенияBinding expressions - app settings

Для управления секретами и строками подключения рекомендуется использовать параметры приложения, а не файлы конфигурации.As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. Это ограничивает доступ к таким секретам и обеспечивает безопасное хранение файлов, таких как function.json, в общедоступном репозитории системы управления версиями.This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

Параметры приложений также удобно использовать при необходимости изменить конфигурации в соответствии со средой.App settings are also useful whenever you want to change configuration based on the environment. Например, в тестовой среде можно отслеживать другую очередь или контейнер хранилища BLOB-объектов.For example, in a test environment, you may want to monitor a different queue or blob storage container.

Выражения привязки параметров приложения определяются иначе, чем другие выражения привязки. Они заключены в символы процента, а не в фигурные скобки.App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. Например, если путь выходной привязки большого двоичного объекта — %Environment%/newblob.txt, а значение параметра приложения EnvironmentDevelopment, в контейнере Development будет создан большой двоичный объект.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.

Если функция выполняется локально, значения параметра приложения поступают из файла local.settings.json.When a function is running locally, app setting values come from the local.settings.json file.

Обратите внимание, что свойство connection триггеров и привязок является особым случаем и автоматически разрешает значения как параметры приложения без знаков процента.Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

Следующий пример представляет собой триггер хранилища очередей Azure. Этот триггер использует параметр приложения %input-queue-name%, чтобы определить очередь, для которой он должен срабатывать.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"
    }
  ]
}

Тот же подход можно использовать в библиотеках классов: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}");
}

Имя файла триггераTrigger file name

path для триггера большого двоичного объекта может быть шаблоном, который позволяет ссылаться на имя большого двоичного объекта, активирующего триггер, в других привязках и коде функции.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. Шаблон может также включать критерии фильтрации, которые определяют, какие большие двоичные объекты могут активировать вызов функции.The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

Например, в следующей привязке триггера большого двоичного объекта шаблон pathsample-images/{filename}, который создает выражение привязки с именем 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"
    },
    ...

Затем выражение filename можно использовать в выходной привязке для указания имени создаваемого большого двоичного объекта: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"
    }
  ],
}

Код функции получает доступ к тому же значению, используя filename в качестве имени параметра: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}");
    // ...
} 

Возможность применять выражения и шаблоны привязки распространяется и на атрибуты в библиотеке классов.The same ability to use binding expressions and patterns applies to attributes in class libraries. В следующем примере параметры конструктора атрибута совпадают со значениями path в предыдущих примерах 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}");
    // ...
}

Можно также создать выражения для частей имени файла, таких как расширение.You can also create expressions for parts of the file name such as the extension. Дополнительные сведения о том, как использовать выражения и шаблоны в строке пути к большому двоичному объекту, см. в статье Привязки хранилища BLOB-объектов Azure для службы "Функции Azure".For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

Метаданные триггераTrigger metadata

Помимо полезных данных, предоставляемых триггером (например, содержимое сообщения очереди, инициирующего вызов функции), многие триггеры предоставляют также дополнительные значения метаданных.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. Эти значения можно использовать в качестве входных параметров в C# и F# или свойств объекта context.bindings в JavaScript.These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

Например, триггер хранилища очередей Azure поддерживает следующие свойства:For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigger (содержимое активирующего сообщения, если строка допустима)QueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • ИдентификаторId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

Значения этих метаданных доступны в свойствах файла function.json.These metadata values are accessible in function.json file properties. Предположим, что вы используете триггер очереди, а сообщение в очереди содержит имя большого двоичного объекта, который вам нужно прочитать.For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. В файле function.json укажите свойство queueTrigger в метаданных большого двоичного объекта path, как показано в следующем примере: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 of metadata properties for each trigger are described in the corresponding reference article. Пример см. в разделе о метаданных триггера очередей.For an example, see queue trigger metadata. Документация доступна также на портале на вкладке Интегрировать в разделе Документация под областью конфигурации привязки.Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

Полезные данные JSONJSON payloads

Если полезные данные представлены в виде JSON, на его свойства можно ссылаться в конфигурации других привязок в той же функции и ее коде.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.

В следующем примере показан файл function.json для функции веб-перехватчика, который получает имя большого двоичного объекта в JSON: {"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"}. Входная привязка большого двоичного объекта считывает этот объект, а привязка для вывода HTTP возвращает содержимое большого двоичного объекта в ответе HTTP.A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. Обратите внимание, что входная привязка большого двоичного объекта получает имя такого объекта, обращаясь напрямую к свойству BlobName ("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"
    }
  ]
}

Для этого в C# и F# нужен класс, определяющий поля, которые должны быть десериализованы, как показано в следующем примере: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}"
    });
}

В JavaScript десериализация JSON выполняется автоматически.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();
}

Точечная нотацияDot notation

Если некоторые свойства в полезных данных JSON являются объектами со свойствами, к ним можно обратиться напрямую с помощью точечной нотации.If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. Например, ваш JSON выглядит следующим образом:For example, suppose your JSON looks like this:

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

На FileName можно непосредственно ссылаться, используя формат BlobName.FileName.You can refer directly to FileName as BlobName.FileName. С этим форматом JSON свойство path из предыдущего примера будет выглядеть следующим образом:With this JSON format, here's what the path property in the preceding example would look like:

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

В C# потребовалось бы два класса: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; }
}

Создание глобальных уникальных идентификаторовCreate GUIDs

Выражение привязки {rand-guid} создает идентификатор GUID.The {rand-guid} binding expression creates a GUID. Следующий путь к большому двоичному объекту в файле function.json создает большой двоичный объект с именем следующего вида: 50710cb5-84b9-4d87-9d83-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}.txt"
}

Текущее времяCurrent time

Выражение привязки DateTime разрешается в DateTime.UtcNow.The binding expression DateTime resolves to DateTime.UtcNow. Следующий путь к большому двоичному объекту в файле function.json создает большой двоичный объект с именем следующего вида: 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}.txt"
}

Привязка во время выполненияBinding at runtime

В C# и других языках .NET можно использовать шаблон императивной привязки, которая отличается от декларативной привязки в файле function.json или в атрибутах.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 binding is useful when binding parameters need to be computed at runtime rather than design time. Дополнительные сведения см. в справочнике разработчика C# и справочнике разработчика скриптов C#.To learn more, see the C# developer reference or the C# script developer reference.

Дальнейшие действияNext steps