Guida introduttiva: Connessione un'applicazione Go in Azure Cosmos DB per MongoDB

Articolo
04/19/2024

SI APPLICA A: MongoDB

Azure Cosmos DB è un servizio di database modello che consente di creare ed eseguire rapidamente query su database di documenti, tabelle, valori chiave e grafi, con funzionalità di scalabilità orizzontale e distribuzione globale. Questa guida introduttiva illustra come creare e gestire un account Azure Cosmos DB tramite Azure Cloud Shell e come clonare un'applicazione di esempio esistente da GitHub e configurarla per l'uso con Azure Cosmos DB.

L'applicazione di esempio è uno strumento di gestione todo basato su riga di comando scritto in Go. L'API Azure Cosmos DB per MongoDB è compatibile con il protocollo di collegamento MongoDB, rendendo possibile la connessione di qualsiasi driver client di MongoDB. Questa applicazione usa il driver Go per MongoDB in modo trasparente per l'applicazione di archiviazione dei dati in un database Azure Cosmos DB.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Crearne una gratuitamente. In alternativa, è possibile provare gratuitamente Azure Cosmos DB senza una sottoscrizione di Azure. È anche possibile usare l'Emulatore di Azure Cosmos DB con la stringa di connessione .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Go installato nel computer e conoscenza del funzionamento di Go.
Git.

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido di Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Clonare l'applicazione di esempio

Eseguire i comandi seguenti per clonare il repository di esempio.

Aprire un prompt dei comandi, creare una nuova cartella denominata git-samples e quindi chiudere il prompt dei comandi.
```
mkdir "C:\git-samples"
```
Aprire una finestra del terminale Git, ad esempio Git Bash, ed eseguire il comando cd per passare a una nuova cartella in cui installare l'app di esempio.
```
cd "C:\git-samples"
```
Eseguire il comando seguente per clonare l'archivio di esempio. Questo comando crea una copia dell'app di esempio nel computer in uso.
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

Esaminare il codice

Questo passaggio è facoltativo. Se si è interessati a comprendere il funzionamento dell'applicazione, è possibile esaminare i frammenti di codice seguenti. In caso contrario, passare direttamente a Eseguire l'applicazione. Il layout dell'applicazione è il seguente:

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

Tutti i frammenti di codice seguenti sono tratti dal file todo.go.

Connessione dell'app Go ad Azure Cosmos DB

clientOptions incapsula la stringa di connessione per Azure Cosmos DB, che viene passata tramite una variabile di ambiente (dettagli disponibili nella sezione successiva). La connessione viene inizializzata tramite mongo.NewClient a cui viene passata l'istanza di clientOptions. Ping la funzione viene richiamata per confermare la corretta connettività (si tratta di una strategia con errori rapidi).

    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)
    }

Nota

L'uso della configurazione SetDirect(true) è importante per non ricevere l'errore di connettività seguente: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Creare un elemento `todo`

Per creare un elemento todo, è necessario ottenere un punto di controllo per mongo.Collection e richiamare la funzione 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)
    }

Viene passato uno Todo struct che contiene la descrizione e lo stato (inizialmente impostato su pending):

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

Elencare elementi `todo`

È possibile elencare elementi TODO in base a criteri specifici. Viene bson.D creato un oggetto per incapsulare i criteri di filtro:

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 consente di cercare i documenti in base al filtro e il risultato viene convertito in una sezione di 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)
    }

Infine, il rendering delle informazioni viene eseguito in formato tabulare:

    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()

Aggiornare un elemento `todo`

Un elemento todo può essere aggiornato in base al relativo _id. Viene creato un filtro bson.D in base all'elemento _id e ne viene creato un altro per le informazioni aggiornate, che in questo caso rappresentano un nuovo stato (completed o pending). Infine, la UpdateOne funzione viene richiamata con il filtro e il documento aggiornato:

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)
    }

Eliminare un elemento `todo`

Un todo oggetto viene eliminato in base al relativo _id oggetto e viene incapsulato sotto forma di istanza di bson.D . La funzione DeleteOne viene richiamata per eliminare il documento.

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)
    }
}

Compilare l'applicazione

Passare alla directory in cui è stata clonata l'applicazione e compilarla (tramite go build).

cd monogdb-go-quickstart
go build -o todo

Per verificare che l'applicazione sia stata compilata correttamente.

./todo --help

Configurazione di Azure Cosmos DB

Se si sceglie di installare e usare l'interfaccia della riga di comando in locale, per questo argomento è necessario eseguire l'interfaccia della riga di comando di Azure versione 2.0 o successiva. Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere [Installare l'interfaccia della riga di comando di Azure].

Se si usa un'interfaccia della riga di comando di Azure installata, accedere alla sottoscrizione di Azure con il comando az login e seguire le istruzioni visualizzate. Se si usa Azure Cloud Shell, è possibile ignorare questo passaggio.

az login

Aggiungere il modulo Azure Cosmos DB

Se si usa un'interfaccia della riga di comando di Azure installata, verificare se il cosmosdb componente è già installato eseguendo il az comando . Se cosmosdb è nell'elenco di comandi di base, passare al comando successivo. Se si usa Azure Cloud Shell, è possibile ignorare questo passaggio.

Se cosmosdb non è presente nell'elenco dei comandi di base, reinstallare l'interfaccia della riga di comando di Azure.

Creare un gruppo di risorse

Creare un gruppo di risorse con il comando az group create. Un gruppo di risorse di Azure è un contenitore logico in cui vengono distribuite e gestite risorse di Azure come app Web, database e account di archiviazione.

L'esempio seguente crea un gruppo di risorse nell'area Europa occidentale. Scegliere un nome univoco per il gruppo di risorse.

Se si usa Azure Cloud Shell, selezionare Prova, seguire le istruzioni visualizzate per accedere, quindi copiare il comando nel prompt dei comandi.

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

Creare un account Azure Cosmos DB

Creare un account Azure Cosmos DB con il comando az cosmosdb create.

Nel comando seguente sostituire il segnaposto <cosmosdb-name> con il nome univoco dell'account Azure Cosmos DB. Questo nome univoco verrà usato come parte dell'endpoint di Azure Cosmos DB, https://<cosmosdb-name>.documents.azure.com/, pertanto deve essere univoco rispetto a tutti gli account Azure Cosmos DB presenti in Azure.

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

Il parametro --kind MongoDB consente le connessioni al client MongoDB.

Dopo la creazione dell'account Azure Cosmos DB, l'interfaccia della riga di comando di Azure mostra informazioni simili all'esempio seguente.

Nota

Questo esempio usa JSON come formato di output dell'interfaccia della riga di comando di Azure, ovvero l'impostazione predefinita. Per usare un altro formato di output, vedere Formati di output per i comandi dell'interfaccia della riga di comando di Azure.

{
  "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"
    }
  ]
}

Recuperare la chiave del database

Per connettersi a un database Azure Cosmos DB, è necessaria la chiave del database. Usare il comando az cosmosdb keys list per recuperare la chiave primaria.

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

L'interfaccia della riga di comando di Azure restituisce informazioni simili all'esempio seguente.

"RUayjYjixJDWG5xTqIiXjC..."

Configurazione dell'applicazione

Esportare i nomi di stringa di connessione, database MongoDB e raccolta come variabili di ambiente.

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>@"

Nota

L'opzione ssl=true è importante in considerazione dei requisiti di Azure Cosmos DB. Per altre informazioni, vedere Requisiti della stringa di connessione.

Per la variabile di ambiente MONGODB_CONNECTION_STRING, sostituire i segnaposto per <COSMOSDB_ACCOUNT_NAME> e <COSMOSDB_PASSWORD>

<COSMOSDB_ACCOUNT_NAME>: nome dell'account Azure Cosmos DB creato
<COSMOSDB_PASSWORD>: chiave di database estratta nel passaggio precedente

export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

È possibile scegliere i valori desiderati per MONGODB_DATABASE e MONGODB_COLLECTION o lasciarli invariati.

Eseguire l'applicazione

Per creare un elemento todo

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

In caso di esito positivo, verrà visualizzato un output con l'elemento _id MongoDB del documento appena creato:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Creare un altro elemento todo

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

Elencare tutti gli elementi todo

./todo --list all

Dovrebbero essere visualizzati quelli appena aggiunti in un formato tabulare, ad esempio:

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

Per aggiornare lo stato di un oggetto todo ,ad esempio impostarlo completed sullo stato, usare l'ID todo :

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Elencare solo gli elementi todo completati

./todo --list completed

Verrà visualizzato quello appena aggiornato:

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

Visualizzare i dati in Esplora dati

I dati archiviati in Azure Cosmos DB sono disponibili per la visualizzazione e l'esecuzione di query nel portale di Azure.

Per visualizzare e usare i dati utente creati nel passaggio precedente, nonché eseguire query su di essi, accedere al portale di Azure nel Web browser.

Nella casella di ricerca nella parte superiore immettere Azure Cosmos DB. Quando il pannello dell'account Azure Cosmos DB si apre, selezionare l'account Azure Cosmos DB. Nel riquadro di spostamento a sinistra selezionare Esplora dati. Espandere la raccolta nel riquadro Raccolte. Sarà quindi possibile visualizzare i documenti nella raccolta, eseguire query sui dati e anche creare ed eseguire stored procedure, trigger e funzioni definite dall'utente.

Esplora dati con documento appena creato

Eliminare un todo oggetto usando il relativo ID:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Elencare gli todoelementi da confermare:

./todo --list all

L'elemento todo appena eliminato non deve essere presente:

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

Pulire le risorse

Dopo aver completato le operazioni con l'app e l'account Azure Cosmos DB, è possibile eliminare le risorse di Azure create in modo da non incorrere in altri costi. Per eliminare le risorse:

Nella barra di ricerca del portale di Azure cercare e selezionare Gruppi di risorse.
Selezionare nell'elenco il gruppo di risorse creato in questa guida di avvio rapido.
Nella pagina Panoramica del gruppo di risorse selezionare Elimina gruppo di risorse.
Nella finestra successiva immettere il nome del gruppo di risorse da eliminare e quindi selezionare Elimina.

Passaggi successivi

In questo argomento di avvio rapido si è appreso come creare un account dell'API Azure Cosmos DB for MongoDB usando Azure Cloud Shell e come creare ed eseguire un'app Go da riga di comando per gestire gli elementi todo. È ora possibile importare dati aggiuntivi nell'account Azure Cosmos DB.

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.

Se si conosce solo il numero di vcore e server nel cluster di database esistente, leggere le informazioni sulla stima delle unità richieste usando vCore o vCPU
Se si conosce la frequenza delle richieste tipiche per il carico di lavoro corrente del database, leggere le informazioni sulla stima delle unità richieste con lo strumento di pianificazione della capacità di Azure Cosmos DB

Importare i dati di MongoDB in Azure Cosmos DB

Guida introduttiva: Connessione un'applicazione Go in Azure Cosmos DB per MongoDB

Prerequisiti

Clonare l'applicazione di esempio

Esaminare il codice

Connessione dell'app Go ad Azure Cosmos DB

Creare un elemento todo

Elencare elementi todo

Aggiornare un elemento todo

Eliminare un elemento todo

Compilare l'applicazione

Configurazione di Azure Cosmos DB

Accedere ad Azure

Aggiungere il modulo Azure Cosmos DB

Creare un gruppo di risorse

Creare un account Azure Cosmos DB

Recuperare la chiave del database

Configurazione dell'applicazione

Esportare i nomi di stringa di connessione, database MongoDB e raccolta come variabili di ambiente.

Eseguire l'applicazione

Visualizzare i dati in Esplora dati

Pulire le risorse

Passaggi successivi

Risorse aggiuntive

Creare un elemento `todo`

Elencare elementi `todo`

Aggiornare un elemento `todo`

Eliminare un elemento `todo`