Início Rápido: Criar um aplicativo de console usando a API para MongoDB do Azure Cosmos DB e o SDK do GolangQuickstart: Build a console app using Azure Cosmos DB's API for MongoDB and Golang SDK

O Azure Cosmos DB é o serviço de banco de dados multimodelo distribuído globalmente da Microsoft.Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. É possível criar e consultar rapidamente bancos de dados de documentos, de chave/valor e de grafo, que se beneficiem das funcionalidades de escala horizontal e de distribuição global no núcleo do 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 Cosmos DB.

Este início rápido demonstra como usar um aplicativo MongoDB existente escrito em Golang e conectá-lo ao banco de dados do Cosmos usando a API para MongoDB do Azure Cosmos DB.This quickstart demonstrates how to take an existing MongoDB app written in Golang and connect it to your Cosmos database using the Azure Cosmos DB's API for MongoDB.

Em outras palavras, o aplicativo Golang só sabe que está se conectando usando um cliente do MongoDB.In other words, your Golang application only knows that it's connecting using a MongoDB client. Está claro para o aplicativo que os dados estão armazenados em um banco de dados do Cosmos.It is transparent to the application that the data is stored in a Cosmos database.

Pré-requisitosPrerequisites

  • Uma assinatura do Azure.An Azure subscription. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don’t have an Azure subscription, create a free account before you begin.

    Como alternativa, você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, gratuitamente e sem compromisso.Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Ou você pode usar o Emulador do Azure Cosmos DB neste tutorial com uma cadeia de conexão deOr 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 um conhecimento básico sobre a linguagem Go.Go and a basic knowledge of the Go language.

  • Um IDE — GoLand da Jetbrains, Visual Studio Code da Microsoft ou Atom.An IDE — GoLand by Jetbrains, Visual Studio Code by Microsoft, or Atom. Neste tutorial, estou usando GoLand.In this tutorial, I'm using GoLand.

Criar uma conta de banco de dadosCreate a database account

  1. Em uma nova janela, entre no portal do Azure.In a new window, sign in to the Azure portal.

  2. No menu à esquerda, selecione Criar um recurso, Bancos de dados e em Azure Cosmos DB, selecione Criar.In the left menu, select Create a resource, select Databases, and then under Azure Cosmos DB, select Create.

    Captura de tela do portal do Azure, realçando Mais Serviços e Azure Cosmos DB

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações da nova conta do Azure Cosmos DB.In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    SubscriptionSubscription Sua assinaturaYour subscription Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Criar NovoCreate new

    Em seguida, insira o mesmo nome exclusivo fornecido na IDThen enter the same unique name as provided in ID
    Selecione Criar novo.Select Create new. Insira o novo nome do grupo de recursos para sua conta.Then enter a new resource-group name for your account. Para simplificar, use um nome igual à sua ID.For simplicity, use the same name as your ID.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome exclusivo para identificar a conta do Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID deve conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. Ela precisa ter entre 3 e 31 caracteres.It must be between 3 and 31 characters in length.
    APIAPI API do Azure Cosmos DB para MongoDBAzure Cosmos DB's API for MongoDB A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Core (SQL) para bancos de dados de documentos, Gremlin para o bancos de dados de grafos, API para MongoDB do Azure Cosmos DB para bancos de dados de documentos, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, Azure Cosmos DB's API MongoDB for document databases, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione MongoDB, porque neste guia de início rápido você está criando uma tabela que funciona com o MongoDB.Select MongoDB because in this quickstart you are creating a table that works with the MongoDB.
    LocationLocation Selecione a região mais próxima de seus usuáriosSelect the region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use o local mais próximo dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that's closest to your users to give them the fastest access to the data.

    Selecione Revisar + Criar.Select Review+Create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags section.

    A página da nova conta do Azure Cosmos DB

  4. A criação da conta leva alguns minutos.The account creation takes a few minutes. Aguarde até que o portal exiba a página Parabéns! Sua conta do Cosmos com a compatibilidade de protocolo de transmissão para o MongoDB está pronta.Wait for the portal to display the Congratulations! Your Cosmos account with wire protocol compatibility for MongoDB is ready page.

    O painel Notificações do portal do Azure

