Inicio rápido: creación de una aplicación de Table API con el SDK de .NET y Azure Cosmos DBQuickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

Esta guía de inicio rápido muestra cómo se usan .NET y Table API de Azure Cosmos DB para compilar una aplicación mediante la clonación de un ejemplo de GitHub.This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. Esta guía de inicio rápido también muestra cómo crear una cuenta de Azure Cosmos DB y cómo usar el Explorador de datos para crear tablas y entidades en Azure Portal basado en web.This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

Requisitos previosPrerequisites

Si aún no tiene instalado Visual Studio 2019, puede descargar y usar la versión gratuita de Visual Studio 2019 Community.If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. Asegúrese de que habilita Desarrollo de Azure durante la instalación de Visual Studio.Make sure that you enable Azure development during the Visual Studio setup.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Creación de una cuenta de base de datosCreate a database account

  1. En una nueva ventana del explorador, inicie sesión en Azure Portal.In a new browser window, sign in to the Azure portal.

  2. En el panel de navegación izquierdo, seleccione Crear un recurso.In the left navigation pane, select Create a resource. Seleccione Bases de datos y, luego, Azure Cosmos DB.Select Databases and then select Azure Cosmos DB.

    Captura de pantalla de Azure Portal en la que se resaltan Más servicios y Azure Cosmos DB

  3. En la página Crear una cuenta de Azure Cosmos DB, especifique la configuración de la nueva cuenta de Azure Cosmos DB:On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account:

    ConfiguraciónSetting ValorValue DESCRIPCIÓNDescription
    SubscriptionSubscription Su suscripciónYour subscription Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    Grupo de recursosResource Group Crear nuevoCreate new

    A continuación, escriba el mismo nombre único que se proporcionó en el identificadorThen enter the same unique name as provided in ID
    Seleccione Crear nuevo.Select Create new. Luego, escriba un nombre nuevo de grupo de recursos para la cuenta.Then enter a new resource group name for your account. Para simplificar, utilice el mismo nombre del identificador.For simplicity, use the same name as your ID.
    Nombre de cuentaAccount Name Escriba un nombre único.Enter a unique name Escriba un nombre único para identificar la cuenta de Azure Cosmos DB.Enter a unique name to identify your Azure Cosmos DB account.

    El identificador solo debe contener letras minúsculas, números y el carácter de guion (-).The ID can use only lowercase letters, numbers, and the hyphen (-) character. El nombre debe tener entre 3 y 31 caracteres.It must be between 3 and 31 characters long.
    APIAPI tabla de AzureAzure Table La API determina el tipo de cuenta que se va a crear.The API determines the type of account to create. Azure Cosmos DB proporciona cinco API: Core(SQL) para bases de datos de documentos, Gremlin para bases de datos de grafos, MongoDB para bases de datos de documentos, Azure Table y Cassandra.Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. Actualmente, debe crear una cuenta independiente para cada API.Currently, you must create a separate account for each API.

    Seleccione Tabla de Azure, ya que en este inicio rápido va a crear una tabla que funciona con Table API.Select Azure Table because in this quickstart you're creating a table that works with the Table API.

    Más información acerca de Table API.Learn more about the Table API.
    LocationLocation Seleccionar la región más cercana a los usuariosSelect the region closest to your users Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use la ubicación más cercana a los usuarios para proporcionarles el acceso más rápido a los datos.Use the location that's closest to your users to give them the fastest access to data.

    En las opciones Redundancia geográfica y Escrituras en varias regiones puede dejar sus valores predeterminados (Deshabilitar) para evitar gastos de RU adicionales.You can leave the Geo-Redundancy and Multi-region Writes options at their default values (Disable) to avoid additional RU charges. Puede omitir las secciones Red y Etiquetas.You can skip the Network and Tags sections.

  4. Seleccione Revisar y crear.Select Review+Create. Una vez completada la validación, seleccione Crear para crear la cuenta.After the validation is complete, select Create to create the account.

    Página de la nueva cuenta de Azure Cosmos DB

  5. La operación de creación de la cuenta tarda unos minutos.It takes a few minutes to create the account. Verá el mensaje La implementación está en curso.You'll see a message that states Your deployment is underway. Espere hasta que finalice implementación y seleccione Ir al recurso.Wait for the deployment to finish and then select Go to resource.

    El panel de notificaciones de Azure Portal

