如何在 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 中寫入或使用預存程序、觸發程序和使用者定義函式: