如何在 Azure Cosmos DB 中註冊和使用預存程序、觸發程序和使用者定義函式

適用於:SQL API

Azure Cosmos DB 中的 SQL API 支援註冊和叫用以 JavaScript 撰寫的預存程序、觸發程序和使用者定義函式 (UDF)。 在您定義一或多個預存程序、觸發程序和使用者定義函數之後,您可以使用資料總管,在 Azure 入口網站中載入並檢視這些項目。

您可以在多個平台上使用 SQL API SDK,包括 .NET v2 (舊版).NET v3JavaJavaScriptPython SDK 來執行這些工作。 如果您之前尚未使用下列其中一個 SDK,請參閱適當 SDK 的「快速入門」文章:

SDK 開始使用
.NET v3 快速入門:建置 .NET 主控台應用程式來管理 Azure Cosmos DB SQL API 資源
Java 快速入門:建置 JAVA 應用程式來管理 Azure Cosmos DB SQL API 資料
JavaScript 快速入門:使用 Node.js 連線至 Azure Cosmos DB SQL API 帳戶並從中查詢資料
Python 快速入門:使用 Azure Cosmos DB SQL API 帳戶建置 Python 應用程式

如何執行預存程序

預存程序須以 JavaScript 撰寫。 這些程序可建立、更新、讀取、查詢和刪除 Azure Cosmos 容器內的項目。 如需如何在 Azure Cosmos DB 中撰寫預存程序的詳細資訊,請參閱如何在 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 並在清單物件中傳入觸發程序的名稱,在 RequestOptions 物件中傳入預先觸發程序。

注意

即使以清單的形式傳入觸發程序的名稱,每個作業仍然只能執行一個觸發程序。

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