Démarrage rapide : connecter une application Go à Azure Cosmos DB for MongoDB

  • Article

S’APPLIQUE À : MongoDB

Azure Cosmos DB est un service de base de données multimodèle qui vous permet de créer et d’interroger rapidement des bases de données de documents, de tables, de paires clé/valeur et de graphes avec des capacités de distribution mondiale et de mise à l’échelle horizontale. Dans ce guide de démarrage rapide, vous créez et gérez un compte Azure Cosmos DB en utilisant Azure Cloud Shell, vous clonez un exemple d’application modèle GitHub existant, puis vous le configurez pour qu'il fonctionne avec Azure Cosmos DB.

L’exemple d’application est un outil de gestion todo avec ligne de commande écrit en Go. L’API Azure Cosmos DB pour MongoDB est compatible avec le protocole filaire MongoDB, permettant à n’importe quel pilote client MongoDB de s’y connecter. Comme cette application utilise le pilote Go pour MongoDB, elle sait que les données sont stockées dans une base de données Azure Cosmos DB.

Prérequis

Clonage de l’exemple d’application

Exécutez les commandes suivantes pour cloner l’exemple de référentiel.

  1. Ouvrez une invite de commandes, créez un nouveau dossier nommé git-samples, puis fermez l’invite de commandes.

    mkdir "C:\git-samples"

  2. Ouvrez une fenêtre de terminal git comme Git Bash et utilisez la commande cd pour accéder au nouveau dossier d’installation pour l’exemple d’application.

    cd "C:\git-samples"

  3. Exécutez la commande suivante pour cloner l’exemple de référentiel : Cette commande crée une copie de l’exemple d’application sur votre ordinateur.

    git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart

Vérifier le code

Cette étape est facultative. Pour savoir comment l’application fonctionne, vous pouvez examiner les extraits de code suivants. Sinon, vous pouvez directement passer à la section Exécution de l’application. La disposition de l’application est la suivante :

.
├── go.mod
├── go.sum
└── todo.go

Tous les extraits suivants proviennent du fichier todo.go.

Connecter l’application Go à Azure Cosmos DB

clientOptions encapsule la chaîne de connexion pour Azure Cosmos DB, qui est transmise à l’aide d’une variable d’environnement (voir la section suivante pour plus détails). La connexion est initialisée à l’aide de l’élément mongo.NewClient vers lequel l’instance clientOptions est passée. LaPing fonction est appelée pour confirmer la réussite de la connectivité (il s'agit d'une stratégie de type Fail-fast).

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
    defer cancel()

    clientOptions := options.Client().ApplyURI(mongoDBConnectionString).SetDirect(true)
    
    c, err := mongo.Connect(ctx, clientOptions)
    if err != nil {
        log.Fatalf("unable to initialize connection %v", err)
    }

    err = c.Ping(ctx, nil)
    if err != nil {
        log.Fatalf("unable to connect %v", err)
    }

Remarque

L’utilisation de la configuration SetDirect(true) est importante car sans elle vous obtenez l’erreur de connectivité suivante : unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Créer un élément todo

Pour créer un élément todo, nous obtenons un handle vers un élément mongo.Collection et appelons la fonction InsertOne.

func create(desc string) {
    c := connect()
    ctx := context.Background()
    defer c.Disconnect(ctx)

    todoCollection := c.Database(database).Collection(collection)
    r, err := todoCollection.InsertOne(ctx, Todo{Description: desc, Status: statusPending})
    if err != nil {
        log.Fatalf("failed to add todo %v", err)
    }

Nous transmettons un struct Todo qui contient la description et l'état( initialement fixé à pending) :

type Todo struct {
    ID          primitive.ObjectID `bson:"_id,omitempty"`
    Description string             `bson:"description"`
    Status      string             `bson:"status"`
}

Répertorier les éléments todo

Nous pouvons répertorier les éléments TODO selon des critères. Un bson.D est créé pour encapsuler les critères de filtrage :

func list(status string) {
    .....
    var filter interface{}
    switch status {
    case listAllCriteria:
        filter = bson.D{}
    case statusCompleted:
        filter = bson.D{{statusAttribute, statusCompleted}}
    case statusPending:
        filter = bson.D{{statusAttribute, statusPending}}
    default:
        log.Fatal("invalid criteria for listing todo(s)")
    }

Find permet de rechercher des documents en fonction du filtre, et le résultat est converti en une tranche de Todo

    todoCollection := c.Database(database).Collection(collection)
    rs, err := todoCollection.Find(ctx, filter)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }
    var todos []Todo
    err = rs.All(ctx, &todos)
    if err != nil {
        log.Fatalf("failed to list todo(s) %v", err)
    }

Enfin, les informations sont affichées sous forme de tableau :

    todoTable := [][]string{}

    for _, todo := range todos {
        s, _ := todo.ID.MarshalJSON()
        todoTable = append(todoTable, []string{string(s), todo.Description, todo.Status})
    }

    table := tablewriter.NewWriter(os.Stdout)
    table.SetHeader([]string{"ID", "Description", "Status"})

    for _, v := range todoTable {
        table.Append(v)
    }
    table.Render()

Mettre à jour un élément todo

Un élément todo peut être mis à jour en fonction de sa valeur _id. Un filtre bson.D est créé en fonction de l’élément _id, et un autre filtre est créé pour les informations mises à jour, soit un nouvel état (completed ou pending) dans ce cas. Enfin, la fonction UpdateOne est appelée avec le filtre et le document mis à jour :

func update(todoid, newStatus string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }
    filter := bson.D{{"_id", oid}}
    update := bson.D{{"$set", bson.D{{statusAttribute, newStatus}}}}
    _, err = todoCollection.UpdateOne(ctx, filter, update)
    if err != nil {
        log.Fatalf("failed to update todo %v", err)
    }

Supprimer un élément todo

Un élément todo est supprimé en fonction de sa valeur _id, puis il est encapsulé sous la forme d'une instance bson.D. DeleteOne est appelé pour supprimer le document.

func delete(todoid string) {
....
    todoCollection := c.Database(database).Collection(collection)
    oid, err := primitive.ObjectIDFromHex(todoid)
    if err != nil {
        log.Fatalf("invalid todo ID %v", err)
    }
    filter := bson.D{{"_id", oid}}
    _, err = todoCollection.DeleteOne(ctx, filter)
    if err != nil {
        log.Fatalf("failed to delete todo %v", err)
    }
}

Créer l’application

Accédez au répertoire dans lequel vous avez cloné l’application, puis générez l’application (en utilisant go build).

cd monogdb-go-quickstart
go build -o todo

Pour confirmer que l’application a été correctement générée.

./todo --help

Configurer Azure Cosmos DB

Connexion à Azure

Si vous choisissez d'installer et d'utiliser l'interface CLI localement, cette rubrique exige que vous utilisiez la version 2.0 ou ultérieure de l'interface Azure CLI. Exécutez az --version pour trouver la version. Si vous devez effectuer une installation ou une mise à niveau, consultez [Installer Azure CLI].

Si vous utilisez une interface Azure CLI installée, connectez-vous à votre abonnement Azure avec la commande az login et suivez les instructions à l'écran. Vous pouvez ignorer cette étape si vous utilisez Azure Cloud Shell.

az login

Ajouter le module Azure Cosmos DB

Si vous utilisez une interface Azure CLI installée, vérifiez si le composant cosmosdb est déjà installé en exécutant la commande az. Si cosmosdb figure dans la liste des commandes de base, passez à la commande suivante. Vous pouvez ignorer cette étape si vous utilisez Azure Cloud Shell.

Si cosmosdb n'est pas dans la liste des commandes de base, réinstallez Azure CLI.

Créer un groupe de ressources

Créez un groupe de ressources avec la commande az group create. Un groupe de ressources Azure est un conteneur logique dans lequel les ressources Azure comme les applications web, les bases de données et les comptes de stockage sont déployées et gérées.

L’exemple suivant crée un groupe de ressources dans la région Europe Ouest. Choisissez un nom unique pour le groupe de ressources.

Si vous utilisez Azure Cloud Shell, sélectionnez Essayer. Ensuite, suivez les invites à l'écran pour vous connecter, puis copiez la commande dans l'invite de commande.

az group create --name myResourceGroup --location "West Europe"

Création d’un compte Azure Cosmos DB

Créez un compte Azure Cosmos DB à l’aide de la commande az cosmosdb create.

Dans la commande suivante, indiquez le nom unique de votre compte Azure Cosmos DB là où se trouve l’espace réservé <cosmosdb-name>. Ce nom unique sera utilisé en tant que point de terminaison Azure Cosmos DB (https://<cosmosdb-name>.documents.azure.com/). Pour cette raison, le nom doit être unique sur l’ensemble des comptes Azure Cosmos DB dans Azure.

az cosmosdb create --name <cosmosdb-name> --resource-group myResourceGroup --kind MongoDB

Le paramètre --kind MongoDB prend en charge les connexions clientes MongoDB.

Une fois le compte Azure Cosmos DB créé, Azure CLI affiche des informations similaires à celles de l’exemple suivant.

Notes

Cet exemple utilise JSON comme format de sortie de l’interface de ligne de commande Azure, qui constitue le format par défaut. Pour utiliser un autre format de sortie, consultez Formats de sortie pour les commandes Azure CLI.

{
  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>.documents.azure.com:443/",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Document
DB/databaseAccounts/<cosmosdb-name>",
  "kind": "MongoDB",
  "location": "West Europe",
  "name": "<cosmosdb-name>",
  "readLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ],
  "resourceGroup": "myResourceGroup",
  "type": "Microsoft.DocumentDB/databaseAccounts",
  "writeLocations": [
    {
      "documentEndpoint": "https://<cosmosdb-name>-westeurope.documents.azure.com:443/",
      "failoverPriority": 0,
      "id": "<cosmosdb-name>-westeurope",
      "locationName": "West Europe",
      "provisioningState": "Succeeded"
    }
  ]
}

Récupérer la clé de la base de données

Pour se connecter à une base de données Azure Cosmos DB, vous avez besoin de la clé de la base de données. Utilisez la commande az cosmosdb keys list pour récupérer la clé primaire.

az cosmosdb keys list --name <cosmosdb-name> --resource-group myResourceGroup --query "primaryMasterKey"

Azure CLI génère des informations semblables à ce qui suit.

"RUayjYjixJDWG5xTqIiXjC..."

Configuration de l'application

Exportez la chaîne de connexion, la base de données MongoDB et les noms de collections en tant que variables d’environnement.

export MONGODB_CONNECTION_STRING="mongodb://<COSMOSDB_ACCOUNT_NAME>:<COSMOSDB_PASSWORD>@<COSMOSDB_ACCOUNT_NAME>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@<COSMOSDB_ACCOUNT_NAME>@"

Remarque

L’option ssl=true est importante, en raison des exigences d’Azure Cosmos DB. Pour plus d’informations, consultez Exigences relatives à la chaîne de connexion.

Pour la variable d’environnement MONGODB_CONNECTION_STRING, remplacez les espaces réservés pour <COSMOSDB_ACCOUNT_NAME> et <COSMOSDB_PASSWORD>

  1. <COSMOSDB_ACCOUNT_NAME>: nom du compte Azure Cosmos DB que vous avez créé
  2. <COSMOSDB_PASSWORD>: clé de base de données extraite à l’étape précédente
export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Vous pouvez choisir vos valeurs préférées pour MONGODB_DATABASE et MONGODB_COLLECTION ou les conserver en l’état.

Exécution de l'application

Pour créer un élément todo

./todo --create "Create an Azure Cosmos DB database account"

En cas de réussite, vous devriez voir une sortie avec l’élément MongoDB _id du document nouvellement créé :

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Créer un autre élément todo

./todo --create "Get the MongoDB connection string using the Azure CLI"

Répertorier tous les éléments todo

./todo --list all

Vous devriez voir les éléments que vous venez d'ajouter dans un format tabulaire suivant :

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | pending   |
|                            | database account               |           |
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

Pour mettre à jour l'état d'un todo (par exemple, le faire passer à l'état completed), utiliser l'ID todo :

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Répertorier uniquement les éléments todoterminés

./todo --list completed

Vous devriez voir l'élément que vous venez de mettre à jour :

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6b1bcd2fa6bd267d4c4" | Create an Azure Cosmos DB      | completed |
|                            | database account               |           |
+----------------------------+--------------------------------+-----------+

Afficher les données dans l’Explorateur de données

Les données stockées dans Azure Cosmos DB peuvent être affichées et interrogées dans le portail Azure.

Pour afficher, interroger et manipuler les données utilisateur créées à l’étape précédente, connectez-vous au portail Azure dans votre navigateur web.

Dans la zone de recherche en haut de la page, entrez Azure Cosmos DB. Lorsque le panneau de votre compte Azure Cosmos DB s’ouvre, sélectionnez votre compte Azure Cosmos DB. Dans le volet de navigation gauche, sélectionnez Explorateur de données. Développez votre collection dans le volet Collections, pour pouvoir afficher les documents de la collection, interroger les données et même créer et exécuter des procédures stockées, des déclencheurs et des fonctions définies par l’utilisateur.

Explorateur de données montrant le document créé

Supprimer un todo à l'aide de son ID :

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Répertorier les éléments todo à confirmer :

./todo --list all

L'élément todo que vous venez de supprimer ne devrait pas apparaître :

+----------------------------+--------------------------------+-----------+
|             ID             |          DESCRIPTION           |  STATUS   |
+----------------------------+--------------------------------+-----------+
| "5e9fd6befd2f076d1f03bd8a" | Get the MongoDB connection     | pending   |
|                            | string using the Azure CLI     |           |
+----------------------------+--------------------------------+-----------+

Nettoyer les ressources

Quand vous en avez terminé avec votre application et votre compte Azure Cosmos DB, vous pouvez supprimer les ressources Azure que vous avez créées afin d’éviter des frais supplémentaires. Pour supprimer les ressources :

  1. Depuis la barre de recherche du portail Azure, recherchez et sélectionnez Groupes de ressources.

  2. Dans la liste, sélectionnez le groupe de ressources créé pour ce guide de démarrage rapide.

    Sélectionner le groupe de ressources à supprimer

  3. Dans la page Vue d’ensemble du groupe de ressources, sélectionnez Supprimer un groupe de ressources.

    Supprimer le groupe de ressources

  4. Dans la fenêtre suivante, entrez le nom du groupe de ressources à supprimer, puis sélectionnez Supprimer.

Étapes suivantes

Dans ce guide de démarrage rapide, vous avez appris à créer un compte d’API Azure Cosmos DB pour MongoDB à l’aide d’Azure Cloud Shell et à créer puis exécuter une application de ligne de commande Go pour gérer todo. Vous pouvez maintenant importer des données supplémentaires dans votre compte Azure Cosmos DB.

Vous tentez d’effectuer une planification de la capacité pour une migration vers Azure Cosmos DB ? Vous pouvez utiliser les informations sur votre cluster de bases de données existant pour la planification de la capacité.

Importer des données MongoDB dans Azure Cosmos DB