Exercice : Lire des données avec des liaisons d’entrée

20 minutes

Imaginez que vous voulez créer un service de recherche par signet. Au départ, votre service est en lecture seule. Si des utilisateurs veulent rechercher une entrée, ils envoient une demande avec l’ID de l’entrée, et la fonction retourne l’URL. L’organigramme suivant illustre le flux logique.

Quand un utilisateur envoie une demande avec du texte, la fonction de recherche de signets tente de trouver une entrée dans votre base de données qui contient un signet avec le texte en tant que clé ou ID. Le système retourne un résultat qui indique si vous avez trouvé l’entrée.

Quand la fonction Azure reçoit une demande avec un ID de signet, elle vérifie d’abord si la demande est valide. Si elle ne l’est pas, une réponse d’erreur est générée. Si la demande est valide, la fonction vérifie si l’ID de signet existe dans la base de données Azure Cosmos DB. Si elle n’existe pas, une réponse d’erreur est générée. Si l’ID de signet est trouvé, une réponse de réussite est générée.

Vous avez besoin de stocker les données quelque part. Dans l’organigramme précédent, le magasin de données est une instance Azure Cosmos DB. Toutefois, comment vous connectez-vous à une base de données à partir d’une fonction et comment lisez-vous les données ? Dans l’univers des fonctions, vous configurez pour cela une liaison d’entrée. La configuration d’une liaison d’entrée via le portail Azure est simple. Comme vous allez bientôt le voir, vous n’avez pas besoin d’écrire de code ni d’ouvrir une connexion de stockage. Le runtime et les liaisons Azure Functions se chargent de ces tâches pour vous.

Créer un compte Azure Cosmos DB

Notes

Cet exercice n’a pas vocation à être un tutoriel sur Azure Cosmos DB. Si vous voulez en savoir plus, consultez le parcours d’apprentissage complet sur Azure Cosmos DB à la fin de ce module.

Créer un compte de base de données

Un compte de base de données est un conteneur pour gérer une ou plusieurs bases de données. Avant de pouvoir créer une base de données, nous devons créer un compte de base de données.

Dans le menu des ressources du portail Azure ou dans la page d’accueil, sélectionnez Créer une ressource. Le volet Créer une ressource apparaît.
Dans le menu Créer une ressource, sélectionnez Bases de données, puis recherchez et sélectionnez Azure Cosmos DB. Le volet Quelle est l’API qui correspond le mieux à votre charge de travail ? s’affiche.
Dans l’option Azure Cosmos DB for NoSQL, sélectionnez Créer pour pouvoir créer un déclencheur Cosmos DB et des liaisons d’entrée/sortie. Le volet Créer un compte Azure Cosmos DB – Azure Cosmos DB for NoSQL s’affiche.

Sous l’onglet Informations de base, entrez les valeurs suivantes pour chaque paramètre.

Paramètre	valeur	Description
Détails du projet
Abonnement	Abonnement Concierge	L’abonnement Azure qui fonctionne avec les ressources dans le bac à sable.
Groupe de ressources	Dans la liste déroulante, sélectionnez [Nom du groupe de ressources de bac à sable]	Le groupe de ressources pour votre bac à sable.
Détails de l’instance
Account Name	`globally unique name`	Entrez un nom unique mais identifiable pour votre compte Azure Cosmos DB ; `documents.azure.com` est ajouté au nom que vous fournissez. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Emplacement	`region`	Sélectionnez la région la plus proche de vous.

Acceptez les valeurs par défaut pour les autres paramètres, puis sélectionnez Vérifier + créer pour valider votre entrée. Une notification Validation réussie s’affiche.
Sélectionnez Créer pour provisionner et déployer un compte de base de données.
Le déploiement peut prendre un certain temps. Attendez un message Déploiement réussi dans le hub de notification avant de continuer.
Sélectionnez Accéder à la ressource pour accéder au compte de base de données dans le portail. Le volet Démarrage rapide de votre compte Azure Cosmos DB s’affiche.

Nous ajoutons ensuite un conteneur, puis une base de données au compte Azure Cosmos DB.

Ajouter un conteneur

Dans une instance Azure Cosmos DB, un conteneur est utilisé pour stocker diverses entités générées par l’utilisateur, également appelées éléments. Nous créons un conteneur appelé Bookmarks.

Utilisons l’outil Explorateur de données pour créer une base de données et un conteneur.

Dans le menu de votre compte Azure Cosmos DB, sélectionnez Explorateur de données. Le volet Explorateur de données de votre compte Cosmos DB apparaît.
Sélectionnez la boîte Nouveau conteneur. Le volet Nouveau conteneur s’affiche. Vous devrez peut-être faire défiler la page pour le voir.

Entrez les valeurs suivantes pour chaque paramètre.

Paramètre	valeur	Description
ID de base de données	Sélectionnez Créer nouveau, puis entrez func-io-learn-db comme ID de base de données.	Les noms de base de données peuvent avoir entre 1 et 255 caractères, et ne peuvent pas contenir /, \, #, ? ni d’espace de fin. Nous utilisons func-io-learn-db dans ce module, mais vous pouvez entrer ce que vous voulez.
Nombre maximal de RU/s de base de données	4000	Acceptez le débit par défaut de 4 000 unités de requête par seconde (RU/s). Pour réduire la latence, vous pouvez effectuer un scale-up des performances plus tard.
ID de conteneur	Signets	Les ID de conteneur sont soumis aux mêmes exigences de caractères que les noms de base de données. Nous utilisons des signets dans ce module.
Clé de partition	/id	La clé de partition spécifie la façon dont les documents des collections Azure Cosmos DB sont répartis entre les partitions de données logiques. Nous allons utiliser le paramètre Clé de partition par souci pratique, car nous ne nous préoccupons pas des performances de la base de données dans ce module. Pour en savoir plus sur les stratégies de clé de partition Azure Cosmos DB, explorez les modules Azure Cosmos DB de Microsoft Learn.

Acceptez les valeurs par défaut pour tous les autres paramètres.

Faites défiler l’affichage jusqu’au bas du volet et sélectionnez OK. Patientez quelques minutes pour que la base de données et le conteneur soient générés.

Une fois terminé, l’Explorateur de données affiche func-io-learn-db dans DATA sous API SQL.
Sélectionnez func-io-learn-db pour la développer. Notez que votre base de données func-io-learn-db contient plusieurs membres enfants, y compris Mise à l’échelle et Signets.
Développez le conteneur Bookmarks et notez qu’il est prérempli avec plusieurs membres enfants.

Dans la tâche suivante, vous ajoutez des données, également appelées éléments, à votre conteneur Bookmarks.

Ajouter des données de test

Vous voulez ajouter les données dans votre conteneur Signets. Utilisez l’Explorateur de données pour stocker une URL et un ID pour chaque élément.

Développez la base de données func-io-learn-db et le conteneur Signets, puis sélectionnez Éléments. L’onglet Éléments s’affiche.
Dans la barre de commandes, sélectionnez Nouvel élément.
Remplacez le code par défaut du nouvel élément par le code JSON suivant.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

Dans la barre de commandes, sélectionnez Enregistrer.

Notez qu’il apparaît plus de propriétés que les deux lignes que nous avons ajoutées. Elles commencent toutes par un trait de soulignement (_rid, _self, _etag, _attachments, _ts). Ces propriétés, décrites dans le tableau ci-dessous, sont générées par le système pour aider à gérer les éléments que vous ajoutez au conteneur.

Propriété	Description
`_rid`	L’ID de ressource est un identificateur unique qui est également hiérarchique relativement à la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation de la ressource élément.
`_self`	URI adressable unique de la ressource.
`_etag`	Nécessaire pour le contrôle de l’accès concurrentiel optimiste.
`_attachments`	Chemin adressable de la ressource des pièces jointes.
`_ts`	Timestamp de la dernière mise à jour de cette ressource.

Nous allons ajouter quelques éléments supplémentaires dans le conteneur Signets. Dans la barre de commandes, sélectionnez Nouvel élément. Créez quatre éléments de plus avec le contenu suivant. Ajoutez les éléments en sélectionnant Nouvel élément, puis sélectionnez Enregistrer après avoir copié et collé chaque nouvel élément. Notez comment chaque élément est ajouté à la liste des éléments.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
Une fois que vous avez terminé d’entrer les données du signet, votre conteneur doit ressembler à l’image suivante.

Votre conteneur Signets contient cinq éléments. Dans ce scénario, si une requête arrive avec « id=docs », elle recherche cet ID dans votre conteneur Bookmarks et retourne l’URL https://learn.microsoft.com/azure. Créons une fonction Azure qui recherche des valeurs dans votre conteneur Signets.

Créer votre fonction

Accédez à l’application de fonction que vous avez créée dans l’unité précédente. Dans le menu des ressources, sélectionnez Accueil et, dans la section Ressources récentes, vous devriez voir votre application de fonction (Type est égal à Application de fonction). Sélectionnez votre application de fonction. Le volet Application de fonction s’affiche.
Sous l’onglet Fonctions de la page Vue d’ensemble, vous devriez avoir une fonction, HttpTrigger1.
Créons une autre fonction. Sélectionnez Créer sous l’onglet Fonctions. Le volet Créer une fonction s’affiche, répertoriant les modèles des déclencheurs pris en charge.
Dans la section Sélectionner un modèle, sélectionnez Déclencheur HTTP.
Acceptez tous les paramètres par défaut et sélectionnez Créer pour créer votre fonction.

Le volet Vue d’ensemble de la fonction HttpTrigger2 s’affiche.

Vérifier la fonction

Vous pouvez vérifier ce que nous avons fait jusqu’à présent en testant la nouvelle fonction.

Dans la barre de commandes, sélectionnez Obtenir l’URL de la fonction. La boîte de dialogue Obtenir l’URL de la fonction s’affiche.
Sélectionnez Valeur par défaut (clé de fonction) dans la liste déroulante, puis sélectionnez l’icône Copier dans le Presse-papiers et sélectionnez OK.
Collez l’URL de la fonction que vous avez copiée dans la barre d’adresses d’un nouvel onglet de navigateur. Ajoutez la valeur de chaîne de requête &name=<your name> à la fin de l’URL, en remplaçant <your name> par votre nom, puis appuyez sur Entrée. La fonction Azure doit retourner une réponse personnalisée dans le navigateur.

Maintenant que notre fonction de base est opérationnelle, penchons-nous sur la lecture de données à partir de votre base de données Azure Cosmos DB ou, dans notre scénario, à partir de votre conteneur Signets.

Ajouter une liaison d’entrée Azure Cosmos DB

Pour lire des données dans la base de données, vous devez définir une liaison d’entrée. Comme vous le voyez ici, vous pouvez configurer une liaison capable de communiquer avec votre base de données en seulement quelques étapes.

Dans le portail Azure, dans le menu de fonction HttpTrigger2 à gauche, sélectionnez Intégration. Le volet d’intégration de votre fonction s’affiche.

Vous avez utilisé un modèle qui a créé une demande de déclencheur HTTP avec une liaison de sortie HTTP. Nous allons ajouter une liaison d’entrée Azure Cosmos DB.
Dans la zone 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.
Dans la section Détails Azure Cosmos DB, sous le paramètre Connexion de compte Cosmos DB, sélectionnez le lien Nouveau. La boîte de dialogue Nouvelle connexion Cosmos DB s’affiche.

Si un message s’affiche vous demandant d’installer l’extension Microsoft.Azure.WebJobs.Extensions.CosmosDB, sélectionnez Installer et attendez que l’installation se termine.
Par défaut, Azure reconnaît le compte Azure Cosmos DB que vous avez créé précédemment. Sélectionnez OK pour configurer une connexion à votre base de données. Une nouvelle connexion au compte de base de données est configurée et apparaît dans le champ Connexion au compte Cosmos DB.

Nous souhaitons rechercher un signet avec un ID spécifique et nous allons donc lier l’ID reçu dans la chaîne de requête à la liaison.

Renseignons les paramètres dans le volet Créer une entrée. Entrez les valeurs suivantes pour chaque paramètre. Pour en savoir plus sur l’objectif de chaque paramètre, sélectionnez l’icône d’information sur ce champ.

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 la base de données que nous définissons.
Nom de la collection	`Bookmarks`	Collection à partir de laquelle nous lisons les données. Ce paramètre a été défini.
ID du document	`id`	Ajoutez l’ID du document que nous avons défini lors de la création du conteneur Azure Cosmos DB Signets.
Clé de partition	`/id`	Ajoutez la clé de partition que vous avez définie lors de la création de la collection Azure Cosmos DB Signets. La clé entrée ici (spécifiée au format de liaison d’entrée `<key>`) doit correspondre à celle de la collection.
Requête SQL (facultative)	Laisser vide	Vous ne récupérez qu’un seul document à la fois d’après l’ID. Par conséquent, il vaut mieux filtrer en fonction du paramètre ID de document qu’utiliser une requête SQL dans cette instance. Vous pourriez concevoir une requête SQL pour retourner une seule entrée (`SELECT * from b where b.ID = id`). Cette requête retournerait en effet un document, mais elle le retournerait dans une collection de documents. Votre code aurait à manipuler une collection inutilement. Adoptez l’approche avec requête SQL quand vous souhaitez obtenir plusieurs documents.

La raison pour laquelle nous utilisons ces paramètres est que nous voulons rechercher un signet avec un ID spécifique. Nous avons donc lié l’ID de document que notre fonction a reçu dans la chaîne de requête à la liaison d’entrée. Cette syntaxe est appelée expression de liaison. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID à rechercher. Les ID étant uniques dans notre collection, la liaison retourne soit 0 document (introuvable), soit 1 document (trouvé).

Pour enregistrer cette configuration de liaison d’entrée, sélectionnez OK.

Mettre à jour l’implémentation de la fonction

Maintenant que votre liaison est définie, vous pouvez l’utiliser dans votre fonction. Vous devez apporter deux modifications pour implémenter la liaison que vous avez créée :

Modifiez le code d’implémentation spécifique au langage de votre fonction. Il doit déterminer si un document a été trouvé dans la base de données qui correspond à l’ID transmis à la fonction.
Modifiez le code d’implémentation JSON de votre fonction pour accepter un paramètre transmis dans la chaîne de requête.

Modifier le code d’implémentation JavaScript de votre fonction

Dans le menu Fonction de votre fonction HttpTrigger2, sélectionnez Coder + tester. Le volet Code + test s’affiche pour votre fonction HttpTrigger2.

Remplacez tout le code dans le fichier index.js par le code suivant.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

Dans la barre de commandes, sélectionnez Enregistrer. Sélectionnez Journaux du système de fichiers dans la liste déroulante en haut au centre du volet Journaux (qui affiche les journaux App Insights par défaut). Le volet Journaux apparaît, indiquant que vous avez Connected!.

Examinons ce que fait ce code.

Une requête HTTP entrante déclenche la fonction et un paramètre de requête id est passé à la liaison d’entrée Azure Cosmos DB.
Si la base de données trouve un document correspondant à cet ID, le paramètre bookmark est défini sur le document trouvé.

Dans cet exemple, le code construit une réponse qui contient la valeur d’URL trouvée dans le document correspondant de la base de données.
Si aucun document correspondant à cette clé n’est trouvé, la requête répond avec une charge utile et un code d’état qui annonce la mauvaise nouvelle à l’utilisateur.

Modifier le code d’implémentation JSON de votre fonction

Sélectionnez function.json dans la liste déroulante de votre chemin <functionapp> \ HttpTrigger2 \.

Modifiez les valeurs pour id et partitionKey afin qu’elles acceptent un paramètre {id}. Votre code function.json doit ressembler à l’exemple suivant, où your-database est remplacé par le nom de votre base de données Cosmos DB.

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

Dans la barre de commandes, sélectionnez Enregistrer.

Modifier le code d’implémentation PowerShell de votre fonction

Dans le menu Fonction de votre fonction HttpTrigger2, sélectionnez Coder + tester. Le volet Coder + tester s’affiche pour votre fonction HttpTrigger2, affichant le fichier run.ps1.

Remplacez tout le code dans le fichier run.ps1 par le code suivant.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

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

Dans la barre de commandes, sélectionnez Enregistrer. Sélectionnez Journaux du système de fichiers dans la liste déroulante en haut au centre du volet Journaux (qui affiche les journaux App Insights par défaut). Le volet Journaux apparaît, indiquant que vous avez Connected!.

Examinons ce que fait ce code.

Une requête HTTP entrante déclenche la fonction et un paramètre de requête id est passé à la liaison d’entrée Azure Cosmos DB.
Si la base de données trouve un document correspondant à cet ID, le paramètre bookmark est défini sur le document trouvé.

Dans cet exemple, le code construit une réponse qui contient la valeur d’URL trouvée dans le document correspondant de la base de données.
Si aucun document correspondant à cette clé n’est trouvé, la requête répond avec une charge utile et un code d’état qui annonce la mauvaise nouvelle à l’utilisateur.

Modifier le code d’implémentation JSON de votre fonction

Sélectionnez function.json dans la liste déroulante de votre chemin <functionapp> \ HttpTrigger2 \.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

Dans la barre de commandes, sélectionnez Enregistrer.

Faire un essai

Vous devriez déjà être dans le volet Coder + tester pour votre fonction HttpTrigger2.
Dans la barre de commandes, sélectionnez Obtenir l’URL de la fonction. La boîte de dialogue Obtenir l’URL de la fonction s’affiche.
Dans la liste déroulante Clé, sélectionnez Valeur par défaut sous Clé de section, puis sélectionnez l’icône Copier dans le presse-papiers à la fin de l’URL.
Collez la clé de fonction que vous avez copiée dans la barre d’adresses d’un nouvel onglet de navigateur, puis ajoutez la valeur de chaîne de requête &id=docs à la fin de l’URL. L’URL obtenue doit ressembler à l’exemple suivant :

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Appuyez sur Entrée pour exécuter la requête. La réponse retournée par votre fonction doit être similaire à l’exemple suivant.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Remplacez &id=docs par &id=missing, appuyez sur Entrée et examinez la réponse. Nous avons défini cinq signets et créé une réponse d’erreur significative si le signet demandé n’existe pas.

Dans cette unité, vous avez créé manuellement votre première liaison d’entrée pour lire des données à partir d’une base de données Azure Cosmos DB. La quantité de code que vous avez écrite pour rechercher et lire des données dans la base de données a été minimale, et ce, grâce aux liaisons. Vous avez réalisé la plus grande partie du travail de configuration de la liaison de façon déclarative, et la plateforme s’est chargée du reste.

Dans l’unité suivante, vous allez ajouter des données à la collection de signets via une liaison de sortie Azure Cosmos DB.

Continuer

Créer un compte Azure Cosmos DB

Créer un compte de base de données

Ajouter un conteneur

Ajouter des données de test

Créer votre fonction

Vérifier la fonction

Ajouter une liaison d’entrée Azure Cosmos DB

Mettre à jour l’implémentation de la fonction

Modifier le code d’implémentation JavaScript de votre fonction

Modifier le code d’implémentation JSON de votre fonction

Modifier le code d’implémentation PowerShell de votre fonction

Modifier le code d’implémentation JSON de votre fonction

Faire un essai

Commentaires