Postup registrace a používání uložených procedur, triggerů a funkcí definovaných uživatelem ve službě Azure Cosmos DB

PLATÍ PRO: NoSQL

Rozhraní API pro NoSQL ve službě Azure Cosmos DB podporuje registraci a vyvolání uložených procedur, triggerů a uživatelem definovaných funkcí (UDF) napsaných v JavaScriptu. Po definování jedné nebo více uložených procedur, triggerů nebo uživatelem definovaných funkcí je můžete načíst a zobrazit na webu Azure Portal pomocí Průzkumníka dat.

K těmto úlohám můžete použít rozhraní API pro sadu NoSQL SDK na různých platformách, včetně .NET v2 (starší verze), .NET v3, Java, JavaScriptu nebo sad Python SDK. Pokud jste ještě s některou z těchto sad SDK nepracovali, projděte si článek rychlý start pro příslušnou sadu SDK:

Sada SDK	Začínáme
.NET v3	Rychlý start: Klientská knihovna Azure Cosmos DB for NoSQL pro .NET
Java	Rychlý start: Vytvoření aplikace v Javě pro správu dat Azure Cosmos DB for NoSQL
JavaScript	Rychlý start: Klientská knihovna Azure Cosmos DB for NoSQL pro Node.js
Python	Rychlý start: Klientská knihovna Azure Cosmos DB for NoSQL pro Python

Důležité

Následující ukázky kódu předpokládají, že již máte client a container proměnné. Pokud tyto proměnné potřebujete vytvořit, projděte si příslušný rychlý start pro vaši platformu.

Spouštění uložených procedur

Uložené procedury se zapisují pomocí JavaScriptu. Můžou vytvářet, aktualizovat, číst, dotazovat a odstraňovat položky v kontejneru Azure Cosmos DB. Další informace naleznete v tématu Jak psát uložené procedury.

Následující příklady ukazují, jak zaregistrovat a volat uloženou proceduru pomocí sad SDK služby Azure Cosmos DB. Zdroj pro tuto uloženou proceduru uložený jako spCreateToDoItem.js naleznete v tématu Vytváření položek pomocí uložených procedur.

Poznámka:

V případě dělených kontejnerů musíte při spuštění uložené procedury zadat hodnotu klíče oddílu v možnostech požadavku. Uložené procedury jsou vždy vymezeny na klíč oddílu. Položky, které mají jinou hodnotu klíče oddílu, nejsou viditelné pro uloženou proceduru. Tento princip platí také pro triggery.

.NET SDK v2

Následující příklad ukazuje, jak zaregistrovat uloženou proceduru pomocí sady .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;

Následující kód ukazuje, jak volat uloženou proceduru pomocí sady .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

Následující příklad ukazuje, jak zaregistrovat uloženou proceduru pomocí sady .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")
});

Následující kód ukazuje, jak volat uloženou proceduru pomocí sady .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

Následující příklad ukazuje, jak zaregistrovat uloženou proceduru pomocí sady Java SDK:

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

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

Následující kód ukazuje, jak volat uloženou proceduru pomocí sady 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

Následující příklad ukazuje, jak zaregistrovat uloženou proceduru pomocí sady JavaScript SDK:

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

Následující kód ukazuje, jak volat uloženou proceduru pomocí sady 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

Následující příklad ukazuje, jak zaregistrovat uloženou proceduru pomocí sady 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) 

Následující kód ukazuje, jak volat uloženou proceduru pomocí sady 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) 

Jak spouštět pretriggery

Následující příklady ukazují, jak zaregistrovat a volat pretrigger pomocí sad SDK služby Azure Cosmos DB. Zdroj tohoto příkladu pretriggeru, který je uložený jako trgPreValidateToDoItemTimestamp.js, najdete v tématu Pretriggery.

Při spuštění operace zadáním PreTriggerInclude a předáním názvu triggeru v objektu List se předávají pretriggery v objektu RequestOptions .

Poznámka:

