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

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

1. Vaya a una cuenta de Azure Cosmos DB en Azure Portal y seleccione la pestaña Puerta de enlace dedicada.

   

2. 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.

   

3. 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 aplicación para usar la caché integrada

Al aprovisionar una puerta de enlace dedicada, se crea automáticamente una caché integrada. No es necesario conectar todas las aplicaciones que usan Azure Cosmos DB a la puerta de enlace dedicada si no necesitan usar la caché integrada. Agregar una puerta de enlace dedicada no afecta a las formas existentes de conectarse a 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.

Autenticación con el control de acceso basado en rol

La puerta de enlace dedicada usa los mismos permisos, definiciones de roles y asignaciones de roles que Azure Cosmos DB. Si ya tiene configurado el control de acceso basado en roles (RBAC) para las operaciones del plano de datos en su cuenta de Azure Cosmos DB, también puede utilizarlo para autenticarse en la puerta de enlace dedicada. Obtenga información sobre RBAC para las operaciones del plano de datos de Azure Cosmos DB.

Configure el CosmosClient estableciendo el punto de conexión de puerta de enlace dedicado, las credenciales y la configuración del modo de conectividad de puerta de enlace. Todos los puntos de conexión de puerta de enlace dedicados siguen el mismo patrón. Quite documents.azure.com del punto de conexión original y reemplácelo por sqlx.cosmos.azure.com. Una puerta de enlace dedicada siempre tendrá el mismo punto de conexión, incluso si quita y vuelve a aprovisionarlo.

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<dedicated-gateway-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential, new CosmosClientOptions { ConnectionMode = ConnectionMode.Gateway });

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<dedicated-gateway-endpoint>")
            .gatewayMode()
            .credential(credential);
            .buildClient();
    }
}

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<dedicated-gateway-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential})

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

Autenticación con cadenas de conexión

1. 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.

2. 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.

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.

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.

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

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

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:

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);

    const queryRequestOptions = {
      bypassIntegratedCache: true };
    const querySpec = {
      query: "SELECT * from c"
    };
    const { resources: items, requestCharge: queryCharge } = await container.items
      .query(querySpec, queryRequestOptions)
      .fetchAll();

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.

Pasos siguientes

• Preguntas más frecuentes sobre la caché integrada
• Información general de la caché integrada
• Puerta de enlace dedicada