Compartilhar via


Como registrar e usar procedimentos armazenados, gatilhos e funções definidas pelo usuário no Azure Cosmos DB

APLICA-SE A: NoSQL

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. Após definir um ou mais procedimentos armazenados, gatilhos ou funções definidas pelo usuário, você pode carregá-los e exibi-los no portal do Azure usando o Data Explorer.

Você pode usar o SDK de API para NoSQL em várias plataformas, incluindo SDKs .NET v2 (herdado), .NET v3, Java, JavaScript ou Python para fazer essas tarefas. Se você nunca trabalhou com um desses SDKs antes, confira o artigo início rápido para o SDK apropriado:

. Introdução
.NET v3 Início Rápido: biblioteca de cliente do Azure Cosmos DB for NoSQL para .NET
Java Início Rápido: criar um aplicativo Java para gerenciar os dados do Azure Cosmos DB for NoSQL
JavaScript Início Rápido: Biblioteca de clientes do Azure Cosmos DB for NoSQL para Node.js
Python Guia de Início Rápido: Biblioteca de clientes do Azure Cosmos DB for NoSQL para Python

Importante

Os exemplos de código a seguir pressupõem que você já tenha client e container variáveis. Se você precisar criar essas variáveis, consulte o início rápido apropriado para sua plataforma.

Como executar procedimentos armazenados

Os procedimentos armazenados são escritos usando JavaScript. Eles podem criar, atualizar, ler, consultar e excluir itens dentro de 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 a origem deste procedimento armazenado, salvo como spCreateToDoItem.js, consulte Criar itens usando procedimentos armazenados.

Observação

Para contêineres particionados, quando você executa um procedimento armazenado, você deve fornecer um valor chave de partição nas opções de solicitação. O escopo dos procedimentos armazenados sempre é uma chave de partição. Os itens com um valor de chave de partição diferente não são visíveis para o procedimento armazenado. Este princípio também se aplica aos gatilhos.

O seguinte exemplo 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 seguinte código 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 });

Como executar os pré-disparadores

Os exemplos a seguir mostram como registrar e chamar um pré-disparador usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo de pré-disparador, salvo como trgPreValidateToDoItemTimestamp.js, consulte Pré-disparadores.

Quando você executa uma operação especificando PreTriggerInclude e passando o nome do gatilho em um objeto List, os pré-disparadores são passados no objeto RequestOptions.

Observação

Mesmo que o nome do gatilho seja transmitido como uma List, você ainda é pode executar apenas um gatilho por operação.

O código a seguir mostra como registrar um pré-disparador 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 a seguir mostra como chamar um pré-disparador 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);

Como executar pós-gatilhos

Os exemplos a seguir mostram como registrar um pós-gatilho usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo de pós-gatilho, salvo como trgPostUpdateMetadata.js, consulte Pós-gatilhos

O seguinte código mostra como registrar um pós-gatilho usando o 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 seguinte código mostra como chamar um pós-gatilho usando o SDK do .NET 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);

Como trabalhar com funções definidas pelo usuário

Os exemplos a seguir mostram como registrar uma função definida pelo usuário usando os SDKs do Azure Cosmos DB. Para a origem deste exemplo de função definida pelo usuário, salvo como udfTax.js, consulte Como gravar funções definidas pelo usuário.

O seguinte código 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 seguinte código 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
}

Próximas etapas

Aprenda mais conceitos e como escrever ou usar procedimentos armazenados, gatilhos e funções definidas pelo usuário no Azure Cosmos DB: