Cara mendaftarkan dan menggunakan prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna di Microsoft Azure Cosmos DB

Artikel
03/18/2023

BERLAKU UNTUK: NoSQL

API untuk NoSQL di Azure Cosmos DB mendukung pendaftaran dan pemanggilan prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna (UDF) yang ditulis dalam JavaScript. Setelah menentukan satu atau beberapa prosedur tersimpan, pemicu, atau fungsi yang ditentukan pengguna, Anda dapat memuat dan melihatnya di portal Azure dengan menggunakan Data Explorer.

Anda dapat menggunakan API untuk NoSQL SDK di beberapa platform termasuk .NET v2 (warisan), .NET v3, Java, JavaScript, atau Python SDK untuk melakukan tugas-tugas ini. Jika Anda belum bekerja dengan salah satu SDK ini sebelumnya, lihat artikel mulai cepat untuk SDK yang sesuai:

SDK	Memulai
.NET v3	Mulai cepat: Azure Cosmos DB untuk pustaka klien NoSQL untuk .NET
Java	Mulai cepat: Membangun aplikasi Java untuk mengelola data Azure Cosmos DB for NoSQL
JavaScript	Mulai cepat: Pustaka klien Azure Cosmos DB for NoSQL untuk Node.js
Python	Mulai cepat: Azure Cosmos DB untuk pustaka klien NoSQL untuk Python

Penting

Sampel kode berikut mengasumsikan bahwa Anda telah memiliki client variabel dan container . Jika Anda perlu membuat variabel tersebut, lihat mulai cepat yang sesuai untuk platform Anda.

Cara menjalankan prosedur tersimpan

Prosedur tersimpan ditulis menggunakan JavaScript. Mereka dapat membuat, memperbarui, membaca, mengkueri, dan menghapus item dalam kontainer Azure Cosmos DB. Untuk informasi selengkapnya, lihat Cara menulis prosedur tersimpan.

Contoh berikut menunjukkan cara mendaftar dan memanggil prosedur tersimpan dengan menggunakan Microsoft Azure Cosmos DB. Untuk sumber prosedur tersimpan ini, disimpan sebagai spCreateToDoItem.js, lihat Membuat item menggunakan prosedur tersimpan.

Catatan

Untuk kontainer yang dipartisi, saat menjalankan prosedur tersimpan, Anda harus memberikan nilai kunci partisi dalam opsi permintaan. Prosedur tersimpan selalu dicakup ke kunci partisi. Item yang memiliki nilai kunci partisi yang berbeda tidak terlihat oleh prosedur tersimpan. Prinsip ini juga berlaku untuk pemicu.

Contoh berikut menunjukkan cara mendaftarkan prosedur tersimpan dengan menggunakan .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;

Kode berikut menunjukkan cara memanggil prosedur tersimpan dengan menggunakan .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 });

Contoh berikut menunjukkan cara mendaftarkan prosedur tersimpan dengan menggunakan .NET SDK v3:

string storedProcedureId = "spCreateToDoItems";
StoredProcedureResponse storedProcedureResponse = await client.GetContainer("myDatabase", "myContainer").Scripts.CreateStoredProcedureAsync(new StoredProcedureProperties
{
    Id = storedProcedureId,
    Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
});

Kode berikut menunjukkan cara memanggil prosedur tersimpan dengan menggunakan .NET SDK v3:

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
    }
};

var result = await client.GetContainer("database", "container").Scripts.ExecuteStoredProcedureAsync<string>("spCreateToDoItem", new PartitionKey("Personal"), new[] { newItems });

Contoh berikut menunjukkan cara mendaftarkan prosedur tersimpan dengan menggunakan Java SDK:

CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
    "spCreateToDoItems", 
    Files.readString(Paths.get("createToDoItems.js"))
);

CosmosStoredProcedureResponse response = container
    .getScripts()
    .createStoredProcedure(definition);

Kode berikut menunjukkan cara memanggil prosedur tersimpan dengan menggunakan Java SDK:

CosmosStoredProcedure sproc = container   
    .getScripts()
    .getStoredProcedure("spCreateToDoItems");

List<Object> items = new ArrayList<Object>();

ToDoItem firstItem = new ToDoItem();
firstItem.category = "Personal";
firstItem.name = "Groceries";
firstItem.description = "Pick up strawberries";
firstItem.isComplete = false;
items.add(firstItem);

