Azure Cosmos DB: creare un'app console per le API MongoDB con Golang e il portale di AzureAzure Cosmos DB: Build a MongoDB API console app with Golang and the Azure portal

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. È 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.You can quickly create and query document, key/value, and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Azure Cosmos DB.

Questa guida introduttiva illustra come usare un'app MongoDB esistente scritta in Golang e come connetterla al database Azure Cosmos DB, che supporta le connessioni client MongoDB usando l'API di MongoDB.This quick-start demonstrates how to use an existing MongoDB app written in Golang and connect it to your Azure Cosmos DB database, which supports MongoDB client connections by using the MongoDB API.

In altri termini, l'applicazione Golang rileva solo la connessione a un database con API MongoDB.In other words, your Golang application only knows that it's connecting to a database using MongoDB APIs. Il fatto che i dati siano archiviati in Azure Cosmos DB è trasparente per l'applicazione.It is transparent to the application that the data is stored in Azure Cosmos DB.

prerequisitiPrerequisites

  • Una sottoscrizione di Azure.An Azure subscription. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don’t have an Azure subscription, create a free account before you begin.

    In alternativa, è possibile provare gratuitamente Microsoft Azure Cosmos DB senza una sottoscrizione di Azure e senza impegnoAlternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. oppure usare l'emulatore Azure Cosmos DB per questa esercitazione, con la stringa di connessione seguente:Or you can use the Azure Cosmos DB Emulator for this tutorial with a connection string of

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

  • Un IDE. Gogland di Jetbrains, Visual Studio Code di Microsoft o Atom.An IDE — Gogland by Jetbrains, Visual Studio Code by Microsoft, or Atom. In questa esercitazione si usa Gogland.In this tutorial, I'm using Goglang.

Creare un account di databaseCreate a database account

  1. In una nuova finestra accedere al portale di Azure.In a new window, sign in to the Azure portal.
  2. Nel menu a sinistra fare clic su Crea una risorsa, quindi su Database e infine in Azure Cosmos DB fare clic su Crea.In the left menu, click Create a resource, click Databases, and then under Azure Cosmos DB, click Create.

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

  3. Nel pannello Nuovo account specificare MongoDB per l'API e immettere le informazioni relative alla configurazione desiderata per l'account Azure Cosmos DB.In the New account blade, specify MongoDB as the API and fill out your desired configuration for the Azure Cosmos DB account.

    • ID deve essere un nome univoco da usare per identificare l'account Azure Cosmos DB.ID must be a unique name you wish to use to identify your Azure Cosmos DB account. Può contenere solo lettere minuscole, numeri, il carattere "-" e deve essere compreso fra 3 e 50 caratteri.It may only contain lower case letters, numbers, the '-' character, and must be between 3 and 50 characters.
    • Sottoscrizione è la sottoscrizione di AzureSubscription is your Azure subscription. e viene compilata automaticamente.It will be filled out for you.
    • Gruppo di risorse è il nome del gruppo di risorse per l'account Azure Cosmos DB.Resource Group is the resource group name for your Azure Cosmos DB account. Selezionare Crea nuovo, quindi immettere il nome di un nuovo gruppo di risorse per l'account.Select Create New, then enter a new resource-group name for your account. Per semplicità si può usare lo stesso nome usato come ID.For simplicity, you can use the same name as your ID.
    • Percorso è la posizione geografica in cui si trova l'istanza di Azure Cosmos DB.Location is the geographic location where your Azure Cosmos DB instance is located. Scegliere la località più vicina agli utenti.Choose the location closest to your users.

      Fare quindi clic su Crea.Then click Create.

      Pagina del nuovo account per Azure Cosmos DB

  4. La creazione dell'account richiede alcuni minuti,The account creation takes a few minutes. Attendere che nel portale venga visualizzata la pagina Complimenti, L'account Azure Cosmos DB con l'API MongoDB è pronto.Wait for the portal to display the Congratulations! Your Azure Cosmos DB account with MongoDB API is ready page.

    Riquadro Notifiche del portale di Azure

Clonare l'applicazione di esempioClone the sample application

