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 connetterla al database Azure Cosmos DB, che supporta connessioni client 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.

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 una stringa di connession diOr 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 Nuovo, quindi su Database e in Azure Cosmos DB fare clic su Crea.In the left menu, click New, 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 la configurazione desiderata per l'account Azure Cosmos DB.In the New account blade, specify the desired configuration for the Azure Cosmos DB account.

    Con Azure Cosmos DB è possibile scegliere uno dei quattro modelli di programmazione: Gremlin (graph), MongoDB, SQL (DocumentDB) e Table (key-value).With Azure Cosmos DB, you can choose one of four programming models: Gremlin (graph), MongoDB, SQL (DocumentDB), and Table (key-value).

    In questa guida introduttiva eseguiremo la programmazione in base all'API MongoDB, per cui occorrerà scegliere MongoDB nella compilazione del modulo.In this quick start we'll be programming against the MongoDB API so you'll choose MongoDB as you fill out the form. 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.But if you have graph data for a social media app, document data from a catalog app, or key/value (table) data, realize that Azure Cosmos DB can provide a highly available, globally-distributed database service platform for all your mission-critical applications.

    Compilare il pannello Nuovo account usando le informazioni riportate nella tabella come guida.Fill out the New account blade using the information in the table as a guide.

    Screenshot del pannello Nuovo Azure Cosmos DB

    ImpostazioneSetting Valore consigliatoSuggested value DescrizioneDescription
    IDID Valore univocoUnique value Nome univoco scelto per identificare l'account Azure Cosmos DB.A unique name you choose to identify the Azure Cosmos DB account. Poiché alI'ID fornito viene aggiunto documents.azure.com per creare l'URI, usare un ID univoco ma facilmente identificabile.documents.azure.com is appended to the ID you provide to create your URI, so use a unique but identifiable ID. L'ID può contenere solo lettere minuscole, numeri e il carattere '-' e deve avere una lunghezza compresa tra 3 e 50 caratteri.The ID may contain only lowercase letters, numbers, and the '-' character, and must be between 3 and 50 characters.
    APIAPI MongoDBMongoDB L'API determina il tipo di account da creare.The API determines the type of account to create. Azure Cosmos DB offre cinque API per soddisfare le esigenze dell'applicazione, ovvero SQL (database di documenti) Gremlin (grafo), MongoDB, SQL (database di documenti), Tabella di Azure e Cassandra, per ognuna delle quali è attualmente necessario un account separato.Azure Cosmos DB provides five APIs to suits the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, each which currently require a separate account.

    Selezionare MongoDB perché in questa guida introduttiva si crea un database di documenti su cui è possibile eseguire query usando MongoDB.Select MongoDB because in this quickstart you are creating a document database that is queryable using MongoDB.

    Altre informazioni sull'API MongoDBLearn more about the MongoDB API
    SottoscrizioneSubscription Sottoscrizione in usoYour subscription Sottoscrizione di Azure da usare per l'account Azure Cosmos DB.The Azure subscription that you want to use for the Azure Cosmos DB account.
    Gruppo di risorseResource Group Stesso valore di IDThe same value as ID Nome del nuovo gruppo di risorse per l'account.The 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.
    LocalitàLocation Area più vicina ai propri utentiThe region closest to your users Posizione geografica in cui ospitare l'account Azure Cosmos DB.The geographic location in which to host your Azure Cosmos DB account. Scegliere la posizione più vicina ai propri utenti per fornire loro l'accesso più rapido possibile ai dati.Choose the location closest to your users to give them the fastest access to the data.
  4. Fare clic su Crea per creare l'account.Click Create to create the account.

  5. Sulla barra degli strumenti fare clic su Notifiche per monitorare il processo di distribuzione.On the toolbar, click Notifications to monitor the deployment process.

    Notifica di distribuzione avviata

  6. Al termine della distribuzione aprire il nuovo account dal riquadro Tutte le risorse.When the deployment is complete, open the new account from the All Resources tile.

    Account Azure Cosmos DB nel riquadro Tutte le risorse

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

Di seguito è riportata una breve panoramica delle operazioni eseguite nel file main.go.Let's make a quick review of what's happening in 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 91-96 che eliminano il documento per poter visualizzare il documento dopo l'esecuzione dell'app.Comment out the lines that delete the document, lines 91-96, 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 nel portale di Azure eseguendo questi passaggi:If you're not going to continue to use this app, delete all resources created by this quickstart in the Azure portal with the following steps:

  1. Scegliere Gruppi di risorse dal menu a sinistra del portale di Azure e quindi fare clic sul nome della risorsa creata.From the left-hand menu in the Azure portal, click Resource groups and then click the name of the resource you created.
  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.On your resource group page, click Delete, type the name of the resource to delete in the text box, 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.