Compartilhar via

Início Rápido: Conectar um aplicativo Go à API do Azure Cosmos DB for MongoDB

  • Artigo

APLICA-SE AO: MongoDB

O Azure Cosmos DB é um serviço de banco de dados multimodelo que permite criar e consultar rapidamente bancos de dados de documentos, tabelas, pares chave-valor e grafo com funcionalidades de escala horizontal e distribuição global. Neste início rápido você cria e gerencia uma conta do Azure Cosmos DB usando o Azure Cloud Shell, clona um aplicativo de exemplo existente do GitHub e configura ele para funcionar com o Azure Cosmos DB.

O aplicativo de exemplo é uma ferramenta de gerenciamento todo baseada em linha de comando escrita em Go. A API do Azure Cosmos DB para MongoDB é compatível com o protocolo de transmissão do MongoDB, possibilitando que qualquer driver cliente do MongoDB se conecte a ele. Esse aplicativo usa o Driver do Go para MongoDB de maneira transparente para o aplicativo em que os dados são armazenados em um banco de dados do Azure Cosmos DB.

Pré-requisitos

Clonar o aplicativo de exemplo

Execute os comandos a seguir para clonar o repositório de exemplo.

  1. Abra um prompt de comando, crie uma pasta chamada git-samples e, em seguida, feche o prompt de comando.

    mkdir "C:\git-samples"

  2. Abra uma janela de terminal de git, como git bash, e use o comando cd para alterar para a nova pasta para instalar o aplicativo de exemplo.

    cd "C:\git-samples"

  3. Execute o comando a seguir para clonar o repositório de exemplo. Este comando cria uma cópia do aplicativo de exemplo no seu computador.

    git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart

Examine o código

Esta etapa é opcional. Se você estiver interessado em aprender como o aplicativo funciona, poderá examinar os trechos de código a seguir. Caso contrário, você poderá passar direto para Executar o aplicativo. O layout do aplicativo é o seguinte:

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

Todos os snippets de código a seguir são retirados do arquivo todo.go.

Conectando o aplicativo Go para o BD Cosmos do Azure

clientOptions encapsula a cadeia de conexão para o Azure Cosmos DB, que é passada usando uma variável de ambiente (detalhes na próxima seção). A conexão é inicializada usando mongo.NewClient, ao qual a instância de clientOptions é passada. A Pingfunção é invocada para confirmar a conectividade bem-sucedida (trata-se de uma estratégia fail-fast).

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

Observação

Usar a configuração SetDirect(true) é importante, pois sem ela você verá o seguinte erro de conectividade: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Criar um item de todo

Para criar um todo, obtemos um vínculo para um mongo.Collection e invocamos a função 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)
    }

Passamos um struct Todo que contém a descrição e o status (inicialmente definido como pending):

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

Listar itens de todo

Podemos listar as Tarefas Pendentes com base em critérios. Um bson.D é criado para encapsular os critérios de 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 é usado para pesquisar documentos com base no filtro e o resultado é convertido em uma fatia de 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)
    }

Por fim, as informações são renderizadas em formato tabular:

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

Atualizar um item de todo

Um todo pode ser atualizado com base em seu _id. Um filtro de bson.D é criado com base no _id e outro é criado para as informações atualizadas, que é um novo status (completed ou pending) nesse caso. Por fim, a função UpdateOne é invocada com o filtro e o documento atualizado:

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

Excluir um todo

Um todo é excluído com base em seu _id e é encapsulado na forma de uma instância bson.D. DeleteOne é invocado para excluir o 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)
    }
}

Compilar o aplicativo

Mude para o diretório em que você clonou o aplicativo e crie-o (usando go build).

cd monogdb-go-quickstart
go build -o todo

Para verificar se o aplicativo foi criado corretamente.

./todo --help

Configurar o Azure Cosmos DB

Entrar no Azure

Se você optar por instalar e usar a CLI localmente, este tópico exigirá a execução da CLI do Azure versão 2.0 ou posterior. Execute az --version para encontrar a versão. Caso precise instalá-la ou atualizá-la, confira [Instalar a CLI do Azure].

Se estiver usando uma CLI do Azure instalada, entre em sua assinatura do Azure com o comando az login e siga as instruções na tela. Você poderá ignorar esta etapa se estiver usando o Azure Cloud Shell.

az login

Adicione o módulo do BD Cosmos do Azure

Se você estiver usando uma CLI do Azure instalada, verifique se o componente cosmosdb já está instalado ao executar o comando az. Se cosmosdb estiver na lista de comandos básicos, vá para o próximo comando. Você poderá ignorar esta etapa se estiver usando o Azure Cloud Shell.

Se cosmosdb não estiver na lista de comandos base, reinstale a CLI do Azure.

Criar um grupo de recursos

Crie um grupo de recursos com o az group create. Um grupo de recursos do Azure é um contêiner lógico no qual recursos do Azure, como aplicativos da Web, bancos de dados e contas de armazenamento são implantados e gerenciados.

O exemplo a seguir cria um grupo de recursos na região da Europa Ocidental. Escolha um nome exclusivo para o grupo de recursos.

Se você estiver usando o Azure Cloud Shell, selecione Experimente, siga as instruções na tela para fazer logon e copie o comando para o prompt de comando.

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

Criar uma conta do Azure Cosmos DB

Crie uma conta do BD Cosmos do Azure usando o comando az cosmosdb create.

No comando a seguir, substitua seu próprio nome de conta exclusivo do BD Cosmos do Azure quando vir o espaço reservado <cosmosdb-name>. Esse nome exclusivo será usado como parte de seu ponto de extremidade do BD Cosmos do Azure (https://<cosmosdb-name>.documents.azure.com/), portanto, o nome precisa ser exclusivo em todas as contas do BD Cosmos do Azure no Azure.

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

O parâmetro --kind MongoDB habilita conexões do cliente MongoDB.

Quando a conta do BD Cosmos do Azure é criada, a CLI do Azure mostra informações semelhantes ao exemplo a seguir.

Observação

Este exemplo usa JSON como o formato de saída da CLI do Azure, que é o padrão. Para usar outro formato de saída, consulte Formatos de saída para comandos da CLI do Azure.

{
  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>.documents.azure.com:443/",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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"
    }
  ]
}

Recuperar a chave do banco de dados

Para se conectar ao BD Cosmos do Azure, você precisa da chave do banco de dados. Use o comando az cosmosdb keys list para recuperar a chave primária.

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

A CLI do Azure emite informações semelhantes ao seguinte exemplo.

"RUayjYjixJDWG5xTqIiXjC..."

Configurar o aplicativo

Exporte a cadeia de conexão, o banco de dados MongoDB e os nomes de coleção como variáveis de 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>@"

Observação

A opção ssl=true é importante devido aos requisitos do Azure Cosmos DB. Para obter mais informações, confira Requisitos de cadeia de conexão.

Para a variável de ambiente MONGODB_CONNECTION_STRING, substitua os espaços reservados por <COSMOSDB_ACCOUNT_NAME> e <COSMOSDB_PASSWORD>

  1. <COSMOSDB_ACCOUNT_NAME>: O nome da conta do Azure Cosmos DB que você criou
  2. <COSMOSDB_PASSWORD>: A chave do banco de dados extraída na etapa anterior
export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Você pode escolher seus valores preferenciais para MONGODB_DATABASE e MONGODB_COLLECTION ou deixá-los como estão.

Executar o aplicativo

Para criar um todo

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

Se for bem-sucedido, você verá uma saída com o _id do MongoDB do documento recém-criado:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Criar outro todo

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

Listar todos os todos

./todo --list all

Você deve examinar aqueles que acabou de adicionar em formato tabular:

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

Para atualizar o status de um todo (por exemplo, para alterá-lo para o status completed), use a ID de todo:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Listar somente os todos concluídos

./todo --list completed

Você deve ver aquele que acabou de atualizar:

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

Exibir dados no Data Explorer

Os dados armazenados no Azure Cosmos DB ficam disponíveis para exibição e consulta no portal do Azure.

Para exibir, consultar e trabalhar com os dados de usuário criados na etapa anterior, faça logon no portal do Azure no seu navegador da Web.

Na caixa Pesquisa superior, insira Azure Cosmos DB. Quando a folha de conta do Azure Cosmos DB abrir, selecione sua conta do Azure Cosmos DB. No painel de navegação esquerdo, clique em Data Explorer. Expanda a coleção no painel Coleções e, em seguida, será possível exibir os documentos na coleção, consultar os dados e até mesmo criar e executar gatilhos, UDFs e procedimentos armazenados.

Data Explorer mostrando o documento recém-criado

Excluir um todo usando sua ID:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Listar os todo a serem confirmados:

./todo --list all

O todo que você acabou de excluir não deve estar presente:

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

Limpar os recursos

Quando o aplicativo e a conta do Azure Cosmos DB estiverem prontos, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para excluir os recursos:

  1. Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.

  2. Na lista, selecione o grupo de recursos criado neste início rápido.

    Selecione o grupo de recursos a excluir

  3. Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.

    Exclua o grupo de recursos

  4. Na próxima janela, insira o nome do grupo de recursos a ser excluído e selecione Excluir.

Próximas etapas

Neste início rápido, você aprendeu a criar uma conta do Azure Cosmos DB for MongoDB usando o Azure Cloud Shell e a criar e executar um aplicativo Go de linha de comando para gerenciar todos. Agora, é possível importar outros dados para sua conta do Azure Cosmos DB.

Tentando fazer o planejamento da capacidade para uma migração para o Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.

Importar dados do MongoDB no Azure Cosmos DB