Guia de início rápido: conectar um aplicativo Go ao Azure Cosmos DB para MongoDB

Artigo
04/19/2024

APLICA-SE A: 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, chave-valor e gráficos com recursos de distribuição global e escala horizontal. 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 o configura para funcionar com o Azure Cosmos DB.

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

Pré-requisitos

Uma conta do Azure com uma subscrição ativa. Crie um gratuitamente. Ou experimente o Azure Cosmos DB gratuitamente sem uma assinatura do Azure. Você também pode usar o emulador do Azure Cosmos DB com a cadeia de conexão .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Go instalado no seu computador, e um conhecimento prático de Go.
Git.

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Clonar a aplicação de exemplo

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

Abra um prompt de comando, crie uma nova pasta chamada git-samplese, em seguida, feche o prompt de comando.
```
mkdir "C:\git-samples"
```
Abra uma janela de terminal do git, como o git bash e utilize o comando cd para alterar para uma nova pasta e instalar a aplicação de exemplo.
```
cd "C:\git-samples"
```
Execute o seguinte comando para clonar o repositório de exemplo. Este comando cria uma cópia da aplicação de exemplo no seu computador.
```
git clone https://github.com/Azure-Samples/cosmosdb-go-mongodb-quickstart
```

Rever o código

Este passo é opcional. Se estiver interessado em saber como funciona a aplicação, pode rever os seguintes excertos. Caso contrário, você pode pular para Executar o aplicativo. O layout do aplicativo é o seguinte:

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

Os seguintes fragmentos foram todos retirados do ficheiro todo.go.

Ligar a aplicação Go ao Azure Cosmos DB

clientOptions encapsula a cadeia de conexão do Azure Cosmos DB, que é passada usando uma variável de ambiente (detalhes na próxima seção). A conexão é inicializada usando mongo.NewClient a qual a clientOptions instância é passada. Ping função é invocada para confirmar a conectividade bem-sucedida (é 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)
    }

Nota

Usar a configuração é importante, sem o SetDirect(true) qual você obterá 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 `todo` item

Para criar um todo, obtemos um identificador para um mongo.Collection e invocamos a InsertOne função.

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 em um Todo struct que contém a descrição e o status (que é inicialmente definido como pending):

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

Lista `todo` de itens

Podemos listar TODOs com base em critérios. A 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 é utilizado para procurar documentos com base no filtro e o resultado é convertido numa 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)
    }

Finalmente, as informações são processadas 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 `todo` item

A todo pode ser atualizado com base no seu _id. Um bson.D filtro é criado com base no _id e outro é criado para as informações atualizadas, que é um novo status (completed ou pending) neste caso. Finalmente, a UpdateOne função é 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`

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

Criar a aplicação

Mude para o diretório onde você clonou o aplicativo e compile-o (usando go build).

cd monogdb-go-quickstart
go build -o todo

Para confirmar que o aplicativo foi criado corretamente.

./todo --help

Configurar o Azure Cosmos DB

Se você optar por instalar e usar a CLI localmente, este tópico exigirá que você esteja executando a CLI do Azure versão 2.0 ou posterior. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, consulte [Instalar a CLI do Azure].

Se estiver a utilizar uma CLI do Azure instalada, inicie sessão na sua subscrição do Azure com o comando az login e siga as instruções no ecrã. Pode ignorar esta etapa se estiver a utilizar o Azure Cloud Shell.

az login

Adicionar o módulo Azure Cosmos DB

Se você estiver usando uma CLI do Azure instalada, verifique se o cosmosdb componente já está instalado executando o az comando. Se cosmosdb está na lista de comandos de base, siga para o próximo comando. Pode ignorar esta etapa se estiver a utilizar 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 Web, bancos de dados e contas de armazenamento, são implantados e gerenciados.

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

Se estiver a utilizar o Azure Cloud Shell, selecione Experimentar, siga as instruções no ecrã para iniciar sessão e, em seguida, copie o comando para a linha de comandos.

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

Criar uma conta do Azure Cosmos DB

Crie uma conta do Azure Cosmos DB com o comando az cosmosdb create.

No comando seguinte, substitua o nome exclusivo da conta do Azure Cosmos DB, quando vir o marcador de posição <cosmosdb-name>. Este nome exclusivo será utilizado como parte do ponto final do Azure Cosmos DB (https://<cosmosdb-name>.documents.azure.com/). Por isso, o nome tem de ser exclusivo em todas as contas do Azure Cosmos DB.

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

O parâmetro --kind MongoDB permite ligações de cliente da MongoDB.

Após criar a conta do DB Cosmos Azure, a CLI do Azure mostra informações semelhantes ao exemplo seguinte.

Nota

Este exemplo utiliza o JSON como formato de saída da CLI do Azure, que é a predefinição. Para utilizar outro formato de saída, veja Formatos de saída para os comandos da CLI do Azure.

{
  "databaseAccountOfferType": "Standard",
  "documentEndpoint": "https://<cosmosdb-name>.documents.azure.com:443/",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/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"
    }
  ]
}

Obter a chave de base de dados

Para ligar a uma base de dados do DB Cosmos Azure , precisará da chave da base 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 apresenta informações semelhantes ao exemplo seguinte.

"RUayjYjixJDWG5xTqIiXjC..."

Configurar a aplicação

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>@"

Nota

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

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

<COSMOSDB_ACCOUNT_NAME>: O nome da conta do Azure Cosmos DB que você criou
<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 preferidos para MONGODB_DATABASE e MONGODB_COLLECTION ou deixá-los como estão.

Executar a aplicação

Para criar um todo

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

Se for bem-sucedido, você verá uma saída com o MongoDB _id 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 ver os que você acabou de adicionar em um formato tabular como tal:

+----------------------------+--------------------------------+-----------+
|             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, alterá-lo para completed status), use o todo ID:

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Listar apenas os s preenchidos todo

./todo --list completed

Você deve ver o que você acabou de atualizar:

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

Ver dados no Data Explorer

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

Para ver, consultar e trabalhar com os dados do utilizador criados no passo anterior, inicie a sessão no portal do Azure no browser.

Na caixa Pesquisa superior, digite Azure Cosmos DB. Quando a folha da conta do Azure Cosmos DB abrir, selecione sua conta do Azure Cosmos DB. Na navegação à esquerda, selecione Data Explorer. Expanda a coleção no painel Coleções e, em seguida, pode ver os documentos na coleção, consultar os dados e, ainda, criar e executar UDFs, acionadores e procedimentos armazenados.

O Data Explorer a mostrar o documento recentemente criado

Exclua um todo usando seu ID:

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Liste os todos a confirmar:

./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     |           |
+----------------------------+--------------------------------+-----------+

Clean up resources (Limpar recursos)

Quando terminar de usar seu aplicativo e sua conta do Azure Cosmos DB, você poderá excluir os recursos do Azure criados para não incorrer em mais cobranças. Para eliminar os recursos:

Na barra de Pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos que você criou para este início rápido.
Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.
Na janela seguinte, introduza o nome do grupo de recursos a eliminar e, em seguida, selecione Eliminar.

Próximos passos

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

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

Se tudo o que você sabe é o número de vcores e servidores em seu cluster de banco de dados existente, leia sobre como estimar unidades de solicitação usando vCores ou vCPUs
Se você souber as taxas de solicitação típicas para sua carga de trabalho de banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB

Importar dados da MongoDB para o Azure Cosmos DB

Guia de início rápido: conectar um aplicativo Go ao Azure Cosmos DB para MongoDB

Pré-requisitos

Clonar a aplicação de exemplo

Rever o código

Ligar a aplicação Go ao Azure Cosmos DB

Criar um todo item

Lista todo de itens

Atualizar um todo item

Excluir um todo

Criar a aplicação

Configurar o Azure Cosmos DB

Iniciar sessão no Azure

Adicionar o módulo Azure Cosmos DB

Criar um grupo de recursos

Criar uma conta do Azure Cosmos DB

Obter a chave de base de dados

Configurar a aplicação

Exporte a cadeia de conexão, o banco de dados MongoDB e os nomes de coleção como variáveis de ambiente.

Executar a aplicação

Ver dados no Data Explorer

Clean up resources (Limpar recursos)

Próximos passos

Recursos adicionais

Criar um `todo` item

Lista `todo` de itens

Atualizar um `todo` item

Excluir um `todo`