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

Artigo
03/29/2023

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

Uma conta do Azure com uma assinatura ativa. Crie um gratuitamente. Ou então experimente o Azure Cosmos DB gratuitamente sem uma assinatura do Azure. Use também o Emulador do Azure Cosmos DB com a cadeia de conexão .mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true.
Ter Go instalado em seu computador e ter conhecimentos práticos de Go.
Git.

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Clonar o aplicativo de exemplo

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

Abra um prompt de comando, crie uma pasta chamada git-samples e, em seguida, feche o prompt de comando.
```
mkdir "C:\git-samples"
```
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"
```
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

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/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"
    }
  ]
}

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>

<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 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:

Na barra de pesquisa do portal do Azure, procure e selecione Grupos de recursos.
Na lista, selecione o grupo de recursos criado neste início rápido.
Na página Visão geral do grupo de recursos, selecione Excluir grupo de recursos.
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.

Se você sabe apenas o número de vCores e servidores no cluster de banco de dados existente, leia sobre como estimar unidades de solicitação com vCores ou vCPUs
Se souber as taxas de solicitação típicas da carga de trabalho do banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB

Importar dados do MongoDB no Azure Cosmos DB

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

Pré-requisitos

Clonar o aplicativo de exemplo

Examine o código

Conectando o aplicativo Go para o BD Cosmos do Azure

Criar um item de todo

Listar itens de todo

Atualizar um item de todo

Excluir um todo

Compilar o aplicativo

Configurar o Azure Cosmos DB

Entrar no Azure

Adicione o módulo do BD Cosmos do Azure

Criar um grupo de recursos

Criar uma conta do Azure Cosmos DB

Recuperar a chave do banco de dados

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.

Executar o aplicativo

Exibir dados no Data Explorer

Limpar os recursos

Próximas etapas

Recursos adicionais

Criar um item de `todo`

Listar itens de `todo`

Atualizar um item de `todo`

Excluir um `todo`