Cómo configurar la caché integrada de Azure Cosmos DB

Artículo
12/30/2023

SE APLICA A: NoSQL

En este artículo se describe cómo aprovisionar una puerta de enlace dedicada, cómo configurar la caché integrada y cómo conectar la aplicación.

Requisitos previos

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Una aplicación existente que usa Azure Cosmos DB. Si no tiene una, aquí tiene algunos ejemplos.
Una cuenta existente de API de Azure Cosmos DB for NoSQL.

Aprovisionamiento de la puerta de enlace dedicada

Vaya a una cuenta de Azure Cosmos DB en Azure Portal y seleccione la pestaña Puerta de enlace dedicada.
Rellene el formulario Puerta de enlace dedicada con los detalles siguientes:
- Puerta de enlace dedicada: establezca el botón de alternancia en Aprovisionada.
- SKU: seleccione una SKU con el tamaño de proceso y memoria necesarios. La caché integrada usará aproximadamente el 50 % de la memoria y la memoria restante se usa para metadatos y solicitudes de enrutamiento a las particiones de back-end.
- Número de instancias: número de nodos. Con fines de desarrollo, se recomienda empezar con un nodo del tamaño D4. En función de la cantidad de datos que necesite almacenar en caché y para lograr una alta disponibilidad, puede aumentar el tamaño del nodo tras las pruebas iniciales.
Seleccione Guardar y espere entre 5 y 10 minutos para que se complete el aprovisionamiento de la puerta de enlace dedicada. Cuando haya terminado el aprovisionamiento, verá la siguiente notificación:

Configuración de la memoria caché integrada

Al crear una puerta de enlace dedicada, se aprovisiona automáticamente una caché integrada.

Modifique la cadena de conexión de la aplicación para usar el nuevo punto de conexión de la puerta de enlace dedicada.

La cadena de conexión de la puerta de enlace dedicada actualizada se encuentra en la hoja Claves:

Todas las cadenas de conexión de las puertas de enlace dedicadas siguen el mismo patrón. Quite documents.azure.com de la cadena de conexión original y reemplácela por sqlx.cosmos.azure.com. Una puerta de enlace dedicada siempre tendrá la misma cadena de conexión, incluso si se quita y se vuelve a aprovisionar.

No es necesario modificar la cadena de conexión en todas las aplicaciones mediante la misma cuenta de Azure Cosmos DB. Por ejemplo, es posible tener una conexión CosmosClient mediante el modo de puerta de enlace y el punto de conexión de la puerta de enlace dedicada, mientras que otra usa el modo directo CosmosClient. En otras palabras, agregar una puerta de enlace dedicada no afecta a las formas existentes de conectarse a Azure Cosmos DB.
Si usa el SDK de .NET o Java, establezca el modo de conexión en el modo de puerta de enlace. Este paso no es necesario para los SDK de Python y Node.js, ya que no tienen opciones adicionales de conexión aparte del modo de puerta de enlace.

Nota:

Si usa la versión más reciente del SDK de .NET o Java, el modo de conexión predeterminado es el modo directo. Para usar la memoria caché integrada, debe invalidar este valor predeterminado.

Ajuste de la coherencia de la solicitud

Debe asegurarse de que la coherencia de la solicitud sea de sesión o final. Si no lo hace, la solicitud siempre omitirá la caché integrada. La manera más fácil de configurar una coherencia específica para todas las operaciones de lectura es establecerla en el nivel de cuenta. También puede configurar la coherencia en el nivel de solicitud; esto se recomienda si solo quiere que un subconjunto de las lecturas use la memoria caché integrada.

Nota:

Si usa el SDK de Python, debe establecer explícitamente el nivel de coherencia de cada solicitud. Tenga en cuenta que la configuración predeterminada del nivel de cuenta no se aplicará automáticamente.

Ajuste de MaxIntegratedCacheStaleness