Clonare l'applicazione di esempio e installare i pacchetti necessari.Clone the sample application and install the required packages.

  1. Creare una cartella denominata CosmosDBSample all'interno della cartella GOROOT\src, che per impostazione predefinita è C:\Go.Create a folder named CosmosDBSample inside the GOROOT\src folder, which is C:\Go\ by default.
  2. Eseguire questo comando usando una finestra del terminale git, ad esempio git bash, per clonare il repository di esempio nella cartella CosmosDBSample.Run the following command using a git terminal window such as git bash to clone the sample repository into the CosmosDBSample folder.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-mongodb-golang-getting-started.git
    
  3. Eseguire questo comando per ottenere il pacchetto mgo.Run the following command to get the mgo package.

    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.The mgo driver (pronounced as mango) is a MongoDB driver for the Go language that implements a rich and well tested selection of features under a very simple API following standard Go idioms.

Aggiornare la stringa di connessioneUpdate your connection string

Tornare ora al portale di Azure per recuperare le informazioni sulla stringa di connessione e copiarle nell'app.Now go back to the Azure portal to get your connection string information and copy it into the 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.Click Quick start in the left navigation menu, and then click Other to view the connection string information required by the Go application.

  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.In Goglang, open the main.go file in the GOROOT\CosmosDBSample directory and update the following lines of code using the connection string information from the Azure portal as shown in the following screenshot.

    Il nome del database è il prefisso del valore Host nel riquadro relativo alla stringa di connessione del portale di Azure.The Database name is the prefix of the Host value in the Azure portal connection string pane. Per l'account riportato nell'immagine seguente, il nome del database è golang-coach.For the account shown in the image below, the Database name is 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.Save the main.go file.

Esaminare il codiceReview the code

Questo passaggio è facoltativo.This step is optional. Per scoprire in che modo le risorse del database vengono create nel codice, è possibile esaminare i frammenti di codice seguenti.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Altrimenti è possibile passare direttamente a Esecuzione dell'app.Otherwise, you can skip ahead to Run the app.

Tutti i frammenti di codice seguenti sono tratti dal file main.go.The following snippets are all taken from the main.go file.

Connessione dell'app Go ad Azure Cosmos DBConnecting the Go app to Azure Cosmos DB

Azure Cosmos DB supporta le istanze di MongoDB abilitate per SSL.Azure Cosmos DB supports the SSL-enabled MongoDB. 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.To connect to an SSL-enabled MongoDB, you need to define the DialServer function in mgo.DialInfo, and make use of the tls.Dial function to perform the connection.

Il frammento di codice Golang seguente connette l'app Go con l'API MongoDB di Azure Cosmos DB.The following Golang code snippet connects the Go app with Azure Cosmos DB MongoDB API. La classe DialInfo contiene opzioni per stabilire una sessione con un cluster MongoDB.The DialInfo class holds options for establishing a session with a MongoDB cluster.

// 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.The mgo.Dial() method is used when there is no SSL connection. Per una connessione SSL è necessario il metodo mgo.DialWithInfo().For an SSL connection, the mgo.DialWithInfo() method is required.

Per creare l'oggetto sessione viene usata un'istanza dell'oggetto DialWIthInfo{}.An instance of the DialWIthInfo{} object is used to create the session object. Dopo che la sessione è stata stabilita, è possibile accedere alla raccolta usando il frammento di codice seguente:Once the session is established, you can access the collection by using the following code snippet:

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

Creare un documentoCreate a document

// 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 documentoQuery or read a document

Azure Cosmos DB supporta query avanzate sui documenti JSON archiviati in ogni raccolta.Azure Cosmos DB supports rich queries against JSON documents stored in each collection. L'esempio di codice seguente illustra una query eseguibile nei documenti della raccolta.The following sample code shows a query that you can run against the documents in your collection.

// 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 documentoUpdate a document

// 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 documentoDelete a document

Azure Cosmos DB supporta l'eliminazione di documenti JSON.Azure Cosmos DB supports deleting JSON documents.

// 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'appRun the 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.In Goglang, ensure that your GOPATH (available under File, Settings, Go, GOPATH) include the location in which the gopkg was installed, which is USERPROFILE\go by default.
  2. Impostare come commento le righe da 103 a 107, che eliminano il documento, per poter visualizzare il documento dopo l'esecuzione dell'app.Comment out the lines that delete the document, lines 103-107, so that you can see the document after running the app.
  3. In Gogland fare clic su Run (Esegui) e quindi su Run 'Build main.go and run' (Esegui 'Compila main.go ed esegui').In Goglang, click Run, and then click Run 'Build main.go and run'.

    L'app viene completata e visualizza la descrizione del documento creato in Creare un documento.The app finishes and displays the description of the document created in Create a document.

    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 datiReview your document in Data Explorer

Tornare al portale di Azure per visualizzare il documento in Esplora dati.Go back to the Azure portal to see your document in Data Explorer.

  1. Fare clic su Esplora dati (anteprima) nel menu di spostamento a sinistra, espandere golang-coach, pacchetto e quindi fare clic su Documenti.Click Data Explorer (Preview) in the left navigation menu, expand golang-coach, package, and then click Documents. Nella scheda Documenti fare clic su _id per visualizzare il documento nel riquadro destro.In the Documents tab, click the _id to display the document in the right pane.

    Esplora dati con documento appena creato

  2. Si può quindi lavorare sul documento inline e fare clic su Aggiorna per salvarlo.You can then work with the document inline and click Update to save it. È anche possibile eliminare il documento oppure creare nuovi documenti o nuove query.You can also delete the document, or create new documents or queries.

Esaminare i contratti di servizio nel portale di AzureReview SLAs in the Azure portal

La velocità effettiva, lo spazio di archiviazione, la disponibilità, la latenza e la coerenza delle risorse nell'account vengono monitorati nel portale di Azure.The throughput, storage, availability, latency, and consistency of the resources in your account are monitored in the Azure portal. Di seguito vengono illustrate brevemente queste metriche.Let's take a quick look at these metrics.

  1. Fare clic su Metriche nel menu di spostamento.Click Metrics in the navigation menu.

    Metriche nel portale di Azure

  2. Fare clic su ogni scheda per conoscere le metriche offerte da Azure Cosmos DB.Click through each of the tabs so you're aware of the metrics Azure Cosmos DB provides.

    Ogni grafico associato ai contratti di servizio per Azure Cosmos DB contiene una linea che indica le eventuali violazioni dei contratti di servizio.Each chart that's associated with the Azure Cosmos DB Service Level Agreements (SLAs) provides a line that shows if any of the SLAs have been violated. Con questo gruppo di metriche, Azure Cosmos DB garantisce trasparenza nel monitoraggio dei contratti di servizio.Azure Cosmos DB makes monitoring your SLAs transparent with this suite of metrics.

    Gruppo di metriche di Azure Cosmos DB

Pulire le risorseClean up resources

Se non si intende continuare a usare l'app, eliminare tutte le risorse create tramite questa guida di avvio rapido eseguendo i passaggi seguenti, per evitare qualsiasi addebito:If you're not going to continue to use this app, delete all resources created by this quickstart with the following steps so you don't incur any charges:

  1. Nel portale di Azure selezionare Gruppi di risorse all'estrema sinistra e quindi selezionare il gruppo di risorse creato.In the Azure portal, select Resource groups on the far left, and then select the resource group you created.

    Se il menu a sinistra è compresso, fare clic sulIf the left menu is collapsed, click pulsante Espandi per espanderlo.to expand it.

    Metriche nel portale di Azure

  2. Nella nuova finestra selezionare il gruppo di risorse e quindi fare clic su Elimina gruppo di risorse.In the new window select the resource group, and then click Delete resource group.

    Metriche nel portale di Azure

  3. Nella nuova finestra digitare il nome del gruppo di risorse da eliminare e quindi fare clic su Elimina.In the new window, type the name of the resource group to delete, and then click Delete.

Passaggi successiviNext steps

In questa guida introduttiva si è appreso come creare un account Azure Cosmos DB ed eseguire un'app Golang con l'API per MongoDB.In this quickstart, you've learned how to create an Azure Cosmos DB account and run a Golang app using the API for MongoDB. È ora possibile importare dati aggiuntivi nell'account Cosmos DB.You can now import additional data to your Cosmos DB account.