Inicio rápido: Conexión de una aplicación Go a la API de Azure Cosmos DB para MongoDBQuickstart: Connect a Go application to Azure Cosmos DB's API for MongoDB

Azure Cosmos DB es un servicio de base de datos multimodelo que permite crear y consultar rápidamente bases de datos de documentos, tablas, claves-valores y grafos con funcionalidades de distribución global y 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. En este inicio rápido, se va a crear y administrar una cuenta de Azure Cosmos DB mediante Azure Cloud Shell, se va a clonar una aplicación de ejemplo existente desde GitHub y se va a configurar esta para que funcione con 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.

La aplicación de ejemplo es una herramienta de administración todo de línea de comandos escrita en Go.The sample application is a command-line based todo management tool written in Go. La API de Azure Cosmos DB para MongoDB es compatible con el protocolo de conexión de MongoDB, lo que permite que cualquier controlador cliente de MongoDB se conecte a ella.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 aplicación usa el controlador de Go para MongoDB de una manera transparente, de forma que sabe que los datos se almacenan en una base de datos de Azure Cosmos DB.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.

Requisitos previosPrerequisites

Uso de Azure Cloud ShellUse Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador.Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure.You can use either Bash or PowerShell with Cloud Shell to work with Azure services. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

Para iniciar Azure Cloud Shell:To start Azure Cloud Shell:

OpciónOption Ejemplo o vínculoExample/Link
Seleccione Pruébelo en la esquina superior derecha de un bloque de código.Select Try It in the upper-right corner of a code block. Solo con seleccionar Pruébelo no se copia automáticamente el código en Cloud Shell.Selecting Try It doesn't automatically copy the code to Cloud Shell. Ejemplo de Probarlo para Azure Cloud Shell
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Iniciar Cloud Shell en una nueva ventanaLaunch Cloud Shell in a new window
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Botón Cloud Shell en Azure Portal

Para ejecutar el código de este artículo en Azure Cloud Shell:To run the code in this article in Azure Cloud Shell:

  1. Inicie Cloud Shell.Start Cloud Shell.

  2. Seleccione el botón Copiar de un bloque de código para copiar el código.Select the Copy button on a code block to copy the code.

  3. Pegue el código en la sesión de Cloud Shell. Para ello, seleccione Ctrl+Mayús+V en Windows y Linux, o bien seleccione Cmd+Mayús+V en macOS.Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Seleccione Entrar para ejecutar el código.Select Enter to run the code.

Clonación de la aplicación de ejemploClone the sample application

Ejecute los comandos siguientes para clonar el repositorio de ejemplo.Run the following commands to clone the sample repository.

  1. Abra un símbolo del sistema, cree una carpeta denominada git-samples y, después, cierre el símbolo del sistema.Open a command prompt, create a new folder named git-samples, then close the command prompt.

    mkdir "C:\git-samples"
    
  2. Abra una ventana de terminal de Git, como git bash y utilice el comando cd para cambiar a la nueva carpeta para instalar la aplicación de ejemplo.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. Ejecute el comando siguiente para clonar el repositorio de ejemplo.Run the following command to clone the sample repository. Este comando crea una copia de la aplicación de ejemplo en el equipo.This command creates a copy of the sample app on your computer.

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

Revisión del códigoReview the code

Este paso es opcional.This step is optional. Si le interesa saber cómo funciona la aplicación, puede revisar los siguientes fragmentos de código.If you're interested in learning how the application works, you can review the following snippets. En caso contrario, puede ir directamente a Ejecutar la aplicación.Otherwise, you can skip ahead to Run the application. El diseño de la aplicación es el siguiente:The application layout is as follows:

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

Los fragmentos de código siguientes se han tomado del archivo todo.go.The following snippets are all taken from the todo.go file.

Conexión de una aplicación Go a Azure Cosmos DBConnecting the Go app to Azure Cosmos DB

clientOptions encapsula la cadena de conexión de Azure Cosmos DB, que se pasa mediante una variable de entorno (se pueden encontrar los detalles en la próxima sección).clientOptions encapsulates the connection string for Azure Cosmos DB, which is passed in using an environment variable (details in the upcoming section). La conexión se inicializa mediante mongo.NewClient al que se pasa la instancia clientOptions.The connection is initialized using mongo.NewClient to which the clientOptions instance is passed. Se invoca la función Ping para confirmar que la conectividad es correcta (es una estrategia con respuesta rápida a errores).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

El uso de la configuración de SetDirect(true) es importante, ya que sin ella obtendrá el siguiente error de conectividad: unable to connect connection(cdb-ms-prod-<azure-region>-cm1.documents.azure.com:10255[-4]) connection is closed.Using 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

Creación de un elemento todoCreate a todo item

Para crear un elemento todo, se obtiene un identificador para mongo.Collection y se invoca la función InsertOne.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)
    }

Se pasa un struct Todo que contiene la descripción y el estado (que se establece inicialmente en pending).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"`
}

Enumeración de elementos todoList todo items

Se pueden enumerar los elementos TODO según unos criterios.We can list TODOs based on criteria. Se crea un objeto bson.D para encapsular los criterios de filtro.A 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)")
    }

