Exercice : Écrire des données avec des liaisons de sortie

15 minutes

Dans l’exercice précédent, nous avons implémenté un scénario pour rechercher des signets dans une base de données Azure Cosmos DB. Nous avons configuré une liaison d’entrée pour lire des données dans notre collection de signets. Nous pouvons cependant en faire plus. Développons le scénario de façon à y inclure l’écriture. Examinez le diagramme de flux suivant :

Diagramme de flux décisionnel illustrant le processus d’ajout d’un signet dans le back-end Azure Cosmos DB et de renvoi d’une réponse

Dans ce scénario, nous recevons des demandes d’ajout de signets à notre collection. Les demandes passent en entrée la clé souhaitée (c’est-à-dire l’ID), ainsi que l’URL du signet. Comme vous pouvez le voir dans l’organigramme, nous répondons avec une erreur si la clé existe déjà dans notre back-end.

Si la clé qui nous a été passée est introuvable, nous ajoutons le nouveau signet à notre base de données. Nous pourrions nous arrêter là, mais nous allons en faire un peu plus.

Vous avez remarqué que l’organigramme comporte une autre étape ? Jusqu’à présent, nous n’avons pas fait grand-chose avec les données reçues en termes de traitement. Nous déplaçons simplement ce que nous recevons dans une base de données. Toutefois, dans une solution réelle, nous traiterions probablement les données d’une certaine manière. Nous pouvons effectuer tout le traitement dans la même fonction, mais dans cet exercice, nous présentons un modèle qui décharge le traitement ultérieur sur un autre composant ou élément de logique métier.

Dans notre scénario de signets, qu’est-ce qui pourrait constituer un bon exemple de ce déchargement du travail ? Et si nous envoyions le nouveau signet à un service de génération de code QR ? Ce service générerait à son tour un code QR pour l’URL, stockerait l’image dans le Stockage Blob et ajouterait l’adresse de l’image QR dans l’entrée de notre collection de signets. L’appel d’un service pour générer une image QR prend beaucoup de temps. Par conséquent, au lieu d’attendre le résultat, nous transmettons la tâche à une fonction et la laissons réaliser cette tâche de façon asynchrone.

Azure Functions prend en charge les liaisons d’entrée pour différentes sources d’intégration, mais offre également un ensemble de modèles de liaisons de sortie pour faciliter l’écriture de données dans des sources de données. Les liaisons de sortie sont également configurées dans le fichier function.json. Comme vous le voyez dans cet exercice, nous pouvons configurer notre fonction pour qu’elle fonctionne avec plusieurs sources de données et services.

Important

Cet exercice s’appuie sur les ressources du bac à sable et les ressources que vous avez créées dans les unités précédentes, en particulier la base de données, les signets et les liaisons d’entrée Azure Cosmos DB. Si vous n’avez pas effectué les exercices des unités précédentes, vous ne pourrez pas effectuer cet exercice.

Créer une fonction déclenchée via HTTP

Dans le portail Azure, accédez à l’application de fonction que vous avez créée en sélectionnant le nom de l’application de fonction dans le chemin de navigation en haut de la page de fonction HttpTrigger2.
Dans l’onglet Fonctions de la page Vue d’ensemble , vous devez disposer des fonctions de déclencheur HTTP que vous avez créées.
Sélectionnez Créer sous l’onglet Fonctions . Le volet Créer une fonction s’affiche.
Sous la section Sélectionner un modèle, sélectionnez Déclencheur HTTP, puis Suivant. Acceptez les valeurs par défaut sous l’onglet Détails du modèle, puis sélectionnez Créer. Le volet Vue d’ensemble de la fonction HttpTrigger3 apparaît.

Ajouter une liaison d’entrée Azure Cosmos DB

Nous allons ajouter une autre liaison d’entrée Azure Cosmos DB.

Dans le menu de fonction HttpTrigger3, sélectionnez Intégration. Le volet Intégration s’affiche.
Dans la zone Déclencheur et entrées, sélectionnez Ajouter une entrée. Le volet Créer une entrée s’affiche.
Dans la liste déroulante Type de liaison, sélectionnez Azure Cosmos DB.
Le paramètre Connexion de compte Cosmos DB doit être déjà renseigné avec la connexion que vous avez créée dans l’exercice précédent.

Si votre connexion ne figure pas dans la liste, suivez ces étapes pour en créer une.
1. Dans la section Détails Azure Cosmos DB, sous le paramètre Connexion de compte Cosmos DB, sélectionnez le lien Nouveau.
2. Quand la boîte de dialogue Nouvelle connexion Cosmos DB s’affiche, sélectionnez OK pour créer la connexion. Une nouvelle connexion au compte Cosmos DB est créée.

Entrez les valeurs suivantes pour les autres paramètres de ce volet. À tout moment, pour en savoir plus sur la fonction d’un paramètre, vous pouvez sélectionner l’icône d’information à sa droite.

Paramètre	valeur	Description
Nom du paramètre de document	`bookmark`	Nom utilisé pour identifier cette liaison dans votre code.
Nom de la base de données	`func-io-learn-db`	Base de données à utiliser. Cette valeur est le nom de base de données que nous avons défini précédemment dans cette leçon.
Nom de la collection	`Bookmarks`	Nom de la collection à partir de laquelle les données sont lues. Nous avons défini ce paramètre plus tôt dans la leçon.
ID du document	`{id}`	Ajoutez `{id}` pour utiliser l’expression de liaison appropriée et acceptez le paramètre qui est transmis dans la chaîne de requête.
Clé de partition	`{id}`	Ajoutez encore `{id}` pour utiliser l’expression de liaison appropriée et acceptez le paramètre qui est transmis dans la chaîne de requête.
Requête SQL (facultative)	Laisser vide	Nous ne récupérons qu’un seul élément à la fois d’après l’ID. Par conséquent, il vaut mieux filtrer en fonction du paramètre Document qu’utiliser une requête SQL dans cette instance. Nous pourrions concevoir une requête SQL pour retourner une seule entrée (`SELECT * from b where b.ID = /id`). Cette requête retourne en effet un élément, mais elle le retourne dans une collection d’éléments. Notre code aurait à manipuler une collection inutilement. Adoptez l’approche avec requête SQL quand vous souhaitez obtenir plusieurs documents.

À l’instar de la liaison d’entrée que nous avons créée au cours de l’exercice précédent, nous souhaitons rechercher un signet avec un ID spécifique. Nous avons donc lié l’ID de document que notre fonction reçoit dans la chaîne de requête à la liaison, appelée expression de liaison. Le déclencheur de la fonction est une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID à rechercher. La liaison retourne 0 document (introuvable) ou 1 document (trouvé).

Sélectionnez Ajouter pour enregistrer la configuration de liaison d’entrée.

Nous avons maintenant une liaison d’entrée Azure Cosmos DB. Nous allons ajouter une liaison de sortie pour écrire de nouvelles entrées dans notre collection.

Ajouter une liaison de sortie Azure Cosmos DB

Dans le volet Intégration pour HttpTrigger3, dans la zone Sorties, sélectionnez Ajouter une sortie. Le volet Créer une sortie s’affiche.
Sous Type de liaison, sélectionnez dans la liste déroulante Azure Cosmos DB.
Le paramètre Connexion au compte Cosmos DB doit être déjà renseigné avec la connexion que vous avez créée précédemment. Si ce n’est pas le cas, développez la liste déroulante et sélectionnez la connexion que vous avez définie pour la liaison d’entrée HttpTrigger3.

Entrez les valeurs suivantes pour les paramètres restants de la liaison de sortie.

Paramètre	valeur	Description
Nom du paramètre de document	`newbookmark`	Nom utilisé pour identifier cette liaison dans votre code. Ce paramètre est utilisé pour écrire une nouvelle entrée de signet.
Nom de la base de données	`func-io-learn-db`	Base de données à utiliser. Cette valeur est le nom de base de données que nous avons défini précédemment dans cette leçon.
Nom de la collection	`Bookmarks`	Nom de la collection à partir de laquelle les données sont lues. Cette valeur est le nom du conteneur que nous avons défini plus tôt dans la leçon.
Clé de partition	`/id`	Ajoutez la clé de partition que nous avons définie lors de la création du conteneur Azure Cosmos DB Bookmarks. La clé entrée ici (spécifiée dans `<key>` de la configuration de liaison d’entrée) doit correspondre à celle du conteneur.

Sélectionnez Ajouter pour enregistrer cette configuration de liaison de sortie.

Nous disposons à présent d’une liaison pour lire les données de notre collection, et d’une liaison pour y écrire des données.

Ajouter une liaison de sortie Stockage File d’attente Azure

Stockage File d’attente Azure est un service permettant de stocker des messages accessibles à partir de n’importe où dans le monde. La taille d’un message peut atteindre 64 Ko et une file d’attente peut contenir des millions de messages, jusqu’à la capacité totale du compte de stockage dans lequel elle est définie. Le diagramme suivant montre de façon détaillée comment une file d’attente est utilisée dans notre scénario.

Illustration montrant une file d’attente de stockage avec une fonction qui envoie (push) et une autre fonction qui récupère des messages

Dans cet exemple, vous voyez qu’une fonction nommée add-bookmark ajoute des messages à une file d’attente et qu’une autre nommée gen-qr-code récupère les messages de la même file d’attente et traite la requête. Comme nous écrivons des messages ou que nous les envoyons (push) dans la file d’attente à partir de add-bookmark, nous ajoutons une nouvelle liaison de sortie à la solution.

Nous allons créer la liaison via le portail.

Dans le volet Intégration de votre fonction, dans la zone Sorties, sélectionnez Ajouter une sortie. Le volet Créer une sortie s’affiche.
Dans la liste déroulante Type de liaison, sélectionnez Stockage File d’attente Azure.

Si un message s’affiche et vous demande d’installer l’extension Microsoft.Azure.WebJobs.Extensions.Storage, sélectionnez Installer et attendez que l’installation se termine.

Ensuite, nous configurons une connexion de compte de stockage, où la file d’attente est hébergée.

Sous Connexion du compte de stockage, sélectionnez Nouveau. La boîte de dialogue Nouvelle connexion du compte de stockage s’affiche.
Au début de ce module, lorsque vous avez créé votre application de fonction, un compte de stockage a également été créé pour vous. Sélectionnez-le dans la liste déroulante, puis sélectionnez OK.

Le paramètre Connexion du compte de stockage est renseigné avec le nom d’une connexion.

Bien que nous puissions conserver les valeurs par défaut, nous allons modifier certains paramètres pour donner plus de sens aux propriétés restantes.

Complétez les paramètres dans le volet Créer une sortie en remplaçant les anciennes valeurs suivantes par les nouvelles valeurs :

Paramètre	Ancienne valeur	Nouvelle valeur	Description
Nom de message de paramètre	outputQueueItem	newmessage	Propriété de liaison que nous utilisons dans le code.
Nom de la file d’attente	outqueue	bookmarks-post-process	Nom de la file d’attente où nous plaçons les signets afin qu’une autre fonction puisse les traiter ultérieurement.

Sélectionnez Ajouter pour enregistrer votre configuration de sortie du Stockage File d’attente Azure.

Mettre à jour l’implémentation de la fonction

Nous avons maintenant configuré toutes nos liaisons. Il est temps de les utiliser dans notre fonction.

Pour ouvrir le fichier index.js dans l’éditeur de code, sélectionnez votre fonction, HttpTrigger3.
Dans le menu, sélectionnez Code + test. Le volet Code + Test s’affiche pour votre fonction.

Remplacez tout le code inclus dans le fichier index.js par le code de l’extrait suivant, puis, dans la barre de commandes, sélectionnez Enregistrer.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Examinons en détail ce que fait ce code :

