Partilhar via


Como registar e utilizar procedimentos armazenados, acionadores e funções definidas pelo utilizador 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) escritas em JavaScript. Depois de 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 a API para SDK NoSQL em várias plataformas, incluindo .NET v2 (legado), .NET v3, Java, JavaScript ou Python SDKs para executar essas tarefas. Se você não trabalhou com um desses SDKs antes, consulte o artigo de início rápido para o SDK apropriado:

SDK Introdução
.NET v3 Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para NoSQL para .NET
Java Guia de início rápido: criar um aplicativo Java para gerenciar o Azure Cosmos DB para dados NoSQL
JavaScript Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para NoSQL para Node.js
Python Guia de início rápido: biblioteca de cliente do Azure Cosmos DB para NoSQL para Python

Importante

Os exemplos de código a seguir pressupõem que você já tenha variáveis client e container . 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 em 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 escrever 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 procedimento armazenado, salvo como spCreateToDoItem.js, consulte Criar itens usando procedimentos armazenados.

Nota

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 definidos como 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. Este princípio também se aplica aos fatores de desencadeamento.

O exemplo a seguir mostra como registrar 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 a seguir 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 });

Como executar pré-gatilhos

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

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

Nota

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

Como executar pós-gatilhos

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

O código a seguir mostra como registrar um pós-gatilho 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 a seguir mostra como chamar um pós-gatilho 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);

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 obter a origem deste exemplo de função definida pelo usuário, salva 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 .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 a seguir mostra como chamar uma função definida pelo usuário 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
}

Próximos passos

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