Azure Cosmos DB'de saklı yordamları, tetikleyicileri ve kullanıcı tanımlı işlevleri kaydetme ve kullanma

2024-08-15

UYGULANANLAR: NoSQL

Azure Cosmos DB'deki NoSQL API'si JavaScript'te yazılmış saklı yordamları, tetikleyicileri ve kullanıcı tanımlı işlevleri (UDF) kaydetmeyi ve çağırmayı destekler. Bir veya daha fazla saklı yordam, tetikleyici veya kullanıcı tanımlı işlev tanımladıktan sonra, Veri Gezgini kullanarak bunları Azure portalında yükleyebilir ve görüntüleyebilirsiniz.

Bu görevleri gerçekleştirmek için .NET v2 (eski), .NET v3 , Java , JavaScript veya Python SDK'ları gibi birden çok platformda NoSQL SDK'sı için API'yi kullanabilirsiniz. Bu SDK'lardan biriyle daha önce çalışmadıysanız, uygun SDK için hızlı başlangıç makalesine bakın:

SDK	Başlangıç
.NET v3	Hızlı Başlangıç: .NET için NoSQL için Azure Cosmos DB istemci kitaplığı
Java	Hızlı Başlangıç: NoSQL için Azure Cosmos DB verilerini yönetmek için java uygulaması oluşturma
JavaScript	Hızlı Başlangıç: NoSQL için Azure Cosmos DB istemci kitaplığı; Node.js
Piton	Hızlı Başlangıç: Python için NoSQL için Azure Cosmos DB istemci kitaplığı

Önemli

Aşağıdaki kod örneklerinde zaten client ve container değişkenleriniz olduğu varsayılır. Bu değişkenleri oluşturmanız gerekiyorsa platformunuz için uygun hızlı başlangıç konusuna bakın.

Depolanan yordamları nasıl çalıştırılır

Saklı yordamlar JavaScript kullanılarak yazılır. Azure Cosmos DB kapsayıcısı içinde öğe oluşturabilir, güncelleştirebilir, okuyabilir, sorgulayabilir ve silebilir. Daha fazla bilgi için Saklı yordamları nasıl yazılır?

Aşağıdaki örneklerde Azure Cosmos DB SDK'larını kullanarak bir saklı yordamın nasıl kaydedilip çağrıldığı gösterilmektedir. spCreateToDoItem.js olarak kaydedilen bu saklı yordamın kaynağı için bkz. Saklı yordamları kullanarak öğe oluşturma.

Not

Bölümlenmiş kapsayıcılar için bir saklı yordam çalıştırdığınızda, istek seçeneklerinde bir bölüm anahtarı değeri sağlamanız gerekir. Saklı yordamların kapsamı her zaman bir bölüm anahtarı olarak belirlenmiştir. Farklı bir bölüm anahtarı değerine sahip öğeler saklı yordama görünmez. Bu ilke tetikleyiciler için de geçerlidir.

Aşağıdaki örnekte .NET SDK v2 kullanılarak saklı yordamın nasıl kaydedildiği gösterilmektedir:

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;

Aşağıdaki kod, .NET SDK v2 kullanarak saklı yordamı çağırmayı gösterir:

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

Aşağıdaki örnekte .NET SDK v3 kullanılarak saklı yordamın nasıl kaydedildiği gösterilmektedir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak saklı yordamı çağırmayı gösterir:

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

Aşağıdaki örnekte Java SDK'sını kullanarak saklı yordamın nasıl kaydedildiği gösterilmektedir:

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

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

Aşağıdaki kod, Java SDK'sını kullanarak saklı yordamı çağırmayı gösterir:

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

Aşağıdaki örnekte JavaScript SDK'sını kullanarak saklı yordamın nasıl kaydedildiği gösterilmektedir:

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak saklı yordamı çağırmayı gösterir:

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

Aşağıdaki örnekte Python SDK'sını kullanarak saklı yordamın nasıl kaydedildiği gösterilmektedir:

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)

Aşağıdaki kod, Python SDK'sını kullanarak saklı yordamı çağırmayı gösterir:

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)

Ön tetikleyiciler nasıl çalıştırılır

Aşağıdaki örneklerde, Azure Cosmos DB SDK'larını kullanarak bir ön denemenin nasıl kaydedildiği ve çağrıldığı gösterilmektedir. Bu ön tetikleme örneğinin kaynağı için, trgPreValidateToDoItemTimestamp.js olarak kaydedilmiş dosyaya, Pretriggers bölümünden bakın.