Comme cette fonction change nos données, nous nous attendons à ce que la requête HTTP soit un POST et à ce que les données du signet fassent partie du corps de la requête.
Notre liaison d’entrée Azure Cosmos DB tente de récupérer un document, ou un signet, en utilisant l’id que nous recevons. Si elle trouve une entrée, l’objet bookmark est défini. La condition if(bookmark) vérifie si une entrée a été trouvée.
Pour effectuer l’ajout à la base de données, il suffit de définir le paramètre de liaison context.bindings.newbookmark sur la nouvelle entrée de signet, que nous avons créée sous forme de chaîne JSON.
Pour poster un message sur notre file d’attente, il suffit de définir le paramètre context.bindings.newmessage.

Notes

La seule tâche que vous avez effectuée a été de créer une liaison de file d’attente. Vous n’avez jamais créé la file d’attente explicitement. Vous pouvez constater toute la puissance des liaisons ! Comme le déclare la notification suivante, la file d’attente est créée automatiquement pour vous si elle n’existe pas.

Capture d’écran montrant un message indiquant que la file d’attente sera créée automatiquement. .

Sélectionnez function.json dans la liste déroulante de votre chemin <functionapp> \ HttpTrigger3 \ et faites les changements suivants :
1. Changez toutes les instances "collectionName" en "containerName".
2. Changez toutes les instances "connectionStringSetting" en "connection".
3. Supprimez les références à "methods": [].

Votre fichier function.json final doit ressembler à ce code.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}"
    },
    {
      "name": "newbookmark",
      "direction": "out",
      "type": "cosmosDB",
      "partitionKey": "/id",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB"
    },
    {
      "name": "newmessage",
      "direction": "out",
      "type": "queue",
      "queueName": "bookmarks-post-process",
      "connection": "your-storage-account_STORAGE"
    }
  ]
}

Dans la barre de commandes, sélectionnez Enregistrer.

Et voilà ! Maintenant, nous allons voir notre travail en action dans la section suivante.

Pour ouvrir le fichier run.ps1 dans l’éditeur de code, sélectionnez votre fonction HttpTrigger3 dans la barre de navigation en haut du volet.
Dans le menu Fonction, sous Développeur, sélectionnez Coder + tester. Le volet Coder + tester de votre fonction HttpTrigger3 apparaît, affichant le contenu par défaut de run.ps1.

Remplacez le contenu de ce fichier par le code suivant.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

Dans la barre de commandes, sélectionnez Enregistrer. Une connexion est établie et une session de fichier journal s’ouvre.

Examinons en détail ce que fait ce code :

Comme cette fonction change nos données, nous nous attendons à ce que la requête HTTP soit un POST et à ce que les données du signet fassent partie du corps de la requête.
Notre liaison d’entrée Azure Cosmos DB tente de récupérer un document, ou un signet, en utilisant l’id dans la requête. Si elle trouve une entrée, l’objet bookmark est défini. La condition if ($bookmark) vérifie si une entrée a été trouvée.
Ajouter à la base de données est aussi simple qu’appeler Push-OutputBinding avec le nom de la liaison de sortie Cosmos DB (newbookmark) et la valeur de l’objet $newBookmark.
Publier un message dans notre file d’attente est aussi simple qu’appeler Push-OutputBinding avec le nom de la liaison de sortie de la file d’attente (newmessage) et la valeur de l’objet $newBookmark.

Notes

Capture d’écran montrant une info-bulle de l’interface utilisateur indiquant que la file d’attente sera créée automatiquement

Et voilà ! Maintenant, nous allons voir notre travail en action dans la section suivante.

Faire un essai

Maintenant que nous avons plusieurs liaisons de sortie, nos tests deviennent un peu plus compliqués. Dans les unités précédentes, nous nous étions contentés de tester en envoyant une requête HTTP et une chaîne de requête, mais cette fois, nous effectuons une requête HTTP POST. Nous devons également vérifier si les messages atteignent la file d’attente.

Dans la barre de commandes du volet Coder + tester de votre fonction HttpTrigger3, sélectionnez Tester/exécuter. Un nouveau volet s’affiche, avec l’onglet Entrée ouvert, comme illustré dans l’image suivante :
Dans la liste déroulante méthode HTTP, vérifiez que l’option POST est sélectionnée.
Remplacez le contenu du corps de la requête par l’objet JSON suivant :
```
{
    "id": "docs",
    "url": "https://zcusa.951200.xyz/azure"
}
```
Sélectionnez Exécuter.
La progression de la programmation apparaît dans le volet Journaux. Dès que vous avez terminé, vérifiez que l’onglet Sortie affiche « Le signet existe déjà. » dans le paramètre Contenu de la réponse HTTP.

Vous avez ajouté l’élément de signet dans Exercice - Lire des données avec des liaisons d’entrée. La réponse confirme que votre JavaScript var bookmark = context.bindings.bookmark fonctionne correctement et que votre code PowerShell fait la même connexion.
Nous allons poster un deuxième signet vers la base de données. Sélectionnez l’onglet Entrée.
Remplacez le contenu du corps de la requête par l’objet JSON suivant :
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Sélectionnez Exécuter.
Vérifiez que l’onglet Sortie affiche « Signet ajouté ! » dans Contenu de la réponse HTTP, comme indiqué dans la capture d’écran suivante.

Félicitations ! Votre fonction fonctionne comme prévu ! Mais qu’en est-il de l’opération de file d’attente que nous avons ajoutée au code ? Allons voir si quelque chose a été écrit dans une file d’attente.

Vérifier qu’un message est écrit dans la file d’attente

Les files d’attente Stockage File d’attente Azure sont hébergées dans un compte de stockage. Vous avez configuré le compte de stockage lors de la création de la liaison de sortie.

Dans la barre de recherche globale du portail Azure, entrez les comptes de stockage, puis, dans la liste des résultats, sélectionnez Comptes de stockage. Le volet Comptes de stockage s’affiche.
Sélectionnez le compte de stockage que vous avez utilisé pour configurer la liaison de sortie newmessage.
Dans le menu Compte de stockage, sous Stockage de données, sélectionnez Files d’attente pour lister les files d’attente hébergées par ce compte de stockage. Vérifiez que la file d’attente bookmarks-post-process figure dans la liste, comme illustré dans la capture d’écran suivante.
Sélectionnez bookmarks-post-process pour dresser la liste des messages figurant dans la file d’attente. Si s’est passé comme prévu, la file d’attente inclut le message que vous avez envoyé lors de l’ajout d’un signet à la base de données. Elle doit se présenter comme suit.

Dans cet exemple, le message a reçu un ID unique, et la colonne Texte du message affiche votre signet au format JSON. Il n’y a aucun message pour le signet docs Azure que vous avez essayé d’ajouter, car il existe déjà dans la base de données.
Vous pouvez tester davantage la fonction en changeant le corps de la requête dans le volet de test avec de nouveaux ensembles ID/URL et en exécutant la fonction. Observez cette file d’attente pour voir plus de messages arriver. Vous pouvez également consulter la base de données pour vérifier que les nouvelles entrées ont été ajoutées.

Dans cet exercice, nous avons étendu notre connaissance des liaisons aux liaisons de sortie et de l’écriture de données à votre base de données Azure Cosmos DB. Nous avons ajouté une liaison de sortie pour publier des messages dans une file d’attente Azure. Cet exemple illustre la véritable puissance des liaisons qui vous permettent de modeler et de déplacer des données de sources entrantes vers diverses destinations. Nous n’avons eu à écrire aucun code de base de données et n’avons eu aucune chaîne de connexion à gérer nous-mêmes. Au lieu de cela, nous avons configuré des liaisons de façon déclarative et nous avons laissé la plateforme s’occuper de la sécurisation des connexions, de la mise à l’échelle de notre fonction et de la mise à l’échelle de nos connexions.