ToDoItem secondItem = new ToDoItem();
secondItem.category = "Personal";
secondItem.name = "Doctor";
secondItem.description = "Make appointment for check up";
secondItem.isComplete = true;
items.add(secondItem);

CosmosStoredProcedureRequestOptions options = new CosmosStoredProcedureRequestOptions();
options.setPartitionKey(
    new PartitionKey("Personal")
);

CosmosStoredProcedureResponse response = sproc.execute(
    items, 
    options
);

Contoh berikut menunjukkan cara mendaftarkan prosedur tersimpan dengan menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
await container.scripts.storedProcedures.create({
    id: sprocId,
    body: require(`../js/${sprocId}`)
});

Kode berikut menunjukkan cara memanggil prosedur tersimpan dengan menggunakan JavaScript SDK:

const newItem = [{
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}];
const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
const {resource: result} = await container.scripts.storedProcedure(sprocId).execute(newItem, {partitionKey: newItem[0].category});

Contoh berikut menunjukkan cara mendaftarkan prosedur tersimpan dengan menggunakan Python SDK:

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/spCreateToDoItems.js') as file:
    file_contents = file.read()

sproc = {
    'id': 'spCreateToDoItem',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
created_sproc = container.scripts.create_stored_procedure(body=sproc)

Kode berikut menunjukkan cara memanggil prosedur tersimpan dengan menggunakan Python SDK:

import uuid

new_id= str(uuid.uuid4())

# Creating a document for a container with "id" as a partition key.

new_item =   {
      "id": new_id, 
      "category":"Personal",
      "name":"Groceries",
      "description":"Pick up strawberries",
      "isComplete":False
   }
result = container.scripts.execute_stored_procedure(sproc=created_sproc,params=[new_item], partition_key=new_id)

Cara menjalankan pretrigger

Contoh berikut menunjukkan cara mendaftar dan memanggil pretrigger dengan menggunakan SDK Azure Cosmos DB. Untuk sumber contoh pretrigger ini, disimpan sebagai trgPreValidateToDoItemTimestamp.js, lihat Pretrigger.

Saat Anda menjalankan operasi dengan menentukan PreTriggerInclude lalu meneruskan nama pemicu dalam List objek, praperadilan diteruskan dalam RequestOptions objek.

Catatan

Meskipun nama pemicu diteruskan sebagai List, Anda masih dapat menjalankan hanya satu pemicu per operasi.

Kode berikut menunjukkan cara mendaftarkan pretrigger menggunakan .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);

Kode berikut menunjukkan cara memanggil pretrigger menggunakan .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);

Kode berikut menunjukkan cara mendaftarkan pretrigger menggunakan .NET SDK v3:

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPreValidateToDoItemTimestamp",
    Body = File.ReadAllText("@..\js\trgPreValidateToDoItemTimestamp.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
});

Kode berikut menunjukkan cara memanggil pretrigger menggunakan .NET SDK v3:

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

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PreTriggers = new List<string> { "trgPreValidateToDoItemTimestamp" } });

Kode berikut menunjukkan cara mendaftarkan pretrigger menggunakan Java SDK:

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "preValidateToDoItemTimestamp",
    Files.readString(Paths.get("validateToDoItemTimestamp.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.PRE);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

Kode berikut menunjukkan cara memanggil pretrigger menggunakan Java SDK:

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Groceries";
item.description = "Pick up strawberries";
item.isComplete = false;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPreTriggerInclude(
    Arrays.asList("preValidateToDoItemTimestamp")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

Kode berikut menunjukkan cara mendaftarkan pretrigger menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "pre"
});

Kode berikut menunjukkan cara memanggil pretrigger menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.items.create({
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}, {preTriggerInclude: [triggerId]});

Kode berikut menunjukkan cara mendaftarkan pretrigger menggunakan Python SDK:

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPreValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPreValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Pre,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

Kode berikut menunjukkan cara memanggil pretrigger menggunakan Python SDK:

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}

result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

Cara menjalankan pasca-pemicu

Contoh berikut menunjukkan cara mendaftarkan pasca-pemicu dengan menggunakan Microsoft Azure Cosmos DB SDK. Untuk sumber contoh pasca-pemicu ini, disimpan sebagai trgPostUpdateMetadata.js, lihat Pasca-pemicu