Se usa Find para buscar documentos según el filtro y el resultado se convierte en un sector 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)
    }

Por último, la información se representa en formato tabular.Finally, 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()

Actualización de un elemento todoUpdate a todo item

Un elemento todo se puede actualizar en función de su valor de _id.A todo can be updated based on its _id. Se crea un filtro bson.D basado en el valor de _id y otro para la información actualizada, que tiene un nuevo estado (completed o pending) en este 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. Por último, se invoca la función UpdateOne con el filtro y el documento actualizado.Finally, 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)
    }

Eliminación de un elemento todoDelete a todo

Un elemento todo se elimina según su valor de _id y se encapsula en forma de una instancia bson.D.A todo is deleted based on its _id and it is encapsulated in the form of a bson.D instance. Se invoca a DeleteOne para eliminar el 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)
    }
}

Compilar la aplicaciónBuild the application

Cambie al directorio en el que ha clonado la aplicación y compílela (mediante go build).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 la aplicación se compiló correctamente:To confirm that the application was built properly.

./todo --help

Configuración de Azure Cosmos DBSetup Azure Cosmos DB

Inicio de sesión en AzureSign in to Azure

Si decide instalar y usar la CLI localmente, para este tema es preciso que ejecute la CLI de Azure versión 2.0 o posterior.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. Ejecute az --version para encontrar la versión.Run az --version to find the version. Si necesita instalarla o actualizarla, consulte [Instalación de la CLI de Azure].If you need to install or upgrade, see [Install Azure CLI].

Si usa una CLI de Azure instalada, inicie sesión en la suscripción de Azure con el comando az login y siga las instrucciones de la pantalla.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. Puede omitir este paso si usa Azure Cloud Shell.You can skip this step if you're using the Azure Cloud Shell.

az login 

Agregar el módulo de Azure Cosmos DBAdd the Azure Cosmos DB module

Si va a usar una CLI de Azure instalada, ejecute el comando az para comprobar si el componente cosmosdb ya está instalado.If you are using an installed Azure CLI, check to see if the cosmosdb component is already installed by running the az command. Si cosmosdb está en la lista de comandos de referencia, continúe con el comando siguiente.If cosmosdb is in the list of base commands, proceed to the next command. Puede omitir este paso si usa Azure Cloud Shell.You can skip this step if you're using the Azure Cloud Shell.

Si cosmosdb no está en la lista de comandos de referencia, vuelva a instalar la CLI de Azure.If cosmosdb is not in the list of base commands, reinstall Azure CLI.

Crear un grupo de recursosCreate a resource group

Cree un grupo de recursos con el comando az group create.Create a resource group with the az group create. Un grupo de recursos de Azure es un contenedor lógico en el que se implementan y se administran recursos de Azure como aplicaciones web, bases de datos y cuentas de almacenamiento.An Azure resource group is a logical container into which Azure resources like web apps, databases and storage accounts are deployed and managed.

En el ejemplo siguiente se crea un grupo de recursos en la región de Oeste de Europa.The following example creates a resource group in the West Europe region. Elija un nombre único para el grupo de recursos.Choose a unique name for the resource group.

Si usa Azure Cloud Shell, seleccione Probarlo, siga las indicaciones de la pantalla para iniciar sesión y, a continuación, copie el comando en el símbolo del sistema.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"

Creación de una cuenta de Azure Cosmos DBCreate an Azure Cosmos DB account

Cree una cuenta de Cosmos con el comando az cosmosdb create.Create a Cosmos account with the az cosmosdb create command.

En el comando siguiente, sustituya su propio nombre único de la cuenta de Cosmos donde vea el marcador de posición <cosmosdb-name>.In the following command, please substitute your own unique Cosmos account name where you see the <cosmosdb-name> placeholder. Este nombre único se usará como parte del punto de conexión de Cosmos DB (https://<cosmosdb-name>.documents.azure.com/), por lo que debe ser único entre todas las cuentas de Cosmos de 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

El parámetro --kind MongoDB habilita las conexiones de cliente de MongoDB.The --kind MongoDB parameter enables MongoDB client connections.

Cuando se crea la cuenta de Azure Cosmos DB, la CLI de Azure muestra información similar a la del ejemplo siguiente.When the Azure Cosmos DB account is created, the Azure CLI shows information similar to the following example.

Nota

Este ejemplo usa JSON como el formato de salida de la CLI de Azure, que es el valor predeterminado.This example uses JSON as the Azure CLI output format, which is the default. Para usar otro formato de salida, consulte Formatos de salida para los comandos de la CLI de 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"
    }
  ]
} 

Recuperación de la clave de base de datosRetrieve the database key

Para conectarse a una base de datos de Cosmos, necesita la clave de base de datos.In order to connect to a Cosmos database, you need the database key. Use el comando az cosmosdb keys list para recuperar la clave principal.Use the az cosmosdb keys list command to retrieve the primary key.

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

La CLI de Azure genera información similar a la del ejemplo siguiente.The Azure CLI outputs information similar to the following example.

"RUayjYjixJDWG5xTqIiXjC..."

Configuración de la aplicaciónConfigure the application

Exporte la cadena de conexión, la base de datos de MongoDB y los nombres de colección como variables de entorno.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>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&maxIdleTimeMS=120000&appName=@<COSMOSDB_ACCOUNT_NAME>@"

Nota

La opción ssl=true es importante debido a los requisitos de Cosmos DB.The ssl=true option is important because of Cosmos DB requirements. Para más información, consulte Requisitos de la cadena de conexión.For more information, see Connection string requirements.

En la variable de entorno MONGODB_CONNECTION_STRING, reemplace los marcadores de posición de <COSMOSDB_ACCOUNT_NAME> y <COSMOSDB_PASSWORD>.For the MONGODB_CONNECTION_STRING environment variable, replace the placeholders for <COSMOSDB_ACCOUNT_NAME> and <COSMOSDB_PASSWORD>

  1. <COSMOSDB_ACCOUNT_NAME>: el nombre de la cuenta de Azure Cosmos DB que ha creado.<COSMOSDB_ACCOUNT_NAME>: The name of the Azure Cosmos DB account you created
  2. <COSMOSDB_PASSWORD>: la clave de base de datos extraída en el paso anterior.<COSMOSDB_PASSWORD>: The database key extracted in the previous step
export MONGODB_DATABASE=todo-db
export MONGODB_COLLECTION=todos

Puede elegir los valores que prefiera para MONGODB_DATABASE y MONGODB_COLLECTION o dejarlos como están.You can choose your preferred values for MONGODB_DATABASE and MONGODB_COLLECTION or leave them as is.

Ejecución de la aplicaciónRun the application

Para crear un elemento todo:To create a todo

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

Si la operación es correcta, verá una salida con el valor de _id de MongoDB del documento recién creado:If successful, you should see an output with the MongoDB _id of the newly created document:

added todo ObjectID("5e9fd6befd2f076d1f03bd8a")

Creación de otro elemento todo:Create another todo

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

Enumeración de todos los elementos todo:List all the todos

./todo --list all

Verá los que acaba de agregar en formato tabular:You 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 actualizar el estado de un elemento todo (por ejemplo, cambiarlo al estado completed), use el identificador de todo:To update the status of a todo (e.g. change it to completed status), use the todo ID

./todo --update 5e9fd6b1bcd2fa6bd267d4c4,completed

Enumeración de solo los elementos todo completados:List only the completed todos

./todo --list completed

Verá el que acaba de actualizar:You should see the one you just updated

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

Ver datos en el Explorador de datosView data in Data Explorer

Los datos almacenados en una instancia de Azure Cosmos DB se pueden ver y consultar en Azure Portal.Data stored in Azure Cosmos DB is available to view and query in the Azure portal.

Para ver y consultar los datos de usuario creados en el paso anterior y trabajar con ellos, inicie sesión en Azure Portal en el explorador web.To view, query, and work with the user data created in the previous step, login to the Azure portal in your web browser.

En el cuadro de búsqueda superior, escriba Azure Cosmos DB.In the top Search box, enter Azure Cosmos DB. Cuando se abra la hoja de la cuenta de Cosmos, seleccione su cuenta de Cosmos.When your Cosmos account blade opens, select your Cosmos account. En el panel de navegación izquierdo, seleccione Explorador de datos.In the left navigation, select Data Explorer. Expanda la colección en el panel Colecciones. Ahora puede ver los documentos de la colección, consultar los datos e incluso crear y ejecutar procedimientos almacenados, desencadenadores y UDF.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.

El Explorador de datos muestra el documento recién creado

Eliminación de un elemento todo mediante su identificador:Delete a todo using it's ID

./todo --delete 5e9fd6b1bcd2fa6bd267d4c4,completed

Enumeración de los elementos todo que se van a confirmar:List the todos to confirm

./todo --list all

El elemento todo que acaba de eliminar no debe 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     |           |
+----------------------------+--------------------------------+-----------+

Limpieza de recursosClean up resources

Cuando haya terminado tanto con la aplicación como con la cuenta de Azure Cosmos DB, puede eliminar los recursos de Azure que creó para no tener más gastos.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 los recursos:To delete the resources:

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.In the Azure portal Search bar, search for and select Resource groups.

  2. En la lista, seleccione el grupo de recursos que creó para este inicio rápido.From the list, select the resource group you created for this quickstart.

    Selección del grupo de recursos que se eliminará

  3. En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.On the resource group Overview page, select Delete resource group.

    Eliminar el grupo de recursos

  4. En la ventana siguiente, escriba el nombre del grupo de recursos que desea eliminar y, después, seleccione Eliminar.In the next window, enter the name of the resource group to delete, and then select Delete.

Pasos siguientesNext steps

En este inicio rápido, ha aprendido a crear una cuenta de la API de Azure Cosmos DB para MongoDB mediante Azure Cloud Shell, y a crear y ejecutar una aplicación Go de línea de comandos para administrar elementos todo.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. Ahora puede importar datos adicionales en la cuenta de Azure Cosmos DB.You can now import additional data to your Azure Cosmos DB account.