A API para NoSQL no Azure Cosmos DB suporta o registo e invocação de procedimentos armazenados, triggers e funções definidas pelo utilizador (UDFs) escritas em JavaScript. Depois de definir um ou mais procedimentos armazenados, triggers ou UDFs, pode carregá-los e visualizá-los no portal Azure usando o Data Explorer.
Pode usar a API do SDK NoSQL em várias plataformas, incluindo .NET v2 (legacy), .NET v3, Java, JavaScript ou Python SDKs para realizar estas tarefas. Se nunca trabalhou com um destes SDKs antes, veja o artigo de início rápido para o SDK apropriado:
Importante
Os exemplos de código seguintes assumem que já tens client variáveis e container . Se precisar de criar essas variáveis, consulte o quickstart apropriado para a sua plataforma.
Como executar procedimentos armazenados
Os procedimentos armazenados são escritos usando JavaScript. Podem criar, atualizar, ler, consultar e eliminar itens dentro de um contentor Azure Cosmos DB. Para mais informações, veja Como escrever procedimentos armazenados.
Os exemplos seguintes mostram como registar e chamar um procedimento armazenado usando os SDKs do Azure Cosmos DB. Para a fonte deste exemplo, guardada como spCreateToDoItem.js, veja Criar itens usando procedimentos armazenados.
Observação
Para contentores particionados, quando executa um procedimento armazenado, deve fornecer um valor de chave de partição nas opções de pedido. Os procedimentos armazenados estão sempre associados a uma chave de partição. Itens que têm um valor de chave de partição diferente não são visíveis para o procedimento armazenado. Este princípio aplica-se também aos gatilhos.
O exemplo seguinte mostra como registar um procedimento armazenado usando o .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;
O código seguinte mostra como chamar um procedimento armazenado usando o .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 });
O exemplo seguinte mostra como registar um procedimento armazenado usando o .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")
});
O código seguinte mostra como chamar um procedimento armazenado usando o .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 });
O exemplo seguinte mostra como registar um procedimento armazenado usando o SDK Java:
CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
"spCreateToDoItems",
Files.readString(Paths.get("createToDoItems.js"))
);
CosmosStoredProcedureResponse response = container
.getScripts()
.createStoredProcedure(definition);
O código seguinte mostra como chamar um procedimento armazenado usando o 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
);
O exemplo seguinte mostra como registar um procedimento armazenado usando o SDK JavaScript:
const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
await container.scripts.storedProcedures.create({
id: sprocId,
body: require(`../js/${sprocId}`)
});
O código seguinte mostra como chamar um procedimento armazenado usando o SDK JavaScript:
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});
O exemplo seguinte mostra como registar um procedimento armazenado usando o SDK Python:
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)
O código seguinte mostra como chamar um procedimento armazenado usando o SDK Python:
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)
Como executar pré-triggers
Os exemplos seguintes mostram como registar e chamar um pré-trigger usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo pré-trigger, guardado como trgPreValidateToDoItemTimestamp.js, veja Pre-triggers.
Quando executas uma operação especificando PreTriggerInclude e depois passando o nome do trigger num List objeto, os pré-triggers são passados no RequestOptions objeto.
Observação
Mesmo que o nome do gatilho seja passado como um List, ainda podes executar apenas um gatilho por operação.
O código seguinte mostra como registar um pré-trigger usando o .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);
O código seguinte mostra como chamar um pré-trigger usando o .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);
O seguinte código mostra como registar um pré-trigger usando o .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
});
O seguinte código mostra como chamar um pré-trigger usando o .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" } });
O código seguinte mostra como registar um pré-trigger usando o 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);
O código seguinte mostra como chamar um pré-trigger usando o 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);
O código seguinte mostra como registar um pré-trigger usando o 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"
});
O código seguinte mostra como chamar um pré-trigger usando o 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]});
O código seguinte mostra como registar um pré-trigger usando o SDK Python:
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)
O código seguinte mostra como chamar um pré-trigger usando o SDK Python:
item = {'category': 'Personal', 'name': 'Groceries',
'description': 'Pick up strawberries', 'isComplete': False}
result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')
Como correr após os gatilhos
Os exemplos seguintes mostram como registar um pós-trigger usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo pós-trigger, guardado como trgPostUpdateMetadata.js, consulte Post-triggers
O seguinte código mostra como registar um pós-acionador usando o .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);
O código seguinte mostra como chamar um post-trigger usando o .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);
O código seguinte mostra como registar um disparador pós-evento usando o .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
});
O código seguinte mostra como chamar um pós-trigger usando o .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" } });
O código seguinte mostra como registar um pós-trigger usando o 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);
O código seguinte mostra como chamar um pós-trigger usando o 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);
O código seguinte mostra como registar um pós-trigger usando o SDK JavaScript:
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"
});
O código seguinte mostra como chamar um pós-trigger usando o 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]});
O exemplo de código abaixo mostra como registar um pós-trigger utilizando o SDK do Python:
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)
O código seguinte mostra como chamar um pós-trigger usando o SDK do Python.
item = {'category': 'Personal', 'name': 'Groceries',
'description': 'Pick up strawberries', 'isComplete': False}
container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')
Como trabalhar com funções definidas pelo utilizador
Os exemplos seguintes mostram como registar um UDF usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo, guardada como udfTax.js, veja Como escrever funções definidas pelo utilizador.
O código seguinte mostra como registar uma função definida pelo utilizador usando o .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);
O código seguinte mostra como chamar uma função definida pelo utilizador usando o .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
}
O seguinte código mostra como registar uma função definida pelo utilizador usando o .NET SDK v3:
await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
Id = "Tax",
Body = File.ReadAllText(@"..\js\Tax.js")
});
O código seguinte mostra como chamar uma função definida pelo utilizador usando o .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
}
}
O código seguinte mostra como registar uma função definida pelo utilizador usando o Java SDK:
CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
"udfTax",
Files.readString(Paths.get("tax.js"))
);
CosmosUserDefinedFunctionResponse response = container
.getScripts()
.createUserDefinedFunction(definition);
O código seguinte mostra como chamar uma função definida pelo utilizador usando o 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);
O seguinte código mostra como registar uma função definida pelo utilizador usando o JavaScript SDK:
const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
id: udfId,
body: require(`../js/${udfId}`)
O código seguinte mostra como chamar uma função definida pelo utilizador usando o 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();
O seguinte código mostra como registar uma função definida pelo utilizador usando o SDK Python:
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)
O seguinte código mostra como chamar uma função definida pelo utilizador usando o SDK Python:
results = list(container.query_items(
'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))
Próximos passos