Créer des déclencheurs et des fonctions définies par l’utilisateur

  • 3 minutes

Azure Cosmos DB prend en charge les prédéclencheurs et les post-déclencheurs. Les prédéclencheurs sont exécutés avant la modification d’un élément de base de données, tandis que les post-déclencheurs sont exécutés après la modification d’un élément de base de données. Les déclencheurs ne sont pas exécutés automatiquement, ils doivent être spécifiés pour chaque opération de base de données où vous souhaitez qu’ils s’exécutent. Une fois que vous avez défini un déclencheur, vous devez l’enregistrer en utilisant les kits SDK Azure Cosmos DB.

Pour obtenir des exemples d’enregistrement et d’appel d’un déclencheur, consultez Prédéclencheurs et Post-déclencheurs.

Prédéclencheurs

L’exemple suivant montre comment un prédéclencheur est utilisé pour valider les propriétés d’un élément Azure Cosmos qui est en cours de création. Il ajoute une propriété d’horodatage à un élément qui vient d’être ajouté s’il n’en contient pas.

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);
}

Les prédéclencheurs ne peuvent pas avoir de paramètres d’entrée. L’objet de requête dans le déclencheur est utilisé pour manipuler le message de requête associé à l’opération. Dans l’exemple précédent, le prédéclencheur est exécuté lors de la création d’un élément Azure Cosmos, et le corps du message de requête contient l’élément qui doit être créé au format JSON.

Lorsque les déclencheurs sont inscrits, vous pouvez spécifier les opérations avec lesquelles ils peuvent s’exécuter. Ce déclencheur doit être créé avec une valeur TriggerOperation de TriggerOperation.Create, ce qui signifie que l’utilisation du déclencheur dans une opération de remplacement n’est pas autorisée.

Pour des exemples sur la façon d’enregistrer et d’appeler un prédéclencheur, consultez l’article Prédéclencheurs.

Post-déclencheurs

L’exemple suivant illustre un post-déclencheur. Ce déclencheur interroge l’élément de métadonnées et le met à jour avec des informations relatives à l’élément qui vient d’être créé.

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;
    }
}

Un élément important à noter est l’exécution transactionnelle des déclencheurs dans Azure Cosmos DB. Le post-déclencheur s’exécute dans le cadre de la même transaction pour l’élément sous-jacent lui-même. Une exception pendant l’exécution du post-déclencheur fait échouer toute la transaction. Tout ce qui est déjà validé est annulé et une exception est retournée.

Fonctions définies par l’utilisateur

L’exemple suivant crée une fonction définie par l’utilisateur pour calculer les impôts sur le revenu en fonction de diverses tranches de revenu. Cette fonction définie par l’utilisateur peut ensuite être utilisée dans une requête. Dans le cadre de cet exemple, supposons qu’il existe un conteneur appelé « Incomes » (Revenus) avec des propriétés semblables à ce qui suit :

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

Ce qui suit correspond à une définition de fonction pour calculer les impôts sur le revenu en fonction de diverses tranches de revenu :

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;
    }