Inicio rápido: Creación de una API web de .NET mediante la API de Azure Cosmos DB para MongoDB

  • Artículo
  • 9 minutos para leer

SE APLICA A: Azure Cosmos DB API para MongoDB

En esta guía de inicio rápido, se muestra cómo:

  1. Crear una cuenta de la API de Azure Cosmos DB para MongoDB
  2. Crear una API web de catálogo de productos con el controlador de .NET de MongoDB
  3. Importar datos de ejemplo

Requisitos previos para ejecutar la aplicación de ejemplo

Si no tiene Visual Studio, descargue Visual Studio 2019 Community Edition con la carga de trabajo ASP.NET y desarrollo web instalada con el programa de instalación.

Creación de una cuenta de base de datos

  1. En una nueva ventana del explorador, inicie sesión en Azure Portal.

  2. En el menú de la izquierda, seleccione Crear un recurso.

    Captura de pantalla de creación de un recurso en Azure Portal.

  3. En la página Nuevo, seleccione Bases de datos > Azure Cosmos DB.

    Captura de pantalla del de las bases de datos de Azure Portal

  4. En la págin Seleccionar opción de API, seleccione Azure Cosmos DB API para MongoDB > Crear.

    La API determina el tipo de cuenta que se va a crear. Seleccione Azure Cosmos DB API para Mongo DB, ya que va a crear una colección que funciona con MongoDB en este inicio rápido. Para más información, consulte Introducción a Azure Cosmos DB API para MongoDB.

    Captura de pantalla del panel de selección de la opción de API.

  5. En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB.

    Configuración Value Descripción
    Suscripción Nombre de suscripción Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.
    Grupo de recursos Definición de un nombre de grupo de recursos Seleccione un grupo de recursos o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
    Nombre de cuenta Escriba un nombre único. Escriba un nombre único para identificar la cuenta de Azure Cosmos DB. El URI de la cuenta será mongo.cosmos.azure.com y se anexará al nombre único de la cuenta.

    El nombre de la cuenta solo puede utilizar letras minúsculas, números y guiones (-), y debe tener entre 3 y 44 caracteres de longitud.
    Location Región más cercana a los usuarios Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.
    Capacity mode (Modo de capacidad) Rendimiento aprovisionado o sin servidor Seleccione Provisioned throughput (Rendimiento aprovisionado) para crear una cuenta en modo de rendimiento aprovisionado. Seleccione Serverless (Sin servidor) para crear una cuenta en modo sin servidor.

    Nota: solo se admiten la versiones 4 y 3.6 de MongoDB API en las cuentas sin servidor. Si elige la versión 3.2, se forzará la cuenta al modo de rendimiento aprovisionado.
    Aplicar el descuento del nivel Gratis de Azure Cosmos DB Aplicar o No aplicar Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis.
    Versión Elección de la versión de servidor necesaria La API de Azure Cosmos DB para MongoDB es compatible con la versión 4.0, 3.6 y 3.2 del servidor. Puede actualizar o degradar una cuenta después de crearla.

    Nota

    Puede tener una cuenta de Azure Cosmos DB de nivel Gratis por cada suscripción de Azure y debe optar por tenerla al crear la cuenta. Si no ve la opción para aplicar el descuento por nivel Gratis, significará que en otra cuenta de la suscripción ya se ha habilitado el nivel Gratis.

    Captura de pantalla de la página de nueva cuenta de Azure Cosmos DB.

  6. En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:

    Configuración Value Descripción
    Redundancia geográfica Deshabilitar Habilite o deshabilite la distribución global en su cuenta. Para ello, debe emparejar su región con una región de par. Puede agregar más regiones a su cuenta más adelante.
    Escrituras en varias regiones Deshabilitar La funcionalidad de escrituras en varias regiones le permite aprovechar el rendimiento aprovisionado para sus bases de datos y contenedores de todo el mundo.

    Nota

    Las siguientes opciones no están disponibles si selecciona Serverless (Sin servidor) en Capacity mode (Modo de capacidad):

    • Aplicación de descuento por nivel Gratis
    • Redundancia geográfica
    • Escrituras en varias regiones

  7. Opcionalmente, puede configurar detalles adicionales en las pestañas siguientes:

    • Redes: configure el acceso desde una red virtual.
    • Directiva de copia de seguridad: configure una directiva de copia de seguridad periódica o continua.
    • Cifrado: use una clave administrada por el servicio o una clave administrada por el cliente.
    • Etiquetas: son pares nombre-valor que permiten categorizar los recursos y ver una facturación consolidada mediante la aplicación de la misma etiqueta en varios recursos y grupos de recursos.

  8. Seleccione Revisar + crear.

  9. La cuenta tarda unos minutos en crearse. Espere a que el portal muestre la página ¡Enhorabuena! La cuenta de Azure Cosmos DB API para MongoDB está lista.

    Captura de pantalla del panel de notificaciones de Azure Portal.

Modelo de objetos

Antes de seguir con la creación de la aplicación, vamos a examinar la jerarquía de recursos de la API para MongoDB y el modelo de objetos que se usa para crear estos recursos y acceder a ellos. La API para MongoDB crea los recursos en el orden siguiente:

  • API de Azure Cosmos DB para cuentas de MongoDB
  • Bases de datos
  • Colecciones
  • Documentos

Para más información sobre la jerarquía de entidades, consulte el artículo Modelo de recursos de Azure Cosmos DB.

Instalación de la plantilla de aplicación de ejemplo

Este ejemplo es una plantilla de proyecto de .NET que se puede instalar para crear una copia local. Ejecute los siguientes comandos en una ventana de comandos:

mkdir "C:\cosmos-samples"
cd "C:\cosmos-samples"
dotnet new -i Microsoft.Azure.Cosmos.Templates
dotnet new cosmosmongo-webapi

Los comandos anteriores:

  1. Cree el directorio C:\cosmos-samples para el ejemplo. Elija una carpeta adecuada para su sistema operativo.
  2. Cambie el directorio actual a la carpeta C:\cosmos-samples.
  3. Instale la plantilla del proyecto para que esté disponible globalmente desde la CLI de .NET.
  4. Cree una aplicación de ejemplo local con la plantilla del proyecto.

Si no desea usar la CLI de .NET, también puede descargar las plantillas del proyecto como un archivo ZIP. Este ejemplo se encuentra en la carpeta Templates/APIForMongoDBQuickstart-WebAPI.

Revisión del código

Los pasos siguientes son opcionales. Si está interesado en aprender cómo se crean los recursos de base de datos en el código, revise los siguientes fragmentos de código. De lo contrario, vaya directamente a Actualización de la configuración de la aplicación.

Configuración de la conexión

El siguiente fragmento de código es del archivo Services/MongoService.cs.

  • La siguiente clase representa al cliente y .NET Framework la inserta en los servicios que la consumen:

        public class MongoService
    {
        private static MongoClient _client;

        public MongoService(IDatabaseSettings settings)
        {
            _client = new MongoClient(settings.MongoConnectionString);
        }

        public MongoClient GetClient()
        {
            return _client;
        }
    }

Configuración del servicio de datos del catálogo de productos

Los fragmentos de código siguientes son del archivo Services/ProductService.cs.

  • El código siguiente recupera la base de datos y la colección y los creará si aún no existen:

    private readonly IMongoCollection<Product> _products;        

public ProductService(MongoService mongo, IDatabaseSettings settings)
{
    var db = mongo.GetClient().GetDatabase(settings.DatabaseName);
    _products = db.GetCollection<Product>(settings.ProductCollectionName);
}

  • El código siguiente recupera un documento por SKU, un identificador de producto único:

    public Task<Product> GetBySkuAsync(string sku)
{
    return _products.Find(p => p.Sku == sku).FirstOrDefaultAsync();
}

  • El código siguiente crea un producto y lo inserta en la colección:

    public Task CreateAsync(Product product)
{
    _products.InsertOneAsync(product);
}

  • El código siguiente busca y actualiza un producto:

    public Task<Product> UpdateAsync(Product update)
{
    return _products.FindOneAndReplaceAsync(
        Builders<Product>.Filter.Eq(p => p.Sku, update.Sku), 
        update, 
        new FindOneAndReplaceOptions<Product> { ReturnDocument = ReturnDocument.After });
}

    De forma similar, puede eliminar documentos mediante el método collection.DeleteOne().

Actualización de la configuración de la aplicación

En Azure Portal, copie la información de la cadena de conexión:

  1. En Azure Portal, seleccione la cuenta de Cosmos DB y, en el panel de navegación izquierdo, seleccione Cadena de conexión y, después, Claves de lectura y escritura. Deberá usar los botones de copia que se encuentran en el lado derecho de la pantalla para copiar la cadena de conexión principal en el archivo appsettings.json en el paso siguiente.

  2. Abra el archivo appsettings.json.

  3. Copie el valor de la cadena de conexión principal del portal (con el botón de copia) y especifíquelo en el valor de la propiedad DatabaseSettings.MongoConnectionString en el archivo appsettings.json.

  4. Revise el valor del nombre de la base de datos en la propiedad DatabaseSettings.DatabaseName en el archivo appsettings.json.

  5. Revise el valor del nombre de la colección en la propiedad DatabaseSettings.ProductCollectionName en el archivo appsettings.json.

Advertencia

Nunca compruebe las contraseñas u otros datos confidenciales en el código fuente.

Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Cosmos DB.

Carga de datos de muestra

Descargue mongoimport, una herramienta de la CLI que importa fácilmente pequeñas cantidades de datos JSON, CSV o TSV. Usaremos mongoimport para cargar los datos de productos de ejemplo proporcionados en la carpeta Data de este proyecto.

En Azure Portal, copie la información de conexión y escríbala en el siguiente comando:

mongoimport --host <HOST>:<PORT> -u <USERNAME> -p <PASSWORD> --db cosmicworks --collection products --ssl --jsonArray --writeConcern="{w:0}" --file Data/products.json

  1. En Azure Portal, seleccione la API de Azure Cosmos DB para cuentas de MongoDB y, en el panel de navegación izquierdo, seleccione Cadena de conexión y, después, seleccione Claves de lectura y escritura.

  2. Copie el valor de HOST del portal (mediante el botón de copia) y escríbalo en lugar de <HOST> .

  3. Copie el valor de PORT del portal (mediante el botón de copia) y escríbalo en lugar de <PORT> .

  4. Copie el valor de USERNAME del portal (mediante el botón de copia) y escríbalo en lugar de <USERNAME> .

  5. Copie el valor de PASSWORD del portal (mediante el botón de copia) y escríbalo en lugar de <PASSWORD> .

  6. Revise el valor del nombre de la base de datos y actualícelo si creó uno distinto de cosmicworks.

  7. Revise el valor del nombre de la colección y actualícelo si creó uno distinto de products.

Nota

Si desea omitir este paso, puede crear documentos con el esquema correcto mediante el punto de conexión POST proporcionado como parte de este proyecto de API web.

Ejecutar la aplicación

En Visual Studio, seleccione CTRL + F5 para ejecutar la aplicación. El explorador predeterminado se inicia con la aplicación.

Si prefiere la CLI, ejecute el siguiente comando en una ventana de comandos para iniciar la aplicación de ejemplo. Este comando también instalará las dependencias del proyecto y compilará el proyecto, pero no iniciará automáticamente el explorador.

dotnet run

Una vez que la aplicación esté en ejecución, vaya a https://localhost:5001/swagger/index.html para ver la documentación de Swagger de la API web y enviar solicitudes de ejemplo.

Seleccione la API que desea probar y seleccione "Try it out" (Probarlo).

Captura de pantalla de la página para probar puntos de conexión de API de la interfaz de usuario de Swagger de la API web.

Escriba los parámetros necesarios y seleccione "Execute" (Ejecutar).

Limpieza de recursos

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. Para eliminar los recursos:

  1. En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.

  2. En la lista, seleccione el grupo de recursos que creó para este inicio rápido.

    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.

    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.

Pasos siguientes

En este inicio rápido, ha aprendido a crear una API para cuentas de MongoDB, una base de datos y una colección con código, y a ejecutar una aplicación de API web. Ahora, puede importar datos adicionales en la base de datos.

¿Intenta planear la capacidad para una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de bases de datos existente.

Importación de datos de MongoDB a Azure Cosmos DB