Tárolt eljárások, eseményindítók és felhasználói függvények regisztrálása és használata az Azure Cosmos DB-ben

Cikk
03/18/2023

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Az Azure Cosmos DB NoSQL API-ja támogatja a JavaScriptben írt tárolt eljárások, triggerek és felhasználó által definiált függvények (UDF-ek) regisztrálását és meghívását. Miután definiált egy vagy több tárolt eljárást, eseményindítót vagy felhasználó által definiált függvényt, betöltheti és megtekintheti őket az Azure Portalon az Adatkezelő használatával.

A NoSQL SDK API-t több platformon is használhatja, beleértve a .NET v2 (örökölt), a .NET v3, a Java, a JavaScript vagy a Python SDK-kat ezen feladatok elvégzéséhez. Ha korábban még nem dolgozott ezen SDK-k egyikével, tekintse meg a megfelelő SDK rövid útmutatóját:

SDK	Első lépések
.NET v3	Rövid útmutató: Az Azure Cosmos DB for NoSQL ügyfélkódtár a .NET-hez
Java	Rövid útmutató: Java-alkalmazás létrehozása az Azure Cosmos DB for NoSQL-adatok kezeléséhez
JavaScript	Rövid útmutató: Azure Cosmos DB for NoSQL ügyfélkódtár Node.js
Python	Rövid útmutató: Azure Cosmos DB for NoSQL-ügyfélkódtár Pythonhoz

Fontos

Az alábbi kódminták feltételezik, hogy már rendelkezik client és container változókkal rendelkezik. Ha létre kell hoznia ezeket a változókat, tekintse meg a platform megfelelő rövid útmutatóját.

Tárolt eljárások futtatása

A tárolt eljárások JavaScript használatával vannak megírva. Létrehozhatnak, frissíthetnek, olvashatnak, lekérdezhetnek és törölhetnek elemeket egy Azure Cosmos DB-tárolóban. További információ: Tárolt eljárások írása.

Az alábbi példák bemutatják, hogyan regisztrálhat és hívhat meg tárolt eljárásokat az Azure Cosmos DB SDK-k használatával. A tárolt eljárás spCreateToDoItem.js ként mentett forrását lásd: Elemek létrehozása tárolt eljárásokkal.

Feljegyzés

Particionált tárolók esetén tárolt eljárás futtatásakor meg kell adnia egy partíciókulcs-értéket a kérés beállításai között. A tárolt eljárások mindig partíciókulcsra vannak korlátozva. Az eltérő partíciókulcs-értékkel rendelkező elemek nem láthatók a tárolt eljárásban. Ez az elv az eseményindítókra is vonatkozik.

Az alábbi példa bemutatja, hogyan regisztrálhat tárolt eljárást a .NET SDK v2 használatával:

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;

Az alábbi kód bemutatja, hogyan hívhat meg tárolt eljárást a .NET SDK v2 használatával:

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

Az alábbi példa bemutatja, hogyan regisztrálhat egy tárolt eljárást a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg tárolt eljárást a .NET SDK v3 használatával:

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

Az alábbi példa bemutatja, hogyan regisztrálhat egy tárolt eljárást a Java SDK használatával:

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

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

Az alábbi kód bemutatja, hogyan hívhat meg egy tárolt eljárást a Java SDK használatával:

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

Az alábbi példa bemutatja, hogyan regisztrálhat tárolt eljárást a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy tárolt eljárást a JavaScript SDK használatával:

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

Az alábbi példa bemutatja, hogyan regisztrálhat tárolt eljárást a Python SDK használatával:

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 következő kód bemutatja, hogyan hívhat meg egy tárolt eljárást a Python SDK használatával:

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)

Előpróbálkozók futtatása

Az alábbi példák bemutatják, hogyan regisztrálhat és hívhat meg egy előpróbálkozót az Azure Cosmos DB SDK-k használatával. A trgPreValidateToDoItemTimestamp.js ként mentett pretrigger-példa forrását lásd: Pretriggers.

Amikor egy műveletet úgy futtat, hogy megadja PreTriggerInclude , majd átadja az eseményindító nevét egy List objektumban, az előpróbálkozók az objektumban RequestOptions lesznek átadva.

Feljegyzés

Annak ellenére, hogy az eseményindító neve átadva van, műveletenként Listtovábbra is csak egy eseményindítót futtathat.

Az alábbi kód bemutatja, hogyan regisztrálhat egy előpróbálkozót a .NET SDK v2 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy pretriggert a .NET SDK v2 használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy pretriggert a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg előpróbálkozót a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy előpróbálkozót a Java SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy pretriggert a Java SDK használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy pretriggert a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy pretriggert a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy pretriggert a Python SDK használatával:

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)

Az alábbi kód bemutatja, hogyan hívhat meg egy pretriggert a Python SDK használatával:

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

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

Eseményindítók utáni futtatás

Az alábbi példák bemutatják, hogyan regisztrálhat egy eseményindítót az Azure Cosmos DB SDK-k használatával. A trgPostUpdateMetadata.js ként mentett, eseményindító utáni példa forrását lásd: Post-triggers

Az alábbi kód bemutatja, hogyan regisztrálhat egy eseményindítót a .NET SDK v2 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy eseményindítót a .NET SDK v2 használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy eseményindítót a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy eseményindítót a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy eseményindítót a Java SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy eseményindítót a Java SDK használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy eseményindítót a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy eseményindítót a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy eseményindítót a Python SDK használatával:

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)

Az alábbi kód bemutatja, hogyan hívhat meg egy eseményindítót a Python SDK használatával:

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

Felhasználó által definiált függvények használata

Az alábbi példák bemutatják, hogyan regisztrálhat felhasználó által definiált függvényeket az Azure Cosmos DB SDK-k használatával. A felhasználó által definiált, udfTax.js ként mentett példa forrását a Felhasználó által definiált függvények írása című témakörben találhatja meg.

Az alábbi kód bemutatja, hogyan regisztrálhat egy felhasználó által definiált függvényt a .NET SDK v2 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy felhasználó által definiált függvényt a .NET SDK v2 használatával:

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
}

Az alábbi kód bemutatja, hogyan regisztrálhat egy felhasználó által definiált függvényt a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy felhasználó által definiált függvényt a .NET SDK v3 használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy felhasználó által definiált függvényt a Java SDK használatával:

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

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

Az alábbi kód bemutatja, hogyan hívhat meg egy felhasználó által definiált függvényt a Java SDK használatával:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy felhasználó által definiált függvényt a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan hívhat meg egy felhasználó által definiált függvényt a JavaScript SDK használatával:

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

Az alábbi kód bemutatja, hogyan regisztrálhat egy felhasználó által definiált függvényt a Python SDK használatával:

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)

Az alábbi kód bemutatja, hogyan hívhat meg egy felhasználó által definiált függvényt a Python SDK használatával:

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

Következő lépések

További fogalmak és útmutató tárolt eljárások, triggerek és felhasználó által definiált függvények írásához vagy használatához az Azure Cosmos DB-ben: