Inicio rápido: Creación de una aplicación Java para administrar los datos de SQL API de Azure Cosmos DB
SE APLICA A:
SQL API
En este inicio rápido se crea y administra una cuenta de Azure Cosmos DB para SQL API desde Azure Portal, y se usa una aplicación de Java clonada desde GitHub. En primer lugar, se crea una cuenta de SQL API de Azure Cosmos DB desde Azure Portal, luego, una aplicación Java mediante el SDK de SQL Java y, después, se agregan los recursos a la cuenta de Cosmos DB mediante la aplicación de Java. 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.
Importante
Este inicio rápido solo es para el SDK de Azure Cosmos DB para Java v4. Consulte las notas de la versión del SDK de Azure Cosmos DB para Java v4, el repositorio de Maven, las sugerencias de rendimiento del SDK de Azure Cosmos DB para Java v4 y la guía de solución de problemas del SDK de Azure Cosmos DB para Java v4 para más información. Si en la actualidad usa una versión anterior a v4, vea la guía Migración al SDK de Azure Cosmos DB para Java v4 a fin de obtener ayuda para actualizar a v4.
Requisitos previos
- Una cuenta de Azure con una suscripción activa. cree una de forma gratuita. O bien, pruebe gratis Azure Cosmos DB sin una suscripción de Azure. También puede usar el emulador de Azure Cosmos DB con el identificador URI
https://localhost:8081y la claveC2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. - Java Development Kit (JDK) 8. Apunte su variable de entorno
JAVA_HOMEa la carpeta donde está instalado el JDK. - Un archivo binario de Maven. En Ubuntu, ejecute
apt-get install mavenpara instalar Maven. - Git. En Ubuntu, ejecute
sudo apt-get install gitpara instalar Git.
Notas de introducción
Estructura de una cuenta de Cosmos DB: independientemente de la API o el lenguaje de programación, una cuenta de Cosmos DB contiene de cero o varias bases de datos; una base de datos contiene de cero a varios contenedores y un contenedor contiene de cero a varios elementos, como se muestra en el diagrama siguiente:
Puede leer más información sobre las bases de datos, los contenedores y los elementos aquí. Algunas propiedades importantes se definen en el nivel del contenedor, entre ellas la capacidad de proceso aprovisionada y la clave de partición.
La capacidad de proceso aprovisionada se mide en unidades de solicitud (RU) que tienen un precio monetario y son un factor determinante crucial en el costo operativo de la cuenta. La capacidad de proceso aprovisionada se puede seleccionar en una granularidad por contenedor o por base de datos; sin embargo, se suele preferir la especificación de capacidad de proceso a nivel de contenedor. Para más información sobre el aprovisionamiento de capacidad de proceso aquí.
A medida que los elementos se insertan en un contenedor de Cosmos DB, la base de datos crece horizontalmente al agregar más almacenamiento y procesos para controlar las solicitudes. La capacidad de almacenamiento y de proceso se agregan en unidades discontinuas conocidas como particiones y debe elegir un campo en los documentos para que sea la clave de partición para asignar cada documento a una partición. La forma de administración de las particiones es la asignación a cada partición de un segmento aproximadamente igual fuera del intervalo de valores de la clave de partición. Por lo tanto, se recomienda elegir una clave de partición relativamente aleatoria o distribuida uniformemente. De lo contrario, algunas particiones verán bastantes más solicitudes (partición de uso frecuente) mientras que otras verán muchas menos (partición de uso esporádico), comportamiento que se debe evitar. Aquí encontrará más información sobre la creación de particiones.
Creación de una cuenta de base de datos
Para poder crear una base de datos de documentos, debe crear una cuenta de SQL API con Azure Cosmos DB.
En el menú de Azure Portal o en la página principal, seleccione Crear un recurso.
En la página Nuevos, busque y seleccione Azure Cosmos DB.
En la página Azure Cosmos DB, seleccione Crear.
En la página Creación de una cuenta de Azure Cosmos DB , especifique la configuración básica de la nueva cuenta de Azure Cosmos.
Configuración Valor Descripción Suscripción Nombre de suscripción Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos. 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 Un nombre único Escriba un nombre para identificar la cuenta de Azure Cosmos. Dado que documents.azure.com se anexa al nombre que se proporciona para crear el identificador URI, debe usar un nombre único.
El nombre solo puede contener letras minúsculas, números y el carácter de guion (-). Debe tener una longitud de entre 3 y 44 caracteres.API El tipo de cuenta que se va a crear Seleccione Core(SQL) para crear una base de datos de documentos y consultarla mediante la sintaxis SQL.
La API determina el tipo de cuenta que se va a crear. Azure Cosmos DB proporciona cinco API: Core (SQL) y MongoDB para datos de documento, Gremlin para datos de gráfico, Azure Table y Cassandra. Actualmente, debe crear una cuenta independiente para cada API.
Más información acerca de SQL API.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. 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. 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.
En la pestaña Distribución global, configure los detalles siguientes. Puede dejar los valores predeterminados para este inicio rápido:
Configuración Valor 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
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.
Seleccione Revisar + crear.
Revise la configuración de la cuenta y seleccione Crear. La operación de creación de la cuenta tarda unos minutos. Espere hasta que la página del portal muestre Se completó la implementación .
Seleccione Ir al recurso para ir a la página de la cuenta de Azure Cosmos DB.
Agregar un contenedor
Ahora puede usar la herramienta Explorador de datos en Azure Portal para crear una base de datos y un contenedor.
Seleccione Data Explorer > Nuevo contenedor.
El área Agregar contenedor se muestra en el extremo derecho, pero es posible que haya que desplazarse hacia la derecha para verlo.
En la página Agregar contenedor, especifique la configuración del nuevo contenedor.
Configuración Valor sugerido Descripción Identificador de base de datos ToDoList Escriba Tareas como nombre de la nueva base de datos. Los nombres de base de datos tienen que tener entre 1 y 255 caracteres y no pueden contener /, \\, #, ?o espacios finales. Seleccione la opción Share throughput across containers (Compartir rendimiento entre contenedores) para compartir el rendimiento aprovisionado de la base de datos entre todos los contenedores de esta. Esta opción también le ayudará a reducir los costos.Rendimiento de base de datos Puede aprovisionar rendimiento de escalado automático o manual. El rendimiento manual le permite escalar RU/s por su cuenta, mientras que el rendimiento de escalabilidad automática permite que el sistema escale RU/s en función del uso. En este ejemplo, seleccione Manual.
Deje el rendimiento en 400 unidades de solicitud por segundo (RU/s). Si quiere reducir la latencia, puede escalar verticalmente el rendimiento más adelante mediante la estimación de las RU/s necesarias con la calculadora de capacidad.
Nota: Este valor no está disponible cuando se crea un contenedor en una cuenta sin servidor.ID de contenedor Elementos Escriba Elementos como nombre del nuevo contenedor. Los identificadores de contenedor tienen los mismos requisitos de caracteres que los nombres de las bases de datos. Clave de partición /categoría El ejemplo que se describe en este artículo usa /category como clave de partición. En este ejemplo, no agregue claves únicas ni active el almacén analítico. Las claves únicas le permiten agregar una capa de integridad de datos a la base de datos mediante la garantía de unicidad de uno o varios valores por clave de partición. Para más información, consulte Claves únicas en Azure Cosmos DB. El almacén analítico se usa para permitir el análisis a gran escala de datos operativos sin ningún efecto sobre las cargas de trabajo transaccionales.
Seleccione Aceptar. El Explorador de datos muestra la nueva base de datos y el contenedor.
Adición de datos de ejemplo
Ahora, puede agregar datos al nuevo contenedor con el Explorador de datos.
En el Explorador de datos, expanda la base de datos Tareas y, después, el contenedor Elementos. Seleccione Elementos y, después, Nuevo elemento.

Ahora, agregue un documento al contenedor con la estructura siguiente.
{ "id": "1", "category": "personal", "name": "groceries", "description": "Pick up apples and strawberries.", "isComplete": false }Después de agregar el archivo JSON a la pestaña Documentos, seleccione Guardar.

Cree y guarde un documento más donde insertará un valor único para la propiedad
idy cambie las demás propiedades como corresponda. Los nuevos documentos pueden tener la estructura que quiera, ya que Azure Cosmos DB no impone ningún esquema en los datos.
Consulta de los datos
Ahora puede usar consultas en Data Explorer para recuperar y filtrar los datos.
En la parte superior de la pestaña Elementos de Data Explorer, examine la consulta predeterminada
SELECT * FROM c. Esta consulta recupera y muestra todos los documentos del contenedor ordenados por identificador.
Para cambiar la consulta, seleccione Editar filtro, reemplace la consulta predeterminada por
ORDER BY c._ts DESCy, después, seleccione Aplicar filtro.
Esta consulta modificada muestra los documentos en orden descendente según su marca de tiempo, por lo que ahora el segundo documento aparece en primer lugar.
Si está familiarizado con la sintaxis de SQL, puede especificar cualquiera de las consultas SQL admitidas en el cuadro de predicado de consulta. También puede usar Data Explorer para crear procedimientos almacenados, UDF y desencadenadores para la lógica de negocios del servidor.
Data Explorer proporciona un acceso sencillo en Azure Portal a todas las características de acceso a datos mediante programación integrado que está disponible en las API. Use también el portal para escalar el rendimiento, obtener las claves y cadenas de conexión, y revisar las métricas y los contratos de nivel de servicio de la cuenta de Azure Cosmos DB.
Clonación de la aplicación de ejemplo
Ahora vamos a empezar a trabajar con el código. Vamos a clonar una aplicación de SQL API desde GitHub, establecer la cadena de conexión y ejecutarla. Verá lo fácil que es trabajar con datos mediante programación.
Ejecute el comando siguiente para clonar el repositorio de ejemplo. Este comando crea una copia de la aplicación de ejemplo en el equipo.
git clone https://github.com/Azure-Samples/azure-cosmos-java-getting-started.git
Revisión del código
Este paso es opcional. Si está interesado en aprender cómo se crean los recursos de base de datos en el código, puede revisar los siguientes fragmentos de código. En caso contrario, puede ir directamente a Ejecutar la aplicación.
Administración de recursos de base de datos mediante la API sincrónica (sincronización)
Inicialización de
CosmosClient.CosmosClientproporciona una representación lógica del cliente para el servicio de base de datos de Azure Cosmos. Este cliente se usa para configurar y ejecutar solicitudes en el servicio.client = new CosmosClientBuilder() .endpoint(AccountSettings.HOST) .key(AccountSettings.MASTER_KEY) // Setting the preferred location to Cosmos DB Account region // West US is just an example. User should set preferred location to the Cosmos DB region closest to the application .preferredRegions(Collections.singletonList("West US")) .consistencyLevel(ConsistencyLevel.EVENTUAL) .buildClient();Creación de
CosmosDatabase.CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName); database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());Creación de
CosmosContainer.CosmosContainerProperties containerProperties = new CosmosContainerProperties(containerName, "/lastName"); // Create container with 400 RU/s CosmosContainerResponse cosmosContainerResponse = database.createContainerIfNotExists(containerProperties, ThroughputProperties.createManualThroughput(400)); container = database.getContainer(cosmosContainerResponse.getProperties().getId());Creación de elementos mediante el método
createItem.// Create item using container that we created using sync client // Use lastName as partitionKey for cosmos item // Using appropriate partition key improves the performance of database operations CosmosItemRequestOptions cosmosItemRequestOptions = new CosmosItemRequestOptions(); CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()), cosmosItemRequestOptions);Las lecturas puntuales se realizan mediante el método
readItem.try { CosmosItemResponse<Family> item = container.readItem(family.getId(), new PartitionKey(family.getLastName()), Family.class); double requestCharge = item.getRequestCharge(); Duration requestLatency = item.getDuration(); logger.info("Item successfully read with id {} with a charge of {} and within duration {}", item.getItem().getId(), requestCharge, requestLatency); } catch (CosmosException e) { logger.error("Read Item failed with", e); }Las consultas SQL a través de JSON se realizan con el método
queryItems.// Set some common query options CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions(); //queryOptions.setEnableCrossPartitionQuery(true); //No longer necessary in SDK v4 // Set query metrics enabled to get metrics around query executions queryOptions.setQueryMetricsEnabled(true); CosmosPagedIterable<Family> familiesPagedIterable = container.queryItems( "SELECT * FROM Family WHERE Family.lastName IN ('Andersen', 'Wakefield', 'Johnson')", queryOptions, Family.class); familiesPagedIterable.iterableByPage(10).forEach(cosmosItemPropertiesFeedResponse -> { logger.info("Got a page of query result with {} items(s) and request charge of {}", cosmosItemPropertiesFeedResponse.getResults().size(), cosmosItemPropertiesFeedResponse.getRequestCharge()); logger.info("Item Ids {}", cosmosItemPropertiesFeedResponse .getResults() .stream() .map(Family::getId) .collect(Collectors.toList())); });
Ejecución la aplicación
Ahora vuelva a Azure Portal para obtener la información de la cadena de conexión e iniciar la aplicación con la información del punto de conexión. Esto permite que la aplicación se comunique con la base de datos hospedada.
En la ventana de terminal de GIT,
cda la carpeta del código de ejemplo.cd azure-cosmos-java-getting-startedEn la ventana del terminal de GIT, use el comando siguiente para instalar los paquetes Java necesarios.
mvn packageEn la ventana del terminal de GIT, use el siguiente comando para iniciar la aplicación Java (reemplace SYNCASYNCMODE por
syncoasyncsegún el código de ejemplo que desea ejecutar, reemplace YOUR_COSMOS_DB_HOSTNAME por el valor del identificador URI entre comillas del portal y reemplace YOUR_COSMOS_DB_MASTER_KEY por la clave principal entre comillas del portal)mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEYLa ventana del terminal muestra una notificación de que se ha creado la base de datos FamilyDB.
La aplicación crea la base de datos con el nombre
AzureSampleFamilyDB.La aplicación crea un contenedor con el nombre
FamilyContainer.La aplicación realizará las lecturas puntuales con los identificadores de objeto y el valor de clave de partición (que es lastName en nuestro ejemplo).
La aplicación consultará los elementos para recuperar todas las familias con el apellido en ("Andersen", "Wakefield", "Johnson").
La aplicación no elimina los recursos creados. Vuelva al portal para limpiar los recursos. desde su cuenta para que no incurrir en gastos.
Revisión de los SLA en Azure Portal
Azure Portal supervisa el rendimiento, capacidad de almacenamiento, disponibilidad, latencia y coherencia de su cuenta de Cosmos DB. 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. Este conjunto de métricas hace que la supervisión de los Acuerdos de Nivel de Servicio sea transparente.
Para revisar las métricas y los Acuerdos de Nivel de Servicio:
Seleccione Métricas en el menú de navegación de la cuenta de Cosmos DB.
Seleccione una pestaña como Latencia y seleccione un período de tiempo a la derecha. Compare las líneas Real y SLA de los gráficos.

Revise las métricas de las otras pestañas.
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:
En la barra de búsqueda de Azure Portal, busque y seleccione Grupos de recursos.
En la lista, seleccione el grupo de recursos que creó para este inicio rápido.

En la página Información general del grupo de recursos, seleccione Eliminar grupo de recursos.

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 cuenta de SQL API de Azure Cosmos DB, a crear una base de datos de documentos y un contenedor mediante Data Explorer, y a ejecutar una aplicación de Java para que haga lo mismo mediante programación. Ya puede importar datos adicionales en la cuenta de Azure Cosmos DB.
¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Puede usar información sobre el clúster de bases de datos existente para planear la capacidad.
- Si lo único que sabe es el número de núcleos virtuales y servidores del clúster de bases de datos existente, lea sobre el cálculo de unidades de solicitud mediante núcleos o CPU virtuales.
- Si conoce las tasas de solicitudes típicas de la carga de trabajo de la base de datos actual, obtenga información sobre el cálculo de unidades de solicitud mediante la herramienta de planeamiento de capacidad de Azure Cosmos DB.