Adición de una tablaAdd a table

Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos y una tabla.You can now use the Data Explorer tool in the Azure portal to create a database and table.

  1. Seleccione Explorador de datos > Nueva tabla.Select Data Explorer > New Table.

    El área Agregar tabla se muestra en el extremo derecho, pero es posible que tenga que desplazarse hacia la derecha para verla.The Add Table area is displayed on the far right, you may need to scroll right to see it.

    Explorador de datos en Azure Portal

  2. En la página Agregar tabla, escriba la configuración de la nueva tabla.In the Add Table page, enter the settings for the new table.

    ConfiguraciónSetting Valor sugeridoSuggested value DESCRIPCIÓNDescription
    Id. de tablaTable Id sample-tablesample-table Identificador de la nueva tabla.The ID for your new table. Los nombres de tabla tienen los mismos requisitos de caracteres que los identificadores de base de datos.Table names have the same character requirements as database ids. Los nombres de bases de datos deben tener entre 1 y 255 caracteres y no pueden contener / \ # ? o un espacio al final.Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    ThroughputThroughput 400 RU400 RUs Cambie el rendimiento a 400 unidades de solicitud por segundo (RU/s).Change the throughput to 400 request units per second (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante.If you want to reduce latency, you can scale up the throughput later.
  3. Seleccione Aceptar.Select OK.

  4. El Explorador de datos muestra la nueva base de datos y la tabla.Data Explorer displays the new database and table.

    El Explorador de datos de Azure Portal mostrando la nueva base de datos y la colección

Adición de datos de ejemploAdd sample data

Ahora puede agregar datos a la nueva tabla mediante el Explorador de datos.You can now add data to your new table using Data Explorer.

  1. En el Explorador de datos, expanda sample-table y seleccione Entidades y, después, seleccione Agregar entidad.In Data Explorer, expand sample-table, select Entities, and then select Add Entity.

    Creación de nuevas entidades en el Explorador de datos en Azure Portal

  2. Ahora agregue datos al cuadro de valores de PartitionKey y RowKey y seleccione Agregar entidad.Now add data to the PartitionKey value box and RowKey value box, and select Add Entity.

    Establecimiento de la clave de partición y la clave de fila para una nueva entidad

    Ahora puede agregar más entidades a la tabla, editar las entidades o consultar los datos en el Explorador de datos.You can now add more entities to your table, edit your entities, or query your data in Data Explorer. En el Explorador de datos también puede escalar el rendimiento y agregar procedimientos almacenados, funciones definidas por el usuario y desencadenadores a su tabla.Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

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

Ahora vamos a clonar una aplicación de Table desde GitHub, establecer la cadena de conexión y ejecutarla.Now let's clone a Table app from GitHub, set the connection string, and run it. Verá lo fácil que es trabajar con datos mediante programación.You'll see how easy it is to work with data programmatically.

  1. Abra un símbolo del sistema, cree una carpeta nueva denominada ejemplos de GIT 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.

    md "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/azure-cosmos-table-dotnet-core-getting-started.git
    

Abrir la aplicación de ejemplo en Visual StudioOpen the sample application in Visual Studio

  1. En Visual Studio, desde el menú Archivo, elija Abrir y, a continuación, elija Proyecto o solución.In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    Abrir la solución

  2. Navegue hasta la carpeta donde clonó la aplicación de ejemplo y abra el archivo TableStorage.sln.Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

Actualización de la cadena de conexiónUpdate your connection string

Ahora vuelva a Azure Portal para obtener la información de la cadena de conexión y cópiela en la aplicación.Now go back to the Azure portal to get your connection string information and copy it into the app. Esto permite que la aplicación se comunique con la base de datos hospedada.This enables your app to communicate with your hosted database.

  1. En Azure Portal, haga clic en Cadena de conexión.In the Azure portal, click Connection String. Use el botón de copia en el lado derecho de la ventana para copiar la CADENA DE CONEXIÓN PRINCIPAL.Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

    Visualización y copia de la cadena de conexión principal (PRIMARY CONNECTION STRING) en el panel Cadena de conexión

  2. En Visual Studio, abra el archivo Settings.json.In Visual Studio, open the Settings.json file.

  3. Pegue la CADENA DE CONEXIÓN PRINCIPAL del portal en el valor de StorageConnectionString.Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. Pegue la cadena dentro de las comillas.Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. Presione CTRL+S para guardar el archivo Settings.json.Press CTRL+S to save the Settings.json file.

Ya ha actualizado la aplicación con toda la información que necesita para comunicarse con Azure Cosmos DB.You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

