Créer des procédures stockées

Effectué

Azure Cosmos DB fournit une exécution transactionnelle intégrée au langage de JavaScript qui vous permet d’écrire des procédures stockées , déclencheet fonctions définies par l’utilisateur (UDF). Pour appeler une procédure stockée, un déclencheur ou une fonction définie par l’utilisateur, vous devez l’inscrire. Pour plus d’informations, consultez Comment utiliser des procédures stockées, des déclencheurs, des fonctions définies par l’utilisateur dans Azure Cosmos DB.

Note

Cette unité se concentre sur les procédures stockées, l’unité suivante couvre les déclencheurs et les fonctions définies par l’utilisateur.

Écriture de procédures stockées

Les procédures stockées peuvent créer, mettre à jour, lire, interroger et supprimer des éléments à l’intérieur d’un conteneur Azure Cosmos. Les procédures stockées sont inscrites par collection et peuvent fonctionner sur n’importe quel document ou pièce jointe présent dans cette collection.

Voici une procédure stockée simple qui retourne une réponse « Hello World ».

var helloWorldStoredProc = {
    id: "helloWorld",
    serverScript: function () {
        var context = getContext();
        var response = context.getResponse();

        response.setBody("Hello, World");
    }
}

L’objet de contexte fournit l’accès à toutes les opérations qui peuvent être effectuées dans Azure Cosmos DB et à l’accès aux objets de requête et de réponse. Dans ce cas, vous utilisez l’objet réponse pour définir le corps de la réponse à renvoyer au client.

Créer un élément à l’aide de la procédure stockée

Lorsque vous créez un élément à l’aide d’une procédure stockée, l’élément est inséré dans le conteneur Azure Cosmos DB et un ID pour l’élément nouvellement créé est retourné. La création d’un élément est une opération asynchrone et dépend des fonctions de rappel JavaScript. La fonction de rappel a deux paramètres : un pour l’objet d’erreur en cas d’échec de l’opération, et un autre pour une valeur de retour, dans ce cas, l’objet créé. Dans la fonction de rappel, vous pouvez soit gérer l'exception, soit lever une erreur. Si un rappel n’est pas fourni et qu’il existe une erreur, le runtime Azure Cosmos DB génère une erreur.

La procédure stockée inclut également un paramètre pour définir la description en tant que valeur booléenne. Lorsque le paramètre est défini sur vrai et que la description est manquante, la procédure stockée lève une exception. Sinon, le reste de la procédure stockée continue de s’exécuter.

Cette procédure stockée reçoit en entrée documentToCreate, le corps d’un document à créer dans la collection actuelle. Toutes ces opérations sont asynchrones et dépendent des rappels de fonction JavaScript.

var createDocumentStoredProc = {
    id: "createMyDocument",
    body: function createMyDocument(documentToCreate) {
        var context = getContext();
        var collection = context.getCollection();
        var accepted = collection.createDocument(collection.getSelfLink(),
              documentToCreate,
              function (err, documentCreated) {
                  if (err) throw new Error('Error' + err.message);
                  context.getResponse().setBody(documentCreated.id)
              });
        if (!accepted) return;
    }
}

Tableaux comme paramètres d'entrée pour les procédures stockées

Lors de la définition d’une procédure stockée dans le portail Azure, les paramètres d’entrée sont toujours envoyés sous forme de chaîne à la procédure stockée. Même si vous passez un tableau de chaînes en tant qu’entrée, le tableau est converti en chaîne et envoyé à la procédure stockée. Pour contourner ce problème, vous pouvez définir une fonction dans votre procédure stockée pour analyser la chaîne en tant que tableau. Le code suivant montre comment analyser un paramètre d’entrée de chaîne en tant que tableau :

function sample(arr) {
    if (typeof arr === "string") arr = JSON.parse(arr);

    arr.forEach(function(a) {
        // do something here
        console.log(a);
    });
}

Exécution limitée

Toutes les opérations Azure Cosmos DB doivent se terminer dans un délai limité. Les procédures stockées ont un temps limité à s’exécuter sur le serveur. Toutes les fonctions de collection retournent une valeur booléenne qui indique si cette opération se termine ou non

Transactions dans les procédures stockées

Vous pouvez implémenter des transactions sur des éléments d’un conteneur à l’aide d’une procédure stockée. Les fonctions JavaScript peuvent implémenter un modèle basé sur les continuations pour traiter ou reprendre l’exécution. La valeur de continuation peut être n’importe quelle valeur de votre choix et vos applications peuvent ensuite utiliser cette valeur pour reprendre une transaction à partir d’un nouveau point de départ. Le diagramme suivant montre comment le modèle de continuation de transaction peut être utilisé pour répéter une fonction côté serveur jusqu’à ce que la fonction termine toute sa charge de travail de traitement.