I když se název triggeru předává jako název List, stále můžete spustit pouze jednu aktivační událost pro každou operaci.

.NET SDK v2

Následující kód ukazuje, jak zaregistrovat pretrigger pomocí sady .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);

Následující kód ukazuje, jak volat pretrigger pomocí sady .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);

.NET SDK v3

Následující kód ukazuje, jak zaregistrovat pretrigger pomocí sady .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
});

Následující kód ukazuje, jak volat pretrigger pomocí sady .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" } });

Java SDK

Následující kód ukazuje, jak zaregistrovat pretrigger pomocí sady 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);

Následující kód ukazuje, jak volat pretrigger pomocí sady 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);

JavaScript

Následující kód ukazuje, jak zaregistrovat pretrigger pomocí sady 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"
});

Následující kód ukazuje, jak volat pretrigger pomocí sady 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]});

Python SDK

Následující kód ukazuje, jak zaregistrovat pretrigger pomocí sady 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)

Následující kód ukazuje, jak volat pretrigger pomocí sady Python SDK:

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

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

Spuštění triggerů po spuštění

Následující příklady ukazují, jak zaregistrovat trigger po spuštění pomocí sad SDK služby Azure Cosmos DB. Zdroj tohoto příkladu po triggeru, který je uložený jako trgPostUpdateMetadata.js, najdete v tématu Post-triggery.

.NET SDK v2

Následující kód ukazuje, jak zaregistrovat post-trigger pomocí sady .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);

Následující kód ukazuje, jak volat post-trigger pomocí sady .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

Následující kód ukazuje, jak zaregistrovat post-trigger pomocí sady .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
});

Následující kód ukazuje, jak volat post-trigger pomocí sady .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

Následující kód ukazuje, jak zaregistrovat post-trigger pomocí sady 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);

Následující kód ukazuje, jak volat post-trigger pomocí sady 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

Následující kód ukazuje, jak zaregistrovat post-trigger pomocí sady 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"
});

Následující kód ukazuje, jak volat post-trigger pomocí sady 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

Následující kód ukazuje, jak zaregistrovat post-trigger pomocí sady 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)

Následující kód ukazuje, jak volat post-trigger pomocí sady Python SDK:

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

Jak pracovat s uživatelem definovanými funkcemi

Následující příklady ukazují, jak zaregistrovat uživatelem definovanou funkci pomocí sad SDK služby Azure Cosmos DB. Zdroj tohoto uživatelem definovaného příkladu funkce, který je uložený jako udfTax.js, najdete v tématu Jak psát uživatelem definované funkce.

.NET SDK v2

Následující kód ukazuje, jak zaregistrovat uživatelem definovanou funkci pomocí sady .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);

Následující kód ukazuje, jak volat uživatelem definovanou funkci pomocí sady .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

Následující kód ukazuje, jak zaregistrovat uživatelem definovanou funkci pomocí sady .NET SDK v3:

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

Následující kód ukazuje, jak volat uživatelem definovanou funkci pomocí sady .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

Následující kód ukazuje, jak zaregistrovat uživatelem definovanou funkci pomocí sady Java SDK:

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

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

Následující kód ukazuje, jak volat uživatelem definovanou funkci pomocí sady 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

Následující kód ukazuje, jak zaregistrovat uživatelem definovanou funkci pomocí sady JavaScript SDK:

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

Následující kód ukazuje, jak volat uživatelem definovanou funkci pomocí sady 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

Následující kód ukazuje, jak zaregistrovat uživatelem definovanou funkci pomocí sady 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)

Následující kód ukazuje, jak volat uživatelem definovanou funkci pomocí sady Python SDK:

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

Další kroky

Přečtěte si další koncepty a postupy pro zápis nebo používání uložených procedur, triggerů a uživatelem definovaných funkcí ve službě Azure Cosmos DB:

• Uložené procedury, triggery a uživatelem definované funkce
• Rozhraní API pro dotazy v JavaScriptu ve službě Azure Cosmos DB