Quickstart: Ligue uma aplicação Go à API da Azure Cosmos DB para a MongoDBQuickstart: Connect a Go application to Azure Cosmos DB's API for MongoDB

APLICA A: Azure Cosmos DB API para MongoDB

Azure Cosmos DB é um serviço de base de dados multi-modelo que permite criar e consultar rapidamente documentos, tabelas, valor-chave e bases de dados de gráficos com capacidades de distribuição global e escala horizontal.Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities. Neste quickstart, você cria e gere uma conta DB Azure Cosmos usando a Azure Cloud Shell, clone uma aplicação de amostra existente do GitHub e configuure-a para trabalhar com Azure Cosmos DB.In this quickstart, you create and manage an Azure Cosmos DB account by using the Azure Cloud Shell, clone an existing sample application from GitHub and configure it to work with Azure Cosmos DB.

A aplicação da amostra é uma ferramenta de gestão baseada em linha de comando todo escrita em Go.The sample application is a command-line based todo management tool written in Go. A API da Azure Cosmos DB para a MongoDB é compatível com o protocolo de fio MongoDB,permitindo que qualquer condutor cliente da MongoDB se conecte a ele.Azure Cosmos DB's API for MongoDB is compatible with the MongoDB wire protocol, making it possible for any MongoDB client driver to connect to it. Esta aplicação utiliza o controlador Go para a MongoDB de uma forma transparente à aplicação que os dados são armazenados numa base de dados DB da Azure Cosmos.This application uses the Go driver for MongoDB in a way that is transparent to the application that the data is stored in an Azure Cosmos DB database.

Pré-requisitosPrerequisites

  • Utilize o ambiente Bash em Azure Cloud Shell.Use the Bash environment in Azure Cloud Shell.

    Iniciar Cloud Shell numa nova janelaLaunch Cloud Shell in a new window

  • Se preferir, instale o CLI do Azure para executar comandos de referência de CLI.If you prefer, install the Azure CLI to run CLI reference commands.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login.If you're using a local installation, sign in to the Azure CLI by using the az login command. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal.To finish the authentication process, follow the steps displayed in your terminal. Para obter mais opções de início de sessão, veja Iniciar sessão com o CLI do Azure.For additional sign-in options, see Sign in with the Azure CLI.

    • Quando lhe for pedido, instale as extensões do CLI do Azure durante a primeira utilização.When you're prompted, install Azure CLI extensions on first use. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.For more information about extensions, see Use extensions with the Azure CLI.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas.Run az version to find the version and dependent libraries that are installed. Para atualizar para a versão mais recente, execute o comando az upgrade.To upgrade to the latest version, run az upgrade.

Clonar a aplicação de exemploClone the sample application

Execute os seguintes comandos para clonar o repositório de exemplo.Run the following commands to clone the sample repository.

  1. Abra um pedido de comando, crie uma nova pasta chamada git-samples e, em seguida, feche o pedido de comando.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    mkdir "C:\git-samples"
    
  2. 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.Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. Execute o seguinte comando para clonar o repositório de exemplo.Run the following command to clone the sample repository. Este comando cria uma cópia da aplicação de exemplo no seu computador.This command creates a copy of the sample app on your computer.

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

Rever o códigoReview the code

Este passo é opcional.This step is optional. Se estiver interessado em saber como funciona a aplicação, pode rever os seguintes excertos.If you're interested in learning how the application works, you can review the following snippets. Caso contrário, pode adiantar-se para executar a aplicação.Otherwise, you can skip ahead to Run the application. O layout da aplicação é o seguinte:The application layout is as follows:

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

Os seguintes fragmentos foram todos retirados do ficheiro todo.go.The following snippets are all taken from the todo.go file.

Ligar a aplicação Go ao Azure Cosmos DBConnecting the Go app to Azure Cosmos DB

clientOptions encapsula a cadeia de ligação para Azure Cosmos DB, que é passada usando uma variável ambiental (detalhes na secção seguinte).clientOptions encapsulates the connection string for Azure Cosmos DB, which is passed in using an environment variable (details in the upcoming section). A ligação é inicializada utilizando mongo.NewClient a qual a instância é clientOptions passada.The connection is initialized using mongo.NewClient to which the clientOptions instance is passed. Ping a função é invocada para confirmar a conectividade bem sucedida (é uma estratégia de falha-rápido)Ping function is invoked to confirm successful connectivity (it is a fail-fast strategy)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
    defer cancel()

    clientOptions := options.Client().ApplyURI(mongoDBConnectionString).SetDirect(true)
    
    c, err := mongo.NewClient(clientOptions)
    err = c.Connect(ctx)
    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

A SetDirect(true) utilização da configuração é importante, sem a qual obterá o seguinte erro de conectividade: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closedUsing the SetDirect(true) configuration is important, without which you will get the following connectivity error: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed

Criar um todo itemCreate a todo item

Para criar um todo , temos uma pega para um mongo.Collection e invocamos a InsertOne função.To create a todo, we get a handle to a mongo.Collection and invoke the InsertOne function.

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 por uma Todo estrutura que contém a descrição e o estado (que está inicialmente definido pending para)We pass in a Todo struct that contains the description and the status (which is initially set to pending)

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

Listar todo itensList todo items

Podemos listar TODOs com base em critérios.We can list TODOs based on criteria. A bson.D é criado para encapsular os critérios do filtroA bson.D is created to encapsulate the filter criteria

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 procurar documentos com base no filtro e o resultado é convertido em uma fatia de TodoFind is used to search for documents based on the filter and the result is converted into a slice of 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, a informação é prestada em formato tabularFinally, the information is rendered in tabular format

    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 itemUpdate a todo item

A todo pode ser atualizado com base na sua _id .A todo can be updated based on its _id. Um bson.D filtro é criado com base no e outro é criado para a _id informação atualizada, que é um novo estado completed (ou ) neste pending caso.A bson.D filter is created based on the _id and another one is created for the updated information, which is a new status (completed or pending) in this case. Finalmente, a UpdateOne função é invocada com o filtro e o documento atualizadoFinally, the UpdateOne function is invoked with the filter and the updated document

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

Eliminar a todoDelete a todo

A todo é eliminada com base na sua e é _id encapsulada sob a forma de um bson.D exemplo.A todo is deleted based on its _id and it is encapsulated in the form of a bson.D instance. DeleteOne é invocado para apagar o documento.DeleteOne is invoked to delete the document.

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çãoBuild the application

Mude para o diretório onde clonou a aplicação e a construa go build (usando).Change into the directory where you cloned the application and build it (using go build).

cd monogdb-go-quickstart
go build -o todo

Para confirmar que a aplicação foi construída corretamente.To confirm that the application was built properly.

./todo --help

Configuração Azure Cosmos DBSetup Azure Cosmos DB

Iniciar sessão no AzureSign in to Azure

Se optar por instalar e usar a CLI localmente, este tópico requer a execução da versão 2.0 ou posterior da CLI do Azure.If you choose to install and use the CLI locally, this topic requires that you are running the Azure CLI version 2.0 or later. Executar az --version para localizar a versão.Run az --version to find the version. Se precisar de instalar ou atualizar, consulte [Instalar Azure CLI].If you need to install or upgrade, see [Install Azure CLI].

Se estiver a utilizar um Azure CLI instalado, inicie sessão na sua subscrição Azure com o comando de login az e siga as instruções no ecrã.If you are using an installed Azure CLI, sign in to your Azure subscription with the az login command and follow the on-screen directions. Pode ignorar esta etapa se estiver a utilizar o Azure Cloud Shell.You can skip this step if you're using the Azure Cloud Shell.

az login 

Adicionar o módulo Azure Cosmos DBAdd the Azure Cosmos DB module

Se estiver a utilizar uma CLI do Azure instalada, veja se o componente cosmosdb já está instalado ao executar o comando az.If you are using an installed Azure CLI, check to see if the cosmosdb component is already installed by running the az command. Se cosmosdb está na lista de comandos de base, siga para o próximo comando.If cosmosdb is in the list of base commands, proceed to the next command. Pode ignorar esta etapa se estiver a utilizar o Azure Cloud Shell.You can skip this step if you're using the Azure Cloud Shell.

