كيفية تسجيل واستخدام الإجراءات المخزنة والمشغلات والدالات المعرفة من قبل المستخدم في Azure Cosmos DB

مقالة
03/18/2023

ينطبق على: NoSQL

تدعم واجهة برمجة التطبيقات ل NoSQL في Azure Cosmos DB تسجيل واستدعاء الإجراءات المخزنة والمشغلات والوظائف المعرفة من قبل المستخدم (UDFs) المكتوبة بلغة JavaScript. بعد تحديد إجراء واحد أو أكثر من الإجراءات المخزنة أو المشغلات أو الوظائف المعرفة من قبل المستخدم، يمكنك تحميلها وعرضها في مدخل Microsoft Azure باستخدام Data Explorer.

يمكنك استخدام واجهة برمجة التطبيقات ل NoSQL SDK عبر أنظمة أساسية متعددة بما في ذلك .NET v2 (قديم) أو .NET v3 أو Java أو JavaScript أو Python SDKs للقيام بهذه المهام. إذا لم تكن قد عملت مع إحدى مجموعات SDK هذه من قبل، فشاهد مقالة التشغيل السريع ل SDK المناسب:

SDK	الشروع في العمل
.NET v3	التشغيل السريع: مكتبة عميل Azure Cosmos DB ل NoSQL ل .NET
Java	التشغيل السريع: إنشاء تطبيق Java لإدارة Azure Cosmos DB لبيانات NoSQL
JavaScript	التشغيل السريع: مكتبة عميل Azure Cosmos DB ل NoSQL Node.js
Python	التشغيل السريع: مكتبة عميل Azure Cosmos DB ل NoSQL ل Python

هام

تفترض نماذج التعليمات البرمجية التالية أن لديك بالفعل client متغيرات و container . إذا كنت بحاجة إلى إنشاء هذه المتغيرات، فراجع التشغيل السريع المناسب للنظام الأساسي الخاص بك.

كيفية تشغيل الإجراءات المخزنة

تتم كتابة الإجراءات المخزنة باستخدام JavaScript. يمكنهم إنشاء العناصر وتحديثها وقراءتها والاستعلام عنها وحذفها داخل حاوية Azure Cosmos DB. لمزيد من المعلومات، راجع كيفية كتابة الإجراءات المخزنة.

توضح الأمثلة التالية كيفية التسجيل واستدعاء إجراء مخزن باستخدام Azure Cosmos DB SDKs. للحصول على مصدر هذا الإجراء المخزن، المحفوظ ك 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 });

يوضح المثال التالي كيفية تسجيل إجراء مخزن باستخدام .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")
});

توضح التعليمة البرمجية التالية كيفية استدعاء إجراء مخزن باستخدام .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 });

يوضح المثال التالي كيفية تسجيل إجراء مخزن باستخدام Java SDK:

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

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

توضح التعليمة البرمجية التالية كيفية استدعاء إجراء مخزن باستخدام 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
);

يوضح المثال التالي كيفية تسجيل إجراء مخزن باستخدام JavaScript SDK:

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

توضح التعليمة البرمجية التالية كيفية استدعاء إجراء مخزن باستخدام 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});

يوضح المثال التالي كيفية تسجيل إجراء مخزن باستخدام 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)

توضح التعليمة البرمجية التالية كيفية استدعاء إجراء مخزن باستخدام 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)

كيفية تشغيل المشغلات المسبقة

توضح الأمثلة التالية كيفية تسجيل واستدعاء pretrigger باستخدام Azure Cosmos DB SDKs. للحصول على مصدر مثال pretrigger هذا، المحفوظ ك trgPreValidateToDoItemTimestamp.js، راجع Pretriggers.

عند تشغيل عملية عن طريق تحديد PreTriggerInclude ثم تمرير اسم المشغل في كائن List ، يتم تمرير الزناد المسبقين RequestOptions في الكائن.

إشعار

على الرغم من تمرير اسم المشغل ك List، فلا يزال بإمكانك تشغيل مشغل واحد فقط لكل عملية.

توضح التعليمات البرمجية التالية كيفية تسجيل pretrigger باستخدام .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);

توضح التعليمات البرمجية التالية كيفية استدعاء pretrigger باستخدام .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);

توضح التعليمات البرمجية التالية كيفية تسجيل pretrigger باستخدام .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
});

توضح التعليمات البرمجية التالية كيفية استدعاء pretrigger باستخدام .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" } });

توضح التعليمات البرمجية التالية كيفية تسجيل pretrigger باستخدام 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);

توضح التعليمات البرمجية التالية كيفية استدعاء pretrigger باستخدام 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);

توضح التعليمات البرمجية التالية كيفية تسجيل pretrigger باستخدام 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"
});

توضح التعليمات البرمجية التالية كيفية استدعاء pretrigger باستخدام 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]});

توضح التعليمات البرمجية التالية كيفية تسجيل pretrigger باستخدام 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)

توضح التعليمات البرمجية التالية كيفية استدعاء pretrigger باستخدام Python SDK:

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

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

كيفية تشغيل المشغلات اللاحقة

توضح الأمثلة التالية كيفية تسجيل المشغل اللاحق باستخدام Azure Cosmos DB SDKs. للحصول على مصدر مثال المشغل اللاحق، المحفوظ ك 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);

توضح التعليمات البرمجية التالية كيفية تسجيل مشغل لاحق باستخدام .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
});

توضح التعليمات البرمجية التالية كيفية تسجيل مشغل لاحق باستخدام .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" } });

توضح التعليمات البرمجية التالية كيفية تسجيل مشغل لاحق باستخدام 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);

توضح التعليمات البرمجية التالية كيفية استدعاء مشغل لاحق باستخدام 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);

توضح التعليمات البرمجية التالية كيفية تسجيل مشغل لاحق باستخدام 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"
});

توضح التعليمات البرمجية التالية كيفية استدعاء مشغل لاحق باستخدام 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]});

توضح التعليمات البرمجية التالية كيفية تسجيل مشغل لاحق باستخدام 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)

توضح التعليمات البرمجية التالية كيفية استدعاء مشغل لاحق باستخدام Python SDK:

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

كيفية العمل مع الوظائف المعرفة من قِبَل المستخدم

توضح الأمثلة التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام Azure Cosmos DB SDKs. للحصول على مصدر مثال الدالة المعرفة من قبل المستخدم، المحفوظ ك 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
}

توضح التعليمات البرمجية التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام .NET SDK V3:

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

توضح التعليمات البرمجية التالية كيفية استدعاء دالة معرّفة من قِبَل المستخدم باستخدام .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
    }
}

توضح التعليمات البرمجية التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام Java SDK:

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

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

توضح التعليمات البرمجية التالية كيفية استدعاء دالة معرّفة من قِبَل المستخدم باستخدام 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);

توضح التعليمات البرمجية التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام JavaScript SDK:

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

توضح التعليمات البرمجية التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام 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();

توضح التعليمات البرمجية التالية كيفية تسجيل دالة معرّفة من قِبَل المستخدم باستخدام 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)

توضح التعليمات البرمجية التالية كيفية استدعاء دالة معرّفة من قِبَل المستخدم باستخدام Python SDK:

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

الخطوات التالية

تعرّف على مزيد من المفاهيم وكيفية كتابة الإجراءات المخزنة والمشغلات والدالات المعرّفة من قِبَل لمستخدم أو استخدامها في Azure Cosmos DB:

مشاركة عبر