如何在 Azure Cosmos DB 中注册和使用存储过程、触发器与用户定义的函数

适用范围: NoSQL

Azure Cosmos DB 中的 API for NoSQL 支持注册和调用以 JavaScript 编写的存储过程、触发器与用户定义的函数 (UDF)。 在定义一个或多个存储过程、触发器和用户定义的函数之后,可以使用数据资源管理器在 Azure 门户 中加载和查看它们。

可以跨多个平台使用 API for NoSQL SDK(包括 .NET v2(旧版).NET v3JavaJavaScriptPython SDK)以执行这些任务。 如果之前未使用过其中一个 SDK,请参阅相应 SDK 的快速入门文章:

SDK 入门
.NET v3 快速入门:适用于 .NET 的 Azure Cosmos DB for NoSQL 客户端库
Java 快速入门:生成 Java 应用以管理 Azure Cosmos DB for NoSQL 数据
JavaScript 快速入门:适用于 Node.js 的 Azure Cosmos DB for NoSQL 客户端库
Python 快速入门:适用于 Python 的 Azure Cosmos DB for NoSQL 客户端库

重要

以下代码示例假定你已具有 clientcontainer 变量。 如果需要创建这些变量,请参阅适用于平台的相应快速入门。

如何运行存储过程

存储过程是使用 JavaScript 编写的。 它们可以在 Azure Cosmos DB 容器中创建、更新、读取、查询和删除项。 有关详细信息,请参阅 如何编写存储过程

以下示例演示如何使用 Azure Cosmos DB SDK 注册和调用存储过程。 有关此存储过程的源(保存为 spCreateToDoItem.js),请参阅 使用存储过程创建项

注意

对于已分区的容器,在运行存储过程时,必须在请求选项中提供分区键值。 存储过程的范围始终限定为分区键。 存储过程看不到具有不同分区键值的项。 此原则也适用于触发器。

以下示例演示如何使用 .NET SDK v2 注册存储过程:

string storedProcedureId = "spCreateToDoItems";
StoredProcedure newStoredProcedure = new StoredProcedure
   {
       Id = storedProcedureId,
       Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
   };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var response = await client.CreateStoredProcedureAsync(containerUri, newStoredProcedure);
StoredProcedure createdStoredProcedure = response.Resource;

以下代码演示如何使用 .NET SDK v2 调用存储过程:

dynamic[] newItems = new dynamic[]
{
    new {
        category = "Personal",
        name = "Groceries",
        description = "Pick up strawberries",
        isComplete = false
    },
    new {
        category = "Personal",
        name = "Doctor",
        description = "Make appointment for check up",
        isComplete = false
    }
};

Uri uri = UriFactory.CreateStoredProcedureUri("myDatabase", "myContainer", "spCreateToDoItem");
RequestOptions options = new RequestOptions { PartitionKey = new PartitionKey("Personal") };
var result = await client.ExecuteStoredProcedureAsync<string>(uri, options, new[] { newItems });

如何运行预触发器

以下示例将演示如何使用 Azure Cosmos DB SDK 注册和调用预触发器。 有关此预触发器示例的源(另存为 trgPreValidateToDoItemTimestamp.js),请参阅预触发器

当通过指定 PreTriggerInclude 并在 List 对象中传递触发器名称来运行操作时,会在 RequestOptions 对象中传递预触发器。

注意

即使触发器名称作为 List 传递,仍然只能对每个操作运行一个触发器。

以下代码演示如何使用 .NET SDK v2 注册预触发器:

string triggerId = "trgPreValidateToDoItemTimestamp";
Trigger trigger = new Trigger
{
    Id =  triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

以下代码演示如何使用 .NET SDK v2 调用预触发器:

dynamic newItem = new
{
    category = "Personal",
    name = "Groceries",
    description = "Pick up strawberries",
    isComplete = false
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
RequestOptions requestOptions = new RequestOptions { PreTriggerInclude = new List<string> { "trgPreValidateToDoItemTimestamp" } };
await client.CreateDocumentAsync(containerUri, newItem, requestOptions);

如何运行后触发器

以下示例演示如何使用 Azure Cosmos DB SDK 注册后触发器。 有关此后触发器示例的源(保存为 trgPostUpdateMetadata.js),请参阅 后触发器

以下代码演示如何使用 .NET SDK v2 注册后触发器:

string triggerId = "trgPostUpdateMetadata";
Trigger trigger = new Trigger
{
    Id = triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

以下代码演示如何使用 .NET SDK v2 调用后触发器:

var newItem = { 
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};

RequestOptions options = new RequestOptions { PostTriggerInclude = new List<string> { "trgPostUpdateMetadata" } };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.createDocumentAsync(containerUri, newItem, options);

如何使用用户定义的函数

以下示例演示如何使用 Azure Cosmos DB SDK 注册用户定义的函数。 有关此用户定义的函数示例的源(保存为 udfTax.js),请参阅 如何编写用户定义的函数

以下代码演示如何使用 .NET SDK v2 注册用户定义的函数:

string udfId = "Tax";
var udfTax = new UserDefinedFunction
{
    Id = udfId,
    Body = File.ReadAllText($@"..\js\{udfId}.js")
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateUserDefinedFunctionAsync(containerUri, udfTax);

以下代码演示如何使用 .NET SDK v2 调用用户定义的函数:

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var results = client.CreateDocumentQuery<dynamic>(containerUri, "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000"));

foreach (var result in results)
{
    //iterate over results
}

后续步骤

详细了解概念以及如何在 Azure Cosmos DB 中编写或使用存储过程、触发器和用户定义的函数: