Azure Cosmos DB: creare un'app console per le API MongoDB con Golang e il portale di Azure

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft. È possibile creare ed eseguire rapidamente query su database di documenti, coppie chiave/valore e grafi, sfruttando in ognuno dei casi i vantaggi offerti dalle funzionalità di scalabilità orizzontale e distribuzione globale alla base di Azure Cosmos DB.

Questa guida introduttiva illustra come usare un'app MongoDB esistente scritta in Golang e connetterla al database Azure Cosmos DB, che supporta connessioni client MongoDB.

In altri termini, l'applicazione Golang rileva solo la connessione a un database con API MongoDB. Il fatto che i dati siano archiviati in Azure Cosmos DB è trasparente per l'applicazione.

Prerequisiti

  • Una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

    In alternativa, è possibile provare gratuitamente Microsoft Azure Cosmos DB senza una sottoscrizione di Azure e senza impegno oppure usare l'emulatore Azure Cosmos DB per questa esercitazione, con una stringa di connession di

    mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true
    
  • Go e una conoscenza di base del linguaggio Go.

  • Un IDE. Gogland di Jetbrains, Visual Studio Code di Microsoft o Atom. In questa esercitazione si usa Gogland.

Creare un account di database

  1. In una nuova finestra accedere al portale di Azure.
  2. Nel menu a sinistra fare clic su Nuovo, quindi su Database e in Azure Cosmos DB fare clic su Crea.

    Screenshot del portale di Azure in cui sono evidenziati Altri servizi e Azure Cosmos DB

  3. Nel pannello Nuovo account specificare la configurazione desiderata per l'account Azure Cosmos DB.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (graph), MongoDB, SQL (DocumentDB) e Table (key-value).

    In questa guida introduttiva eseguiremo la programmazione in base all'API MongoDB, per cui occorrerà scegliere MongoDB nella compilazione del modulo. Tuttavia, se si dispone di dati grafo per un'app social media, dati documento di un'app di catalogo o dati chiave-valore (tabella), tenere presente che Azure Cosmos DB può fornire una piattaforma di servizi di database distribuiti a livello globale e a disponibilità elevata per tutte le applicazioni cruciali.

    Compilare il pannello Nuovo account usando le informazioni riportate nella tabella come guida.

    Screenshot del pannello Nuovo Azure Cosmos DB

    Impostazione Valore consigliato Descrizione
    ID Valore univoco Nome univoco scelto per identificare l'account Azure Cosmos DB. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile. L'ID può contenere solo lettere minuscole, numeri e il carattere '-' e deve avere una lunghezza compresa tra 3 e 50 caratteri.
    API MongoDB Eseguiremo la programmazione in base all'API MongoDB più avanti in questo articolo.
    Sottoscrizione Sottoscrizione in uso Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.
    Gruppo di risorse Stesso valore di ID Nome del nuovo gruppo di risorse per l'account. Per semplicità si può usare lo stesso nome usato come ID.
    Località Area più vicina ai propri utenti Posizione geografica in cui ospitare l'account Azure Cosmos DB. Scegliere la posizione più vicina ai propri utenti per fornire loro l'accesso più rapido possibile ai dati.
  4. Fare clic su Crea per creare l'account.

  5. Sulla barra degli strumenti fare clic su Notifiche per monitorare il processo di distribuzione.

    Notifica di distribuzione avviata

  6. Al termine della distribuzione aprire il nuovo account dal riquadro Tutte le risorse.

    Account Azure Cosmos DB nel riquadro Tutte le risorse

Clonare l'applicazione di esempio

Clonare l'applicazione di esempio e installare i pacchetti necessari.

  1. Creare una cartella denominata CosmosDBSample all'interno della cartella GOROOT\src, che per impostazione predefinita è C:\Go.
  2. Eseguire questo comando usando una finestra del terminale git, ad esempio git bash, per clonare il repository di esempio nella cartella CosmosDBSample.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-mongodb-golang-getting-started.git
    
  3. Eseguire questo comando per ottenere il pacchetto mgo.

    go get gopkg.in/mgo.v2
    

Il driver mgo (pronunciato mango) è un driver MongoDB per il linguaggio Go che implementa una selezione estesa e ben collaudata di funzionalità in un'API molto semplice basata sui termini Go standard.

Aggiornare la stringa di connessione

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.

  1. Fare clic su Avvio rapido nel menu di spostamento a sinistra e quindi su Altri per visualizzare le informazioni relative alla stringa di connessione necessarie per l'applicazione Go.

  2. In Gogland aprire il file main.go nella directory GOROOT\CosmosDBSample e aggiornare le righe di codice seguenti usando le informazioni relative alla stringa di connessione del portale di Azure illustrate nello screenshot riportato di seguito.

    Il nome del database è il prefisso del valore Host nel riquadro relativo alla stringa di connessione del portale di Azure. Per l'account riportato nell'immagine seguente, il nome del database è golang-coach.

    Database: "The prefix of the Host value in the Azure portal",
    Username: "The Username in the Azure portal",
    Password: "The Password in the Azure portal",
    

    Scheda Altri del riquadro Avvio rapido nel portale di Azure con le informazioni relative alla stringa di connessione

  3. Salvare il file main.go.

Esaminare il codice

Di seguito è riportata una breve panoramica delle operazioni eseguite nel file main.go.

Connessione dell'app Go ad Azure Cosmos DB

Azure Cosmos DB supporta le istanze di MongoDB abilitate per SSL. Per connettersi a un'istanza di MongoDB abilitata per SSL, è necessario definire la funzione DialServer in mgo.DialInfo e usare la funzione tls.Dial per eseguire la connessione.

Il frammento di codice Golang seguente connette l'app Go con l'API MongoDB di Azure Cosmos DB. La classe DialInfo contiene opzioni per stabilire una sessione con un cluster MongoDB.

// DialInfo holds options for establishing a session with a MongoDB cluster.
dialInfo := &mgo.DialInfo{
    Addrs:    []string{"golang-couch.documents.azure.com:10255"}, // Get HOST + PORT
    Timeout:  60 * time.Second,
    Database: "database", // It can be anything
    Username: "username", // Username
    Password: "Azure database connect password from Azure Portal", // PASSWORD
    DialServer: func(addr *mgo.ServerAddr) (net.Conn, error) {
        return tls.Dial("tcp", addr.String(), &tls.Config{})
    },
}

// Create a session which maintains a pool of socket connections
// to our Azure Cosmos DB MongoDB database.
session, err := mgo.DialWithInfo(dialInfo)

if err != nil {
    fmt.Printf("Can't connect to mongo, go error %v\n", err)
    os.Exit(1)
}

defer session.Close()

// SetSafe changes the session safety mode.
// If the safe parameter is nil, the session is put in unsafe mode, 
// and writes become fire-and-forget,
// without error checking. The unsafe mode is faster since operations won't hold on waiting for a confirmation.
// 
session.SetSafe(&mgo.Safe{})

Il metodo mgo.Dial() viene usato quando non è disponibile una connessione SSL. Per una connessione SSL è necessario il metodo mgo.DialWithInfo().

Per creare l'oggetto sessione viene usata un'istanza dell'oggetto DialWIthInfo{}. Dopo che la sessione è stata stabilita, è possibile accedere alla raccolta usando il frammento di codice seguente:

collection := session.DB(“database”).C(“package”)

Creare un documento

// Model
type Package struct {
    Id bson.ObjectId  `bson:"_id,omitempty"`
    FullName      string
    Description   string
    StarsCount    int
    ForksCount    int
    LastUpdatedBy string
}

// insert Document in collection
err = collection.Insert(&Package{
    FullName:"react",
    Description:"A framework for building native apps with React.",
    ForksCount: 11392,
    StarsCount:48794,
    LastUpdatedBy:"shergin",

})

if err != nil {
    log.Fatal("Problem inserting data: ", err)
    return
}

Leggere o eseguire query in un documento

Azure Cosmos DB supporta query avanzate sui documenti JSON archiviati in ogni raccolta. L'esempio di codice seguente illustra una query eseguibile nei documenti della raccolta.

// Get a Document from the collection
result := Package{}
err = collection.Find(bson.M{"fullname": "react"}).One(&result)
if err != nil {
    log.Fatal("Error finding record: ", err)
    return
}

fmt.Println("Description:", result.Description)

Aggiornare un documento

// Update a document
updateQuery := bson.M{"_id": result.Id}
change := bson.M{"$set": bson.M{"fullname": "react-native"}}
err = collection.Update(updateQuery, change)
if err != nil {
    log.Fatal("Error updating record: ", err)
    return
}

Eliminare un documento

Azure Cosmos DB supporta l'eliminazione di documenti JSON.

// Delete a document
query := bson.M{"_id": result.Id}
err = collection.Remove(query)
if err != nil {
   log.Fatal("Error deleting record: ", err)
   return
}

Esecuzione dell'app

  1. In Gogland verificare che il valore GOPATH, disponibile in File, Settings (Impostazioni), Go, GOPATH, includa il percorso di installazione di gopkg, che per impostazione predefinita è USERPROFILE\g.
  2. Impostare come commento le righe 91-96 che eliminano il documento per poter visualizzare il documento dopo l'esecuzione dell'app.
  3. In Gogland fare clic su Run (Esegui) e quindi su Run 'Build main.go and run' (Esegui 'Compila main.go ed esegui').

    L'app viene completata e visualizza la descrizione del documento creato in Creare un documento.

    Description: A framework for building native apps with React.
    
    Process finished with exit code 0
    

    Visualizzazione dell'output dell'app in Gogland

Esaminare il documento in Esplora dati

Tornare al portale di Azure per visualizzare il documento in Esplora dati.

  1. Fare clic su Esplora dati (anteprima) nel menu di spostamento a sinistra, espandere golang-coach, pacchetto e quindi fare clic su Documenti. Nella scheda Documenti fare clic su _id per visualizzare il documento nel riquadro destro.

    Esplora dati con documento appena creato

  2. Si può quindi lavorare sul documento inline e fare clic su Aggiorna per salvarlo. È anche possibile eliminare il documento oppure creare nuovi documenti o nuove query.

Esaminare i contratti di servizio nel portale di Azure

Ora che l'app è operativa, è opportuno garantire la continuità aziendale e controllare l'accesso degli utenti per garantire disponibilità elevata. Per esaminare la disponibilità, la latenza, la velocità effettiva e la coerenza della raccolta, si può usare il portale di Azure.

Ogni grafo associato ai contratti di servizio per Azure Cosmos DB fornisce una linea che mostra la quota necessaria per soddisfare il contratto di servizio e l'utilizzo effettivo. Queste informazioni offrono una panoramica chiara sulle prestazioni del database. Nel portale sono anche incluse altre metriche, ad esempio per quanto riguarda l'uso dello spazio di archiviazione e il numero di richieste al minuto.

  • Nel riquadro a sinistra del portale di Azure, in Monitoraggio, selezionare Metriche.

    App elenco attività con dati di esempio

Pulire le risorse

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido nel portale di Azure eseguendo questi passaggi:

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.
  2. Nella pagina del gruppo di risorse fare clic su Elimina, digitare il nome della risorsa da eliminare nella casella di testo e quindi fare clic su Elimina.

Passaggi successivi

In questa guida introduttiva si è appreso come creare un account Azure Cosmos DB ed eseguire un'app Golang con l'API per MongoDB. È ora possibile importare dati aggiuntivi nell'account Cosmos DB.