Se cosmosdb não estiver na lista de comandos de base, reinstale a CLI do Azure.If cosmosdb is not in the list of base commands, reinstall Azure CLI.

Criar um grupo de recursosCreate a resource group

Criar um grupo de recursos com o grupo az criar.Create a resource group with the az group create. Um grupo de recursos do Azure é um contentor lógico no qual os recursos do Azure, como aplicações Web, bases de dados e contas de armazenamento, são implementados e geridos.An Azure resource group is a logical container into which Azure resources like web apps, databases and storage accounts are deployed and managed.

O exemplo seguinte cria um grupo de recursos na região Europa Ocidental.The following example creates a resource group in the West Europe region. Escolha um nome exclusivo para o grupo de recursos.Choose a unique name for the resource group.

Se estiver a utilizar o Azure Cloud Shell, selecione Try It, siga as instruções no ecrã para iniciar sessão e, em seguida, copie o comando para a solicitação de comando.If you are using Azure Cloud Shell, select Try It, follow the onscreen prompts to login, then copy the command into the command prompt.

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

Criar uma conta do Azure Cosmos DBCreate an Azure Cosmos DB account

Crie uma conta Cosmos com o cosmosdb az criar comando.Create a Cosmos account with the az cosmosdb create command.

No seguinte comando, substitua o seu próprio nome exclusivo da conta Cosmos onde vê o <cosmosdb-name> espaço reservado.In the following command, please substitute your own unique Cosmos account name where you see the <cosmosdb-name> placeholder. Este nome único será usado como parte do seu ponto final cosmos DB ( https://<cosmosdb-name>.documents.azure.com/ ), por isso o nome precisa ser único em todas as contas cosmos em Azure.This unique name will be used as part of your Cosmos DB endpoint (https://<cosmosdb-name>.documents.azure.com/), so the name needs to be unique across all Cosmos accounts in Azure.

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

O parâmetro --kind MongoDB permite ligações de cliente da MongoDB.The --kind MongoDB parameter enables MongoDB client connections.

Após criar a conta do DB Cosmos Azure, a CLI do Azure mostra informações semelhantes ao exemplo seguinte.When the Azure Cosmos DB account is created, the Azure CLI shows information similar to the following example.

Nota

Este exemplo utiliza o JSON como formato de saída da CLI do Azure, que é a predefinição.This example uses JSON as the Azure CLI output format, which is the default. Para utilizar outro formato de saída, veja Formatos de saída para os comandos da CLI do Azure.To use another output format, see Output formats for Azure CLI commands.

{
  "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 dadosRetrieve the database key

Para se ligar a uma base de dados cosmos, precisa da chave de base de dados.In order to connect to a Cosmos database, you need the database key. Use o comando da lista de chaves az cosmosdb para recuperar a chave primária.Use the az cosmosdb keys list command to retrieve the primary key.

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

A CLI do Azure apresenta informações semelhantes ao exemplo seguinte.The Azure CLI outputs information similar to the following example.

"RUayjYjixJDWG5xTqIiXjC..."

Configurar a aplicaçãoConfigure the application

Exporte a cadeia de ligação, a base de dados mongoDB e os nomes de recolha como variáveis ambientais.Export the connection string, MongoDB database and collection names as environment variables.

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 da Cosmos DB.The ssl=true option is important because of Cosmos DB requirements. Para obter mais informações, consulte os requisitos de cadeia de ligação.For more information, see Connection string requirements.

Para a MONGODB_CONNECTION_STRING variável ambiente, substitua os espaços reservados <COSMOSDB_ACCOUNT_NAME> para e <COSMOSDB_PASSWORD>For the MONGODB_CONNECTION_STRING environment variable, replace the placeholders for <COSMOSDB_ACCOUNT_NAME> and <COSMOSDB_PASSWORD>

  1. <COSMOSDB_ACCOUNT_NAME>: O nome da conta DB Azure Cosmos que criou<COSMOSDB_ACCOUNT_NAME>: The name of the Azure Cosmos DB account you created
  2. <COSMOSDB_PASSWORD>: A chave da base de dados extraída no passo anterior<COSMOSDB_PASSWORD>: The database key extracted in the previous step
export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Pode escolher os seus valores preferidos MONGODB_DATABASE para e MONGODB_COLLECTION ou deixá-los como está.You can choose your preferred values for MONGODB_DATABASE and MONGODB_COLLECTION or leave them as is.

Executar a aplicaçãoRun the application

Para criar uma todoTo create a todo

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

Se for bem sucedido, deverá ver uma saída com o MongoDB _id do documento recém-criado:If successful, you should see an output with the MongoDB _id of the newly created document:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Criar outro todoCreate another todo

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

Listar todos os todo sList all the todos

./todo --list all

Você deve ver os que acabou de adicionar em um formato tabular como talYou should see the ones you just added in a tabular format as such

+----------------------------+--------------------------------+-----------+
|             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 estado de um todo (por exemplo, alterá-lo para completed estado), utilize o todo IDTo update the status of a todo (e.g. change it to completed status), use the todo ID

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Listar apenas os todo s completosList only the completed todos

./todo --list completed

Devia ver o que acabou de atualizar.You should see the one you just updated

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

Ver dados no Data ExplorerView data in Data Explorer

Os dados armazenados no Azure Cosmos DB estão disponíveis para visualização e consulta no portal Azure.Data stored in Azure Cosmos DB is available to view and query in the Azure portal.

Para ver, consultar e trabalhar com os dados do utilizador criados no passo anterior, inicie a sessão no portal do Azure no browser.To view, query, and work with the user data created in the previous step, login to the Azure portal in your web browser.

Na caixa de pesquisa superior, insira Azure Cosmos DB.In the top Search box, enter Azure Cosmos DB. Quando a sua folha de conta Cosmos abrir, selecione a sua conta Cosmos.When your Cosmos account blade opens, select your Cosmos account. Na navegação à esquerda, selecione Data Explorer.In the left navigation, select 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.Expand your collection in the Collections pane, and then you can view the documents in the collection, query the data, and even create and run stored procedures, triggers, and UDFs.

O Data Explorer a mostrar o documento recentemente criado

Excluir um todo uso é IDDelete a todo using it's ID

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Listar os todo s para confirmarList the todos to confirm

./todo --list all

O todo que acabou de apagar não deve estar presente.The todo you just deleted should not be present

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

Limpar os recursosClean up resources

Quando terminar a sua app e a conta DB da Azure Cosmos, pode apagar os recursos Azure que criou para não incorrer em mais encargos.When you're done with your app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para eliminar os recursos:To delete the resources:

  1. Na barra de pesquisa do portal Azure, procure e selecione grupos de Recursos.In the Azure portal Search bar, search for and select Resource groups.

  2. A partir da lista, selecione o grupo de recursos que criou para este arranque rápido.From the list, select the resource group you created for this quickstart.

    Selecione o grupo de recursos para eliminar

  3. Na página de visão geral do grupo de recursos, selecione Eliminar o grupo de recursos.On the resource group Overview page, select Delete resource group.

    Eliminar o grupo de recursos

  4. Na janela seguinte, insira o nome do grupo de recursos para eliminar e, em seguida, selecione Delete.In the next window, enter the name of the resource group to delete, and then select Delete.

Passos seguintesNext steps

Neste quickstart, aprendeu a criar uma conta API Azure Cosmos DB MongoDB usando a Azure Cloud Shell, e criar e executar uma aplicação de linha de comando Go para gerir todo s.In this quickstart, you learned how to create an Azure Cosmos DB MongoDB API account using the Azure Cloud Shell, and create and run a Go command-line app to manage todos. Agora, pode importar dados adicionais para a sua conta do Azure Cosmos DB.You can now import additional data to your Azure Cosmos DB account.