Clonar o aplicativo de exemploClone the sample application

Clone o aplicativo de exemplo e instale os pacotes necessários.Clone the sample application and install the required packages.

  1. Crie uma pasta chamada CosmosDBSample dentro da pasta GOROOT\src, que é C:\Go\ por padrão.Create a folder named CosmosDBSample inside the GOROOT\src folder, which is C:\Go\ by default.

  2. Execute o comando a seguir usando uma janela do terminal git como git bash para clonar o repositório de exemplo na pasta 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. Execute o comando a seguir para obter o pacote mgo.Run the following command to get the mgo package.

    go get gopkg.in/mgo.v2
    

O driver mgo é um driver MongoDB para a linguagem Go que implementa uma seleção bem testada e avançada de recursos em uma API muito simples seguindo expressões Go padrão.The mgo driver 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.

Atualizar sua cadeia de conexãoUpdate your connection string

Agora, volte ao portal do Azure para obter informações sobre a cadeia de conexão e copiá-las para o aplicativo.Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. Clique em Início rápido no menu de navegação à esquerda e clique em Outros para exibir as informações de cadeia de conexão exigidas pelo aplicativo 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. No Goglang, abra o arquivo main.go no diretório GOROOT\CosmosDBSample e atualize as linhas de código a seguir usando as informações de cadeia de conexão do portal do Azure, conforme mostrado na captura de tela a seguir.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.

    O Nome do banco de dados é o prefixo do valor Host no painel de cadeia de conexão de portal do Azure.The Database name is the prefix of the Host value in the Azure portal connection string pane. Para a conta mostrada na imagem abaixo, o nome do banco de dados é 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",
    

    Painel Início rápido, guia Outros no portal do Azure mostrando as informações de cadeia de conexão

  3. Salve o arquivo main.go.Save the main.go file.

Examine o códigoReview the code

Esta etapa é opcional.This step is optional. Se você estiver interessado em aprender como os recursos de banco de dados são criados no código, poderá examinar os snippets de código a seguir.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Caso contrário, você poderá pular para Executar o aplicativo.Otherwise, you can skip ahead to Run the app.

Todos os snippets de código a seguir são retirados do arquivo main.go.The following snippets are all taken from the main.go file.

Conectando o aplicativo Go ao Cosmos DBConnecting the Go app to Cosmos DB

A API do Azure Cosmos DB para MongoDB dá suporte à conexão habilitada para SSL.Azure Cosmos DB's API for MongoDB supports the SSL-enabled connection. Para se conectar, você precisa definir a função DialServer em mgo.DialInfo e usar a função tls.Dial para realizar a conexão.To connect, you need to define the DialServer function in mgo.DialInfo, and make use of the tls.Dial function to perform the connection.

O snippet de código Golang a seguir se conecta ao aplicativo Go com a API para MongoDB do Azure Cosmos DB.The following Golang code snippet connects the Go app with Azure Cosmos DB's API for MongoDB. A classe DialInfo contém opções para estabelecer uma sessão.The DialInfo class holds options for establishing a session.

// DialInfo holds options for establishing a session.
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 Cosmos database (using Azure Cosmos DB's API for MongoDB).
session, err := mgo.DialWithInfo(dialInfo)

if err != nil {
    fmt.Printf("Can't connect, 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{})

O método mgo.Dial() é usado quando não há nenhuma conexão SSL.The mgo.Dial() method is used when there is no SSL connection. Para uma conexão SSL, o método mgo.DialWithInfo() é necessário.For an SSL connection, the mgo.DialWithInfo() method is required.

Uma instância do objeto DialWIthInfo{} é usada para criar o objeto de sessão.An instance of the DialWIthInfo{} object is used to create the session object. Quando a sessão é estabelecida, você pode acessar a coleção usando o snippet de código abaixo:Once the session is established, you can access the collection by using the following code snippet:

collection := session.DB("database").C("package")

Criar um 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
}

Consultar ou ler um documentoQuery or read a document

O Cosmos DB dá suporte a consultas avançadas de dados armazenados em cada coleção.Cosmos DB supports rich queries against data stored in each collection. O código de exemplo a seguir mostra uma consulta que pode ser executada em documentos em sua coleção.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)

Atualizar um 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
}

