Azure Functions 绑定表达式和模式

2025-08-15

Azure Functions 中触发器和绑定最强大的功能之一是 绑定表达式。在 function.json 文件和函数参数和代码中，可以使用解析为来自各种源的值的表达式。

大多数表达式都用大括号括起来。例如，在队列触发器函数中，{queueTrigger} 解析为队列消息文本。 path如果 Blob 输出绑定的属性和container/{queueTrigger}队列消息HelloWorld触发函数，则会创建一HelloWorld个名为的 Blob。

应用设置

最佳做法是使用应用设置而不是配置文件来管理机密和连接字符串。这种做法会限制对这些机密的访问，并使文件在公共源代码管理存储库中存储文件 function.json 是安全的。

每当要根据环境更改配置时，应用设置也很有用。例如，在测试环境中，可能需要监视队列存储或 Blob 存储的其他容器。

应用设置的绑定表达式与其他绑定表达式的标识方式不同：它们用百分比符号而不是大括号包装。例如，如果 Blob 输出绑定的路径为%Environment%/newblob.txt应用设置值Development，则会在DevelopmentEnvironment容器中创建 Blob。

当函数在本地运行时，应用设置的值来自 local.settings.json 该文件。

注意

触发器和绑定的 connection 属性是一种特殊情况，该属性会自动将值解析为应用设置（不带百分比号）。

以下示例是一个 Azure 队列存储触发器，它使用应用设置 %input_queue_name% 定义要触发的队列：

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

可在类库中使用此相同的方法：

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

触发器文件名

path Blob 触发器的值可以是一种模式，可用于引用其他绑定和函数代码中的触发 Blob 的名称。该模式还可包含筛选条件，用于指定哪些 Blob 可以触发函数调用。

例如，在 Blob 触发器的以下绑定中，模式 path 为 sample-images/{filename}。此模式创建名为的 filename绑定表达式。

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

然后，可以使用输出绑定中的表达式 filename 来指定要创建的 blob 的名称：

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

函数代码可以使用 filename 作为参数名称来访问相同的值：

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

类库中的特性同样能够使用绑定表达式和模式。在以下示例中，属性构造函数参数的值与前面的function.json示例相同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}");
    // ...
}

还可针对文件名的某些部分创建表达式。在以下示例中，函数仅在与模式匹配的文件名上触发： anyname-anyfile.csv

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

有关如何在 Blob 路径字符串中使用表达式和模式的详细信息，请参阅 Azure Blob 存储绑定的参考。

触发器元数据

除了触发器提供的数据有效负载（例如触发函数的队列消息的内容），许多触发器还提供其他元数据值。可以将这些值用作 C# 和 F# 中的输入参数，也可以用作 JavaScript 中对象的属性 context.bindings 。

例如，Azure 队列存储触发器支持以下属性：

QueueTrigger （如果字符串有效，则触发消息内容）
DequeueCount
ExpirationTime
Id
InsertionTime
NextVisibleTime
PopReceipt

可以在文件属性中 function.json 访问这些元数据值。例如，假设使用队列触发器，队列消息包含要读取的 blob 的名称。 function.json在文件中，可以使用 queueTrigger blob path 属性中的元数据属性，如以下示例所示：

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

可以在相应的参考文章中找到每个触发器的元数据属性的详细信息。有关示例，请参阅 Azure 队列存储触发器的元数据。在门户的 “集成 ”选项卡上，还可以在绑定配置区域下面的 “文档 ”部分获取文档。

JSON 有效负载

在某些情况下，可以参考同一函数和函数代码中其他绑定的配置中的触发器有效负载属性。此方法要求触发器有效负载为 JSON，并且小于特定于每个触发器的阈值。通常，有效负载大小需要小于 100 MB，但应检查每个触发器的引用内容。

使用触发器有效负载属性可能会影响应用程序的性能。它还强制触发器参数类型为简单类型（如字符串）或表示 JSON 数据的自定义对象类型。不能将其用于流、客户端或其他 SDK 类型。

以下示例显示了function.json一个 Webhook 函数的文件，该函数以 JSON 形式接收 Blob 名称： {"BlobName":"HelloWorld.txt"} Blob 输入绑定读取 blob，HTTP 输出绑定返回 HTTP 响应中的 Blob 内容。请注意，Blob 输入绑定通过直接 BlobName 引用属性（"path": "strings/{BlobName}"）来获取 Blob 名称。

{
  "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# 中工作，需要一个类来定义要反序列化的字段，如以下示例所示：

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 反序列化：

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

点表示法

如果 JSON 有效负载中的某些属性是具有属性的对象，则可以使用点（.）表示法直接引用它们。此表示法不适用于 Azure Cosmos DB 或 Azure 表存储绑定。

例如，假设 JSON 如以下示例所示：

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

可以直接以 FileName 的形式引用 BlobName.FileName。使用此 JSON 格式时，上述示例中的 path 属性如下所示：

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

在 C# 中，需要两个类：

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

新的 GUID

{rand-guid} 绑定表达式用于创建 GUID。文件中的以下 blob 路径 function.json 创建一个名称类似于 50710cb5-84b9-4d87-9d83-a03d6976a682.txt的 blob：

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

当前日期和时间

绑定表达式 DateTime 解析为 DateTime.UtcNow。文件中的以下 blob 路径 function.json 创建一个名称类似于 2018-02-16T17-59-55Z.txt的 blob：

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

在运行时绑定

在 C# 和其他 .NET 语言中，可以使用命令性绑定模式，而不是声明性绑定 function.json 和属性。当绑定参数需要在运行时（而非在设计时）计算时，命令性绑定很有用。若要了解详细信息，请参阅 C# 开发人员参考或 C# 脚本开发人员参考。

Azure Functions 触发器和绑定

通过