Configure MaxIntegratedCacheStaleness, que es el tiempo máximo en el que está dispuesto a tolerar datos almacenados en caché obsoletos. Se recomienda establecer MaxIntegratedCacheStaleness lo más alto posible, ya que aumentará la probabilidad de que las consultas y las lecturas puntuales repetidas puedan ser aciertos de caché. Si establece MaxIntegratedCacheStaleness en 0, la solicitud de lectura nunca usará la caché integrada, independientemente del nivel de coherencia. Cuando no está configurado, el valor predeterminado de MaxIntegratedCacheStaleness es 5 minutos.

Nota

MaxIntegratedCacheStaleness se puede establecer como máximo en 10 años. En la práctica, este valor es la obsolescencia máxima y la caché puede restablecerse antes debido a los reinicios del nodo que pueden producirse.

El ajuste de MaxIntegratedCacheStaleness se admite en estas versiones de cada SDK:

SDK	Versiones compatibles
.NET SDK v3	>= 3.30.0
SDK de Java v4	>= 4.34.0
SDK de Node.js	>=3.17.0
SDK de Python	>=4.3.1

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(30) 
            }
        }
);

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setMaxIntegratedCacheStaleness(Duration.ofMinutes(30));
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

 const queryRequestOptions = {
   maxIntegratedCacheStalenessInMs: 1800000 };
 const querySpec = {
   query: "SELECT * from c"
 };
 const { resources: items } = await container.items
   .query(querySpec, queryRequestOptions)
   .fetchAll();

query = "SELECT * FROM c"
container.query_items(
    query=query,
    max_integrated_cache_staleness_in_ms=1800000
)

Omitir la caché integrada (versión preliminar)

Use la opción de solicitud BypassIntegratedCache para controlar qué solicitudes usan la caché integrada. Las escrituras, las lecturas puntuales y las consultas que omiten la caché integrada no usarán el almacenamiento de caché, lo que ahorra espacio para otros elementos. Las solicitudes que omiten la memoria caché siguen enrutadas a través de la puerta de enlace dedicada. Estas solicitudes se sirven desde el back-end y las RU de coste.

El paso de la memoria caché se admite en estas versiones de cada SDK:

SDK	Versiones compatibles
.NET SDK v3	>= 3.35.0-versión preliminar
SDK de Java v4	>= 4,49,0
SDK de Node.js	No compatible
SDK de Python	No compatible

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setIntegratedCacheBypassed(true);
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Comprobación de los resultados de la caché

Por último, puede reiniciar la aplicación y comprobar los aciertos integrados de la caché de las lecturas o consultas puntuales repetidas viendo si el cargo de la solicitud es 0. Una vez que haya modificado CosmosClient para poder usar el punto de conexión de la puerta de enlace dedicada, todas las solicitudes se enrutarán a través de esa puerta de enlace dedicada.

Para que una solicitud de lectura (esto es, una lectura o consulta de punto) use la caché integrada, deben cumplirse todos los criterios siguientes:

El cliente debe conectarse al punto de conexión de la puerta de enlace dedicada.
El cliente usa el modo de puerta de enlace (los SDK de Python y Node.js siempre usan el modo de puerta de enlace).
La coherencia de la solicitud debe establecerse en un estado de sesión o evento.

Nota:

¿Tiene comentarios sobre la caché integrada? Queremos conocerlos. No dude en compartir sus comentarios directamente con el equipo de ingeniería de Azure Cosmos DB: cosmoscachefeedback@microsoft.com.

Share via

Cómo configurar la caché integrada de Azure Cosmos DB

Requisitos previos

Aprovisionamiento de la puerta de enlace dedicada

Configuración de la memoria caché integrada

Ajuste de la coherencia de la solicitud

Ajuste de MaxIntegratedCacheStaleness

Omitir la caché integrada (versión preliminar)

Comprobación de los resultados de la caché

Pasos siguientes

Recursos adicionales