Bir nesne içinde tetikleyici adını belirtip PreTriggerInclude geçirerek bir List işlemi çalıştırdığınızda, ön tetikleyiciler RequestOptions nesnesine geçirilir.

Not

Tetikleyicinin adı olarak Listgeçirilse de işlem başına yalnızca bir tetikleyici çalıştırabilirsiniz.

Aşağıdaki kod, .NET SDK v2 kullanarak bir ön denemeyi nasıl kaydedeceklerini gösterir:

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

Aşağıdaki kod, .NET SDK v2 kullanarak bir ön denemeyi nasıl çağıracaklarını gösterir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak bir ön denemeyi nasıl kaydedeceklerini gösterir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak bir ön denemeyi çağırmayı gösterir:

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

Aşağıdaki kod, Java SDK'sını kullanarak bir ön deneme kaydının nasıl yapılacağını gösterir:

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

Aşağıdaki kod, Java SDK'sını kullanarak bir ön denemeyi nasıl çağıracaklarını gösterir:

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak ön deneme kaydının nasıl yapılacağını gösterir:

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak bir ön denemeyi çağırmayı gösterir:

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

Aşağıdaki kod, Python SDK'sını kullanarak bir ön deneme kaydının nasıl yapılacağını gösterir:

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)

Aşağıdaki kod, Python SDK'sını kullanarak bir ön denemeyi çağırmayı gösterir:

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

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

Son tetikleyicileri çalıştırma

Aşağıdaki örneklerde Azure Cosmos DB SDK'larını kullanarak bir son tetikleyicinin nasıl kaydedildiği gösterilmektedir. trgPostUpdateMetadata.js olarak kaydedilen bu tetikleyici sonrası örneğin kaynağı için bkz. Post-triggers

Aşağıdaki kod, .NET SDK v2 kullanarak bir post-trigger'ın nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kodda .NET SDK v2 kullanılarak bir post-trigger'ın nasıl çağrılacakları gösterilmektedir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak bir post-trigger'ın nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak bir post-trigger'ın nasıl çağrılacaklarını gösterir:

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

Aşağıdaki kod, Java SDK'sını kullanarak bir post-trigger'ın nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kod, Java SDK'sını kullanarak bir post-trigger'ı çağırmayı gösterir:

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak bir post-trigger'ın nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak bir post-trigger'ı çağırmayı gösterir:

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

Aşağıdaki kod, Python SDK'sını kullanarak bir post-trigger'ın nasıl kaydedileceklerini gösterir:

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)

Aşağıdaki kod, Python SDK'sını kullanarak bir post-trigger çağırmayı gösterir:

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

Kullanıcı tanımlı işlevlerle çalışma

Aşağıdaki örneklerde, Azure Cosmos DB SDK'larını kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedildiği gösterilmektedir. udfTax.js olarak kaydedilen bu kullanıcı tanımlı işlev örneğinin kaynağı için bkz. Kullanıcı tanımlı işlevleri yazma.

Aşağıdaki kod, .NET SDK v2 kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kodda .NET SDK v2 kullanılarak kullanıcı tanımlı bir işlevin nasıl çağrıldığı gösterilmektedir:

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
}

Aşağıdaki kod, .NET SDK v3 kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kod, .NET SDK v3 kullanarak kullanıcı tanımlı bir işlevi çağırmayı gösterir:

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

Aşağıdaki kod, Java SDK'sını kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedileceklerini gösterir:

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

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

Aşağıdaki kodda Java SDK'sını kullanarak kullanıcı tanımlı bir işlevin nasıl çağrıldığı gösterilmektedir:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

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

Aşağıdaki kod, JavaScript SDK'sını kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedileceklerini gösterir:

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

Aşağıdaki kodda JavaScript SDK'sını kullanarak kullanıcı tanımlı bir işlevin nasıl çağrıldığı gösterilmektedir:

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();

Aşağıdaki kod, Python SDK'sını kullanarak kullanıcı tanımlı bir işlevin nasıl kaydedileceklerini gösterir:

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)

Aşağıdaki kod, Python SDK'sını kullanarak kullanıcı tanımlı bir işlevi çağırmayı gösterir:

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

Sonraki adımlar

Azure Cosmos DB'de saklı yordamları, tetikleyicileri ve kullanıcı tanımlı işlevleri yazma veya kullanma hakkında daha fazla bilgi edinin: