Créer les procédures stockées
Azure Cosmos DB fournit une exécution transactionnelle avec langage intégré de JavaScript qui vous permet d’écrire des procédures stockées, des déclencheurs et des fonctions définies par l’utilisateur. Pour appeler une procédure stockée, un déclencheur ou une fonction définie par l’utilisateur, vous devez les enregistrer. Pour plus d’informations, consultez How to register and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB (Comment inscrire et utiliser des procédures stockées, des déclencheurs et des fonctions définies par l’utilisateur dans Azure Cosmos DB).
Notes
Cette unité se concentre sur les procédures stockées, tandis que l’unité suivante aborde 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 dans un conteneur Azure Cosmos. Les procédures stockées sont enregistrées par collection, et elles peuvent s’appliquer à tout document ou pièce jointe figurant dans cette collection.
Voici une simple procédure stockée qui renvoie 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 donne accès à toutes les opérations pouvant être effectuées dans Azure Cosmos DB, ainsi que l’accès aux objets de demande et de réponse. En l’occurrence, vous utilisez l’objet de réponse pour définir le corps de la réponse renvoyée au client.
Créer un élément à l’aide de la procédure stockée
Quand vous créez un élément à l’aide d’une procédure stockée, il 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 varie selon les fonctions de rappel JavaScript. La fonction de rappel comporte 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 le cas présent, l’objet créé. À l’intérieur du rappel, vous pouvez gérer l’exception ou générer une erreur. Si aucun rappel n’est fourni et qu’une erreur se produit, 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 sous forme de valeur booléenne. Lorsque le paramètre est défini sur true 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 prend en entrée documentToCreate, le corps d'un document à créer dans la collection actuelle. Toutes ces opérations sont asynchrones et dépendent de 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 en tant que 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 sous forme d’entrée, le tableau est converti en chaîne et envoyé à la procédure stockée. Pour contourner cela, vous pouvez définir une fonction à l’intérieur de votre procédure stockée pour que la chaîne soit analysée 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 être effectuées dans un laps de temps limité. Les procédures stockées sont limitées dans le temps pour s’exécuter sur le serveur. Toutes les fonctions de collection retournent une valeur booléenne qui indique si cette opération est effectuée ou pas.
Transactions dans des procédures stockées
Vous pouvez implémenter des transactions sur des éléments dans un conteneur à l’aide d’une procédure stockée. Les fonctions JavaScript peuvent implémenter un modèle basé sur la continuation 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.
