Criar gatilhos e funções definidas pelo usuário

  • 3 minutos

O Azure Cosmos DB dá suporte a pré-gatilhos e pós-gatilhos. Os pré-gatilhos são executados antes da modificação de um item do banco de dados e os pós-gatilhos são executados após essa modificação. Os gatilhos não são executados automaticamente e precisam ser especificados para cada operação de banco de dados em que você deseja executá-los. Depois de definir um gatilho, você deve registrá-lo usando os SDKs do Azure Cosmos DB.

Para obter exemplos de como registrar e chamar um gatilho, confira pré-gatilhos e pós-gatilhos.

Pré-gatilhos

O exemplo a seguir mostra como um pré-gatilho é usado para validar as propriedades de um item do Azure Cosmos que está sendo criado. Ele adiciona uma propriedade de carimbo de data/hora a um item recém-adicionado, quando ele não a contém.

function validateToDoItemTimestamp() {
    var context = getContext();
    var request = context.getRequest();

    // item to be created in the current operation
    var itemToCreate = request.getBody();

    // validate properties
    if (!("timestamp" in itemToCreate)) {
        var ts = new Date();
        itemToCreate["timestamp"] = ts.getTime();
    }

    // update the item that will be created
    request.setBody(itemToCreate);
}

Os pré-gatilhos não podem ter parâmetros de entrada. O objeto de solicitação no gatilho é usado para manipular a mensagem de solicitação associada à operação. No exemplo anterior, o pré-gatilho é executado ao criar um item do Azure Cosmos e o corpo da mensagem de solicitação contém o item a ser criado no formato JSON.

Quando os gatilhos são registrados, é possível especificar as operações com as quais eles podem ser executados. Esse gatilho deve ser criado com um valor TriggerOperation de TriggerOperation.Create, o que significa que não é permitido usar o gatilho em uma operação de substituição.

Para obter exemplos de como registrar e chamar um pré-gatilho, visite o artigo de pré-gatilhos.

Pós-gatilhos

O exemplo a seguir mostra um pós-gatilho. Este gatilho consulta o item de metadados e o atualiza com detalhes sobre o item recém-criado.

function updateMetadata() {
var context = getContext();
var container = context.getCollection();
var response = context.getResponse();

// item that was created
var createdItem = response.getBody();

// query for metadata document
var filterQuery = 'SELECT * FROM root r WHERE r.id = "_metadata"';
var accept = container.queryDocuments(container.getSelfLink(), filterQuery,
    updateMetadataCallback);
if(!accept) throw "Unable to update metadata, abort";

function updateMetadataCallback(err, items, responseOptions) {
    if(err) throw new Error("Error" + err.message);
        if(items.length != 1) throw 'Unable to find metadata document';

        var metadataItem = items[0];

        // update metadata
        metadataItem.createdItems += 1;
        metadataItem.createdNames += " " + createdItem.id;
        var accept = container.replaceDocument(metadataItem._self,
            metadataItem, function(err, itemReplaced) {
                    if(err) throw "Unable to update metadata, abort";
            });
        if(!accept) throw "Unable to update metadata, abort";
        return;
    }
}

É importante observar a execução transacional de gatilhos no Azure Cosmos DB. O pós-gatilho é executado como parte da mesma transação para o próprio item subjacente. Uma exceção durante a execução do pós-gatilho resultará em uma falha em toda a transação. Tudo o que estiver confirmado será revertido, e uma exceção será retornada.

Funções definidas pelo usuário

O exemplo a seguir cria uma UDF para calcular o imposto de renda para várias faixas de renda. Essa função definida pelo usuário deve ser usada dentro de uma consulta. Para os fins deste exemplo, suponha que há um contêiner chamado "Rendas" com as seguintes propriedades:

{
   "name": "User One",
   "country": "USA",
   "income": 70000
}

A seguir, há uma definição de função para calcular o imposto de renda para várias faixas de renda:

function tax(income) {

        if(income == undefined)
            throw 'no input';

        if (income < 1000)
            return income * 0.1;
        else if (income < 10000)
            return income * 0.2;
        else
            return income * 0.4;
    }