Excluir um documentoDelete a document

O Cosmos DB dá suporte à exclusão de documentos.Cosmos DB supports deletion of documents.

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

Execute o aplicativoRun the app

  1. No Golang, verifique se seu GOPATH (disponível em Arquivo, Configurações, Go, GOPATH) inclui a localização em que o gopkg foi instalado, que é PERFILDOUSUÁRIO/go por padrão.In Golang, 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. Comente as linhas que excluem o documento, linhas 103 a 107, para que você possa ver o documento depois de executar o aplicativo.Comment out the lines that delete the document, lines 103-107, so that you can see the document after running the app.

  3. No Golang, clique em Executar e em Executar 'Compilar main.go e executar'.In Golang, click Run, and then click Run 'Build main.go and run'.

    O aplicativo termina e exibe a descrição do documento criado em Criar um 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
    

    Golang mostrando a saída do aplicativo

Revisar o documento no Data ExplorerReview your document in Data Explorer

Volte para o portal do Azure a fim de ver o documento no Data Explorer.Go back to the Azure portal to see your document in Data Explorer.

  1. Clique em Data Explorer (Versão prévia) no menu de navegação à esquerda, expanda golang-coach, pacotee clique em Documentos.Click Data Explorer (Preview) in the left navigation menu, expand golang-coach, package, and then click Documents. Na guia Documentos , clique na _id para exibir o documento no painel direito.In the Documents tab, click the _id to display the document in the right pane.

    Data Explorer mostrando o documento recém-criado

  2. Você pode trabalhar com o documento em linha e clicar em Atualizar para salvá-lo.You can then work with the document inline and click Update to save it. Você também pode excluir o documento ou criar novos documentos ou consultas.You can also delete the document, or create new documents or queries.

Examinar SLAs no Portal do AzureReview SLAs in the Azure portal

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da conta do Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Gráficos de métricas associados a um SLA (Contrato de Nível de Serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Esse conjunto de métricas torna o monitoramento dos SLAs transparente.This suite of metrics makes monitoring your SLAs transparent.

Para examinar as métricas e os SLAs:To review metrics and SLAs:

  1. Selecione Métricas no menu de navegação da sua conta do Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selecione uma guia, tal como Latência, e selecione um período à direita.Select a tab such as Latency, and select a timeframe on the right. Comparar as linhas Real e SLA dos gráficos.Compare the Actual and SLA lines on the charts.

    Pacote de métricas do Azure Cosmos DB

  3. Examine as métricas nas outras guias.Review the metrics on the other tabs.

Limpar recursosClean up resources

Quando você concluir seu aplicativo Web e a conta do Azure Cosmos DB, poderá excluir os recursos do Azure criados para não incorrer em mais cobranças.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para excluir os recursos:To delete the resources:

  1. No portal do Azure, selecione Grupos de recursos no canto esquerdo.In the Azure portal, select Resource groups on the far left. Se o menu esquerdo estiver recolhido, selecione Expandir botão para expandi-lo.If the left menu is collapsed, select Expand button to expand it.

  2. Selecione o grupo de recursos que você criou para este início rápido.Select the resource group you created for this quickstart.

    Métricas no portal do Azure

  3. Na nova janela, selecione Excluir grupo de recursos.In the new window, select Delete resource group.

    Métricas no portal do Azure

  4. Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.In the next window, enter the name of the resource group to delete, and then select Delete.

Próximas etapasNext steps

Neste início rápido, você aprendeu como criar uma conta do Cosmos e executar um aplicativo Golang.In this quickstart, you've learned how to create a Cosmos account and run a Golang app. Agora você pode importar dados adicionais para o banco de dados Cosmos.You can now import additional data to your Cosmos database.