Kode berikut menunjukkan cara mendaftarkan pasca-pemicu menggunakan .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);

Kode berikut menunjukkan cara memanggil pasca-pemicu menggunakan .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);

Kode berikut menunjukkan cara mendaftarkan pasca-pemicu menggunakan .NET SDK v3:

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPostUpdateMetadata",
    Body = File.ReadAllText(@"..\js\trgPostUpdateMetadata.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
});

Kode berikut menunjukkan cara memanggil pasca-pemicu menggunakan .NET SDK v3:

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

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PostTriggers = new List<string> { "trgPostUpdateMetadata" } });

Kode berikut menunjukkan cara mendaftarkan pasca-pemicu menggunakan Java SDK:

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "postUpdateMetadata",
    Files.readString(Paths.get("updateMetadata.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.POST);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

Kode berikut menunjukkan cara memanggil pasca-pemicu menggunakan Java SDK:

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Doctor";
item.description = "Make appointment for check up";
item.isComplete = true;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPostTriggerInclude(
    Arrays.asList("postUpdateMetadata")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

Kode berikut menunjukkan cara mendaftarkan pasca-pemicu menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "post"
});

Kode berikut menunjukkan cara memanggil pasca-pemicu menggunakan JavaScript SDK:

const item = {
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};
const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.items.create(item, {postTriggerInclude: [triggerId]});

Kode berikut menunjukkan cara mendaftarkan pasca-pemicu menggunakan Python SDK:

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPostValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPostValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Post,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

Kode berikut menunjukkan cara memanggil pasca-pemicu menggunakan Python SDK:

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}
container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

Cara bekerja dengan fungsi yang ditentukan pengguna

Contoh berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna dengan menggunakan Microsoft Azure Cosmos DB. Untuk sumber contoh fungsi yang ditentukan pengguna ini, disimpan sebagai udfTax.js, lihat Cara menulis fungsi yang ditentukan pengguna.

Kode berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna menggunakan .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);

Kode berikut menunjukkan cara memanggil fungsi yang ditentukan pengguna menggunakan .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
}

Kode berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna menggunakan .NET SDK v3:

await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
    Id = "Tax",
    Body = File.ReadAllText(@"..\js\Tax.js")
});

Kode berikut menunjukkan cara memanggil fungsi yang ditentukan pengguna menggunakan .NET SDK v3:

var iterator = client.GetContainer("database", "container").GetItemQueryIterator<dynamic>("SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000");
while (iterator.HasMoreResults)
{
    var results = await iterator.ReadNextAsync();
    foreach (var result in results)
    {
        //iterate over results
    }
}

Kode berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna menggunakan Java SDK:

CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
    "udfTax",
    Files.readString(Paths.get("tax.js"))
);

CosmosUserDefinedFunctionResponse response = container
    .getScripts()
    .createUserDefinedFunction(definition);

Kode berikut menunjukkan cara memanggil fungsi yang ditentukan pengguna menggunakan Java SDK:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

CosmosPagedIterable<ToDoItem> iterable = container.queryItems(
    "SELECT t.cost, udf.udfTax(t.cost) AS costWithTax FROM t", 
    options, 
    ToDoItem.class);

Kode berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
    id: udfId,
    body: require(`../js/${udfId}`)

Kode berikut menunjukkan cara memanggil fungsi yang ditentukan pengguna menggunakan JavaScript SDK:

const container = client.database("myDatabase").container("myContainer");
const sql = "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000";
const {result} = await container.items.query(sql).toArray();

Kode berikut menunjukkan cara mendaftarkan fungsi yang ditentukan pengguna menggunakan Python SDK:

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/udfTax.js') as file:
    file_contents = file.read()
udf_definition = {
    'id': 'Tax',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
udf = container.scripts.create_user_defined_function(udf_definition)

Kode berikut menunjukkan cara memanggil fungsi yang ditentukan pengguna menggunakan Python SDK:

results = list(container.query_items(
    'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))

Langkah berikutnya

Pelajari konsep selengkapnya dan cara menulis atau menggunakan prosedur tersimpan, pemicu, dan fungsi yang ditentukan pengguna di Microsoft Azure Cosmos DB: