适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 触发器

Azure Cosmos DB 触发器使用 Azure Cosmos DB 更改源来侦听跨分区的插入和更新。 更改源发布插入和更新,不发布删除。

有关设置和配置详细信息,请参阅概述

示例

触发器的用法取决于扩展包版本,以及函数应用中使用的 C# 形式,可以是以下形式之一:

进程内类库是编译的 C# 函数,该函数在与 Functions 运行时相同的进程中运行。

以下示例取决于给定 C# 模式的扩展版本。

以下示例演示了一个 C# 函数。当指定数据库和集合中存在插入或更新操作时,会调用该函数。

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            ILogger log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.LogInformation($"Documents modified: {documents.Count}");
                log.LogInformation($"First document Id: {documents[0].Id}");
            }
        }
    }
}

当指定数据库和集合中发生插入或更新操作时,会调用此函数。

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

Java 函数运行时库中,对其值将来自 Cosmos DB 的参数使用 @CosmosDBTrigger 注释。 可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

以下示例演示 function.json 文件中的一个 Cosmos DB 触发器绑定以及使用该绑定的 JavaScript 脚本函数。 添加或修改 Cosmos DB 记录时,该函数会写入日志消息。

下面是 function.json 文件中的绑定数据:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

请注意,某些绑定属性名称在 Azure Cosmos DB 扩展的版本 4.x 中已更改。

JavaScript 代码如下所示:

    module.exports = async function (context, documents) {
      context.log('First document Id modified : ', documents[0].id);
    }

下面的示例演示如何在 Cosmos DB 中的数据更改时运行函数。

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

请注意,某些绑定属性名称在 Azure Cosmos DB 扩展的版本 4.x 中已更改。

在 run.ps1 文件中,可以通过 $Documents 参数访问触发函数的文档。

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

以下示例演示 function.json 文件中的一个 Cosmos DB 触发器绑定以及使用该绑定的 Python 函数。 修改 Cosmos DB 记录时,该函数会写入日志消息。

下面是 function.json 文件中的绑定数据:

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

请注意,某些绑定属性名称在 Azure Cosmos DB 扩展的版本 4.x 中已更改。

下面是 Python 代码:

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

特性

进程内独立进程 C# 库使用 CosmosDBTriggerAttribute 来定义函数。 C# 脚本改为使用 function.json 配置文件。

Attribute 属性 说明
ConnectionStringSetting 应用设置或设置集合的名称,用于指定如何连接到受监视的 Azure Cosmos DB 帐户。 有关详细信息,请参阅连接
DatabaseName 带有受监视的集合的 Azure Cosmos DB 数据库的名称。
CollectionName 受监视的集合的名称。
LeaseConnectionStringSetting (可选)应用设置或设置集合的名称,用于指定如何连接到保留租用集合的 Azure Cosmos DB 帐户。

未设置时,使用 ConnectionStringSetting 值。 在门户中创建绑定时,将自动设置该参数。 用于租用集合的连接字符串必须具有写入权限。
LeaseDatabaseName (可选)数据库的名称,该数据库包含用于存储租用的集合。 未设置时,使用 databaseName 设置的值。
LeaseCollectionName (可选)用于存储租用的集合的名称。 未设置时,使用值 leases
CreateLeaseCollectionIfNotExists (可选)设置为 true 时,如果租用集合并不存在,将自动创建该集合。 默认值为 false
LeasesCollectionThroughput (可选)在创建租用集合时,定义要分配的请求单位的数量。 仅当 CreateLeaseCollectionIfNotExists 设置为 true 时,才会使用此设置。 使用门户创建绑定时,将自动设置该参数。
LeaseCollectionPrefix (可选)设置后,该值将作为前缀添加到在此函数的租约集合中创建的租约。 使用前缀可让两个不同的 Azure 函数通过不同的前缀来共享同一个租约集合。
FeedPollDelay (可选)在所有当前更改清空后,每两次在分区中轮询源上的新更改的延迟时间(以毫秒为单位)。 默认值为 5,000 毫秒(5 秒)。
LeaseAcquireInterval (可选)设置后,此项以毫秒为单位定义启动一个计算任务的时间间隔(前提是分区在已知的主机实例中均匀分布)。 默认为 13000(13 秒)。
LeaseExpirationInterval (可选)设置后,此项以毫秒为单位定义在表示分区的租用上进行租用的时间间隔。 如果在此时间间隔内不续订租用,则该租用会过期,分区的所有权会转移到另一个实例。 默认为 60000(60 秒)。
LeaseRenewInterval (可选)设置后,此项以毫秒为单位定义当前由实例拥有的分区的所有租用的续订时间间隔。 默认为 17000(17 秒)。
CheckpointInterval (可选)设置后,此项以毫秒为单位定义租用检查点的时间间隔。 默认为始终在进行每个 Function 调用之后进行检查。
CheckpointDocumentCount (可选)自定义租用检查点之间的文档数量。 默认是每次函数调用之后。
MaxItemsPerInvocation (可选)设置后,此属性会对每次函数调用收到的项目的最大数目进行设置。 如果受监视集合中的操作通过存储过程执行,则在从更改源读取项时,会保留事务范围。 因此,收到的项数可能高于指定的值,通过同一事务更改的项会通过某个原子批处理操作返回。
StartFromBeginning (可选)此选项告知触发器要从集合的更改历史记录开头位置读取更改,而不是从当前时间开始读取。 从开头位置读取仅在触发器首次启动时起作用,因为在后续运行中,已存储检查点。 如果已经创建租约,则将此选项设置为 true 将不起作用。
PreferredLocations (可选)为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置(区域)。 值应以逗号分隔。 例如,“中国北部,中国北部,中国北部”。
UseMultipleWriteLocations (可选)启用多区域帐户以写入租用集合。
UseDefaultJsonSerialization (可选)允许你在监视的集合中使用 JsonConvert.DefaultSettings。 此设置仅适用于受监视集合和使用者,用于设置受监视集合中使用的序列化。 必须在派生自 JsonConvert.DefaultSettings 的类中设置 CosmosDBWebJobsStartup

批注

配置

下表解释了在 function.json 文件中设置的绑定配置属性,其中属性因扩展版本而异。

function.json 属性 说明
type 必须设置为 cosmosDBTrigger
direction 必须设置为 in。 在 Azure 门户中创建触发器时,会自动设置该参数。
name 函数代码中使用的变量名称,表示发生更改的文档列表。
connectionStringSetting 应用设置或设置集合的名称,用于指定如何连接到受监视的 Azure Cosmos DB 帐户。 有关详细信息,请参阅连接
databaseName 带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName 受监视的集合的名称。
leaseConnectionStringSetting (可选)应用设置或设置集合的名称,用于指定如何连接到保留租用集合的 Azure Cosmos DB 帐户。

未设置时,使用 connectionStringSetting 值。 在门户中创建绑定时,将自动设置该参数。 用于租用集合的连接字符串必须具有写入权限。
leaseDatabaseName (可选)数据库的名称,该数据库包含用于存储租用的集合。 未设置时,使用 databaseName 设置的值。
leaseCollectionName (可选)用于存储租用的集合的名称。 未设置时,使用值 leases
createLeaseCollectionIfNotExists (可选)设置为 true 时,如果租用集合并不存在,将自动创建该集合。 默认值为 false
leasesCollectionThroughput (可选)在创建租用集合时,定义要分配的请求单位的数量。 仅当 createLeaseCollectionIfNotExists 设置为 true 时,才会使用此设置。 使用门户创建绑定时,将自动设置该参数。
leaseCollectionPrefix (可选)设置后,该值将作为前缀添加到在此函数的租约集合中创建的租约。 使用前缀可让两个不同的 Azure 函数通过不同的前缀来共享同一个租约集合。
feedPollDelay (可选)在所有当前更改清空后,每两次在分区中轮询源上的新更改的延迟时间(以毫秒为单位)。 默认值为 5,000 毫秒(5 秒)。
leaseAcquireInterval (可选)设置后,此项以毫秒为单位定义启动一个计算任务的时间间隔(前提是分区在已知的主机实例中均匀分布)。 默认为 13000(13 秒)。
leaseExpirationInterval (可选)设置后,此项以毫秒为单位定义在表示分区的租用上进行租用的时间间隔。 如果在此时间间隔内不续订租用,则该租用会过期,分区的所有权会转移到另一个实例。 默认为 60000(60 秒)。
leaseRenewInterval (可选)设置后,此项以毫秒为单位定义当前由实例拥有的分区的所有租用的续订时间间隔。 默认为 17000(17 秒)。
checkpointInterval (可选)设置后,此项以毫秒为单位定义租用检查点的时间间隔。 默认为始终在进行每个 Function 调用之后进行检查。
checkpointDocumentCount (可选)自定义租用检查点之间的文档数量。 默认是每次函数调用之后。
maxItemsPerInvocation (可选)设置后,此属性会对每次函数调用收到的项目的最大数目进行设置。 如果受监视集合中的操作通过存储过程执行,则在从更改源读取项时,会保留事务范围。 因此,收到的项数可能高于指定的值,通过同一事务更改的项会通过某个原子批处理操作返回。
startFromBeginning (可选)此选项告知触发器要从集合的更改历史记录开头位置读取更改,而不是从当前时间开始读取。 从开头位置读取仅在触发器首次启动时起作用,因为在后续运行中,已存储检查点。 如果已经创建租约,则将此选项设置为 true 将不起作用。
preferredLocations (可选)为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置(区域)。 值应以逗号分隔。 例如,“中国北部,中国北部,中国北部”。
useMultipleWriteLocations (可选)启用多区域帐户以写入租用集合。

有关完整示例的信息,请参阅示例部分

使用情况

Azure Cosmos DB 触发器支持的参数类型取决于 Functions 运行时版本、扩展包版本以及使用的 C# 模态。

触发器需要第二个集合,该集合用于存储各分区的租用。 必须提供受监视的集合和包含租用的集合,触发器才能正常工作。

重要

如果多个函数都配置为对同一集合使用 Cosmos DB 触发器,则每个函数都应使用专用租用集合,否则应该为每个函数指定不同的 LeaseCollectionPrefix。 否则,将只触发其中一个函数。 有关前缀的信息,请参阅“属性”部分

重要

如果多个函数都配置为对同一集合使用 Cosmos DB 触发器,则每个函数都应使用专用租用集合,否则应该为每个函数指定不同的 leaseCollectionPrefix。 否则,将只触发其中一个函数。 有关前缀的信息,请参阅“注释”部分

重要

如果多个函数都配置为对同一集合使用 Cosmos DB 触发器,则每个函数都应使用专用租用集合,否则应该为每个函数指定不同的 leaseCollectionPrefix。 否则,将只触发其中一个函数。 有关前缀的信息,请参阅“配置”部分

该触发器并不指示是更新还是插入文档,它仅提供文档本身。 如果需要以不同方式处理更新和插入,可通过实现用于插入或更新的时间戳字段来执行该操作。

连接

connectionStringSetting/connectionleaseConnectionStringSetting/leaseConnection 属性是对指定应用应该如何连接到 Azure Cosmos DB 的环境配置的引用。 这些属性可以指定:

如果配置的值既是单个设置的完全匹配,也是其他设置的前缀匹配,则使用完全匹配。

连接字符串

数据库帐户的连接字符串应存储在应用程序设置中,其名称与绑定配置的 connection 属性指定的值匹配。

基于标识的连接

如果使用 4.x 或更高版本的扩展,则无需将连接字符串与机密一起使用,可以使应用使用 Azure Active Directory 标识。 为此,需要定义公共前缀下的设置,该前缀映射到触发器和绑定配置中的 connection 属性。

在此模式下,扩展需要以下属性:

属性 环境变量模板 说明 示例值
帐户终结点 <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB 帐户终结点 URI。 https://<数据库帐户名称>.documents.azure.cn:443/

可以设置其他属性来自定义连接。 请参阅基于标识的连接的通用属性

在 Azure Functions 服务中托管时,基于标识的连接将使用托管标识。 默认情况下使用系统分配的标识,但可以使用 credentialclientID 属性来指定用户分配的标识。 在其他上下文(如本地开发)中运行时,将改用开发人员标识,尽管可以进行自定义。 请参阅使用基于标识的连接进行本地开发

向标识授予权限

无论使用何种标识,都必须具有执行所需操作的权限。 需要使用内置角色或者提供这些权限的自定义角色在 Azure RBAC 中分配角色

重要

某些权限可能由并非所有上下文都需要的目标服务公开。 尽可能遵循最低权限原则,仅授予标识所需的权限。 例如,如果应用只需要从数据源进行读取即可,则使用仅具有读取权限的角色。 分配一个也具有该服务写入权限的角色并不恰当,因为对于读取操作来说,写入是多余的权限。 同样,你也希望确保角色分配的范围仅限于需要读取的资源。

你将需要创建一个角色分配,以便在运行时提供对数据库帐户的访问权限。 所有者等管理角色还不够。 下表显示了在正常操作中使用 Cosmos DB 扩展时建议使用的内置角色。 根据所编写的代码,应用程序可能需要具有其他权限。

绑定类型 内置角色示例
触发器 Cosmos DB 内置数据参与者
输入绑定 Cosmos DB 内置数据读取者
输出绑定 Cosmos DB 内置数据参与者

后续步骤