Compilación e implementación de la aplicaciónBuild and deploy the app

  1. En Visual Studio, haga clic con el botón derecho en el proyecto CosmosTableSamples en Explorador de soluciones y, después, haga clic en Administrar paquetes NuGet.In Visual Studio, right-click on the CosmosTableSamples project in Solution Explorer and then click Manage NuGet Packages.

    Administración de paquetes de NuGet

  2. En el cuadro Examinar de NuGet, escriba Microsoft.Azure.Cosmos.Table.In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. Se buscará la biblioteca de cliente de Table API de Cosmos DB.This will find the Cosmos DB Table API client library. Observe que esta biblioteca está disponible actualmente para .NET Framework y .NET Standard.Note that this library is currently available for .NET Framework and .NET Standard.

    Pestaña Examinar de NuGet

  3. Haga clic en Instalar para instalar la biblioteca Microsoft.Azure.Cosmos.Table.Click Install to install the Microsoft.Azure.Cosmos.Table library. De este modo, se instalan el paquete de Table API de Azure Cosmos DB y todas las dependencias.This installs the Azure Cosmos DB Table API package and all dependencies.

  4. Al ejecutar toda la aplicación, los datos de ejemplo se insertan en la entidad de tabla y eliminan al final, por lo que no verá datos insertados si ejecuta todo el ejemplo.When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. Sin embargo, puede insertar algunos puntos de interrupción para ver los datos.However you can insert some breakpoints to view the data. Abra el archivo BasicSamples.cs y haga clic con el botón derecho en la línea 52, seleccione Punto de interrupción y, a continuación, seleccione Insertar punto de interrupción.Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. Inserte otro punto de interrupción en la línea 55.Insert another breakpoint on line 55.

    Agregar un punto de interrupción

  5. Presione F5 para ejecutar la aplicación.Press F5 to run the application. En la ventana de consola se muestra el nombre de la nueva base de datos de tablas (en este caso, demoa13b1) en Azure Cosmos DB.The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    Salida de consola

    Cuando se alcance el primer punto de interrupción, vuelva al Explorador de datos en Azure Portal.When you hit the first breakpoint, go back to Data Explorer in the Azure portal. Haga clic en el botón Actualizar, expanda la tabla demo* y haga clic en Entidades.Click the Refresh button, expand the demo* table, and click Entities. En la pestaña Entidades que está a la derecha se muestra la nueva entidad que se agregó para Walter Harp.The Entities tab on the right shows the new entity that was added for Walter Harp. Tenga en cuenta que el número de teléfono para la nueva entidad es 425-555-0101.Note that the phone number for the new entity is 425-555-0101.

    Nueva entidad

    Si recibe un error que indica que no se encuentra el archivo Settings.json al ejecutar el proyecto, puede resolverlo agregando la siguiente entrada XML a la configuración del proyecto.If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. Haga clic en CosmosTableSamples, seleccione Editar CosmosTableSamples.csproj y agregue el itemGroup siguiente:Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. Cierre la pestaña Entidades en el Explorador de datos.Close the Entities tab in Data Explorer.

  7. Presione F5 para ejecutar la aplicación hasta el siguiente punto de interrupción.Press F5 to run the app to the next breakpoint.

    Cuando se alcance el punto de interrupción, vuelva a Azure Portal, haga clic de nuevo en la pestaña Entidades para abrirla y compruebe que el número de teléfono se haya actualizado a 425-555-0105.When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. Presione F5 para ejecutar la aplicación.Press F5 to run the app.

    La aplicación agrega entidades para usar en una aplicación de ejemplo avanzada que Table API no admite actualmente.The app adds entities for use in an advanced sample app that the Table API currently does not support. A continuación, la aplicación elimina la tabla creada por la aplicación de ejemplo.The app then deletes the table created by the sample app.

  9. En la ventana de la consola, presione Entrar para finalizar la ejecución de la aplicación.In the console window, press Enter to end the execution of the app.

Revisión de los SLA en Azure PortalReview SLAs in the Azure portal

Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Los gráficos de las métricas asociadas con un Acuerdo de Nivel de Servicio (SLA) de Azure Cosmos DB muestran el rendimiento real en comparación con el valor de este acuerdo.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.This suite of metrics makes monitoring your SLAs transparent.

Para revisar las métricas y los Acuerdos de Nivel de Servicio:To review metrics and SLAs:

  1. Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha.Select a tab such as Latency, and select a timeframe on the right. Compare las líneas Real y SLA de los gráficos.Compare the Actual and SLA lines on the charts.

    Conjunto de métricas de Azure Cosmos DB

  3. Revise las métricas de las otras pestañas.Review the metrics on the other tabs.

Limpieza de recursosClean up resources

Cuando haya terminado tanto con la aplicación web 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 web 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 Azure Portal, seleccione Grupos de recursos a la izquierda del todo.In the Azure portal, select Resource groups on the far left. Si el menú de la izquierda está contraído, seleccione el botón Expandir para expandirlo.If the left menu is collapsed, select Expand button to expand it.

  2. Seleccione el grupo de recursos que creó para este inicio rápido.Select the resource group you created for this quickstart.

    Selección del grupo de recursos que se eliminará

  3. En la nueva ventana, seleccione Eliminar grupo de recursos.In the new window, 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 esta guía de inicio rápido, ha obtenido información sobre cómo crear una cuenta de Azure Cosmos DB, crear una tabla mediante el Explorador de datos y ejecutar una aplicación.In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. Ahora ya puede consultar los datos mediante Table API.Now you can query your data using the Table API.