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

Article
08/15/2024

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

Compte Azure avec un abonnement actif. Créez-en un gratuitement. Vous pouvez également essayez Azure Cosmos DB gratuitement sans abonnement Azure. Vous pouvez aussi utiliser l’émulateur Azure Cosmos DB avec la chaîne de connexion .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Go installé sur votre ordinateur et une expérience de travail avec Go.
Git.

Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
- Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
- Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
- Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Clonage de l’exemple d’application

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

Ouvrez une invite de commandes, créez un nouveau dossier nommé git-samples, puis fermez l’invite de commandes.
```
mkdir "C:\git-samples"
```
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"
```
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

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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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>

<COSMOSDB_ACCOUNT_NAME>: nom du compte Azure Cosmos DB que vous avez créé
<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 :

Depuis la barre de recherche du portail Azure, recherchez et sélectionnez Groupes de ressources.
Dans la liste, sélectionnez le groupe de ressources créé pour ce guide de démarrage rapide.
Dans la page Vue d’ensemble du groupe de ressources, sélectionnez Supprimer un groupe de ressources.
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é.

Si vous ne connaissez que le nombre de vCores et de serveurs présents dans votre cluster de bases de données existant, lisez Estimation des unités de requête à l’aide de vCores ou de processeurs virtuels
Si vous connaissez les taux de requêtes typiques de votre charge de travail de base de données actuelle, lisez la section concernant l’estimation des unités de requête à l’aide du planificateur de capacité Azure Cosmos DB

Importer des données MongoDB dans Azure Cosmos DB

Partager via

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

Prérequis

Clonage de l’exemple d’application

Vérifier le code

Connecter l’application Go à Azure Cosmos DB

Créer un élément `todo`

Répertorier les éléments `todo`

Mettre à jour un élément `todo`

Supprimer un élément `todo`

Créer l’application

Configurer Azure Cosmos DB

Ajouter le module Azure Cosmos DB

Créer un groupe de ressources

Création d’un compte Azure Cosmos DB

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

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.

Exécution de l'application

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

Nettoyer les ressources

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

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

Prérequis

Clonage de l’exemple d’application

Vérifier le code

Connecter l’application Go à Azure Cosmos DB

Créer un élément todo

Répertorier les éléments todo

Mettre à jour un élément todo

Supprimer un élément todo

Créer l’application

Configurer Azure Cosmos DB

Connexion à Azure

Ajouter le module Azure Cosmos DB

Créer un groupe de ressources

Création d’un compte Azure Cosmos DB

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

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.

Exécution de l'application

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

Nettoyer les ressources

Étapes suivantes

Commentaires

Ressources supplémentaires

Créer un élément `todo`

Répertorier les éléments `todo`

Mettre à jour un élément `todo`

Supprimer un élément `todo`