A API para NoSQL no Azure Cosmos DB dá suporte ao registro e à invocação de procedimentos armazenados, gatilhos e UDFs (funções definidas pelo usuário) escritos em JavaScript. Depois de definir um ou mais procedimentos armazenados, gatilhos ou UDFs, você poderá carregá-los e exibi-los no portal do Azure usando o Data Explorer.
Você pode usar a API para SDK do NoSQL em várias plataformas, incluindo SDKs do .NET v2 (herdado),.NET v3, Java, JavaScript ou Python para realizar essas tarefas. Se você ainda não trabalhou com um desses SDKs antes, consulte o artigo de início rápido para o SDK apropriado:
Importante
Os exemplos de código a seguir pressupõem que você já tem client e container variáveis. Se você precisar criar essas variáveis, consulte o guia de início rápido adequado para sua plataforma.
Como executar procedimentos armazenados
Os procedimentos armazenados são escritos em JavaScript. Eles podem criar, atualizar, ler, consultar e excluir itens em um contêiner do Azure Cosmos DB. Para obter mais informações, consulte Como gravar procedimentos armazenados.
Os exemplos a seguir mostram como registrar e chamar um procedimento armazenado usando os SDKs do Azure Cosmos DB. Para obter a origem deste exemplo, salvo como spCreateToDoItem.js, consulte Criar itens usando procedimentos armazenados.
Observação
Para contêineres particionados, ao executar um procedimento armazenado, você deve fornecer um valor de chave de partição nas opções de solicitação. Os procedimentos armazenados são sempre associados a uma chave de partição. Os itens que têm um valor de chave de partição diferente não são visíveis para o procedimento armazenado. Esse princípio também se aplica a gatilhos.
O exemplo a seguir mostra como registrar um procedimento armazenado usando o SDK do .NET 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 a seguir mostra como chamar um procedimento armazenado usando o SDK do .NET 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 a seguir mostra como registrar um procedimento armazenado usando o SDK do .NET 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 a seguir mostra como chamar um procedimento armazenado usando o SDK do .NET 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 a seguir mostra como registrar um procedimento armazenado usando o SDK do Java:
CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
"spCreateToDoItems",
Files.readString(Paths.get("createToDoItems.js"))
);
CosmosStoredProcedureResponse response = container
.getScripts()
.createStoredProcedure(definition);
O código a seguir mostra como chamar um procedimento armazenado usando o SDK do Java:
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 a seguir mostra como registrar um procedimento armazenado usando o SDK do 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 a seguir mostra como chamar um procedimento armazenado usando o SDK do 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 a seguir mostra como registrar um procedimento armazenado usando o SDK do 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 a seguir mostra como chamar um procedimento armazenado usando o SDK do 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é-gatilhos
Os exemplos a seguir mostram como registrar e chamar um pré-acionador usando os SDKs do Azure Cosmos DB. Para obter a origem desse exemplo de pré-gatilho, salvo como trgPreValidateToDoItemTimestamp.js, consulte Pré-gatilhos.
Quando você executa uma operação especificando PreTriggerInclude e, em seguida, passa o nome do desencadeador em um objeto List, os pré-desencadeadores são passados em objetos RequestOptions.
Observação
Mesmo que o nome do gatilho seja passado como um List, você ainda pode executar apenas um gatilho por operação.
O código a seguir mostra como registrar um pré-gatilho usando o SDK do .NET 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 a seguir mostra como chamar um pré-gatilho 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 código a seguir mostra como registrar um pré-trigger usando o SDK do .NET 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 código a seguir mostra como chamar um pré-gatilho usando o SDK do .NET 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 a seguir mostra como registrar um gatilho prévio usando o SDK do Java:
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 a seguir mostra como chamar um gatilho prévio usando SDK do Java.
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 a seguir mostra como registrar um pré-gatilho usando o SDK do JavaScript:
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"
});
Código a seguir mostra como chamar um pre-trigger usando o SDK do JavaScript:
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 a seguir mostra como registrar um pré-trigger utilizando o 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)
O código a seguir mostra como chamar um pré-gatilho usando o SDK do Python:
item = {'category': 'Personal', 'name': 'Groceries',
'description': 'Pick up strawberries', 'isComplete': False}
result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')
Como executar gatilhos pós-processamento
Os exemplos a seguir mostram como registrar um trigger pós-execução usando os SDKs do Azure Cosmos DB. Para obter a origem desse exemplo pós-gatilho, salvo como trgPostUpdateMetadata.js, consulte Post-triggers
O código a seguir mostra como registrar um disparador pós-uso do SDK do .NET 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 a seguir mostra como chamar um gatilho pós-processamento 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 a seguir demonstra como registrar um pós-trigger usando o SDK .NET 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 a seguir mostra como chamar um pós-acionador usando o SDK .NET 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 a seguir mostra como registrar um pós-trigger usando o SDK do Java:
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 a seguir mostra como chamar um gatilho pós-processamento 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 a seguir mostra como registrar um post-trigger usando o SDK do 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 a seguir mostra como chamar um pós-gatilho usando o SDK do JavaScript:
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 código a seguir mostra como registrar um gatilho pós-processamento usando 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 a seguir mostra como chamar um gatilho posterior 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 usuário
Os exemplos a seguir mostram como registrar uma UDF usando os SDKs do Azure Cosmos DB. Para obter a origem deste exemplo, salvo como udfTax.js, consulte Como escrever funções definidas pelo usuário.
O código a seguir mostra como registrar uma função definida pelo usuário usando o SDK do .NET 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 a seguir mostra como chamar uma função definida pelo usuário usando o SDK do .NET 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 código a seguir mostra como registrar uma função definida pelo usuário usando o SDK do .NET v3:
await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
Id = "Tax",
Body = File.ReadAllText(@"..\js\Tax.js")
});
O código a seguir mostra como chamar uma função definida pelo usuário usando o SDK do .NET 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 a seguir mostra como registrar uma função definida pelo usuário usando o SDK do Java:
CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
"udfTax",
Files.readString(Paths.get("tax.js"))
);
CosmosUserDefinedFunctionResponse response = container
.getScripts()
.createUserDefinedFunction(definition);
O código a seguir mostra como chamar uma função definida pelo usuário usando o SDK do Java:
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
CosmosPagedIterable<ToDoItem> iterable = container.queryItems(
"SELECT t.cost, udf.udfTax(t.cost) AS costWithTax FROM t",
options,
ToDoItem.class);
O código a seguir mostra como registrar uma função definida pelo usuário usando o SDK do JavaScript:
const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
id: udfId,
body: require(`../js/${udfId}`)
O código a seguir mostra como chamar uma função definida pelo usuário usando o SDK do JavaScript:
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 código a seguir mostra como registrar uma função definida pelo usuário usando o SDK do 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 código a seguir mostra como chamar uma função definida pelo usuário usando o SDK do Python:
results = list(container.query_items(
'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))
Próximas etapas