Habilitación de la caché integrada

Completado

Habilitación de la caché integrada

La habilitación de la caché integrada se realiza en dos pasos principales:

• Creación de una puerta de enlace dedicada en la cuenta de Azure Cosmos DB for NoSQL
• Actualización del código del SDK para usar la puerta de enlace para las solicitudes

Creación de una puerta de enlace dedicada

En primer lugar, debe aprovisionar una puerta de enlace dedicada en su cuenta. Esta acción se puede realizar mediante el portal y el panel Dedicated Gateway (Puerta de enlace dedicada).

Como parte del proceso de aprovisionamiento, se le pedirá que configure el número de instancias de puerta de enlace y una SKU. Esta configuración determina el número de nodos y el tamaño de proceso y memoria de cada nodo de la puerta de enlace. El número de nodos y SKU se puede modificar más adelante a medida que aumenta la cantidad de datos que necesita almacenar en caché.

Una vez aprovisionada la nueva puerta de enlace, puede obtener el punto de conexión de la puerta de enlace.

Nota:

El punto de conexión de puerta de enlace es distinto del punto de conexión típico que se usa con un cliente de Azure Cosmos DB for NoSQL.

Actualización del código del SDK de .NET

Para que el cliente del SDK de .NET use la caché integrada, debe asegurarse de que se cumplen tres condiciones:

• El cliente usa el punto de conexión de puerta de enlace dedicado en lugar del punto de conexión típico
• El cliente está configurado para usar el modo Puerta de enlace en lugar del modo de conectividad Directo predeterminado.
• El nivel de coherencia del cliente debe establecerse en sesión o posible.

En primer lugar, asegúrese de que el punto de conexión está establecido en el punto de conexión de la puerta de enlace dedicada. Normalmente, Azure Cosmos DB for NoSQL para puntos de conexión tiene el formato de <cosmos-account-name>.documents.azure.com. Para la puerta de enlace dedicada, el punto de conexión tiene la estructura de <cosmos-account-name>.sqlx.cosmos.azure.com.

En lugar de usar una clave de cuenta, configure el SDK para que use una identidad administrada para la autenticación. A continuación se muestra el código actualizado.

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

string endpoint = "https://<cosmos-account-name>.sqlx.cosmos.azure.com/";

CosmosClientOptions options = new()
{
    ConnectionMode = ConnectionMode.Gateway,
    ConsistencyLevel = ConsistencyLevel.Session // or ConsistencyLevel.Eventual
};

// Use DefaultAzureCredential to authenticate with managed identity.
CosmosClient client = new(endpoint, new DefaultAzureCredential(), options);

Nota:

Asegúrese de que la aplicación tiene habilitada una identidad administrada y de que a la identidad administrada se le ha concedido el rol Colaborador de datos integrado de Cosmos DB en la cuenta de Azure Cosmos DB.

Configuración de operaciones de lectura de punto

Para configurar una operación de lectura de punto para usar la caché integrada, debe crear un objeto de tipo ItemRequestOptions. En este objeto, puede establecer manualmente la propiedad ConsistencyLevel en ConsistencyLevel.Session o ConsistencyLevel.Eventual. A continuación, puede usar la variable options en la invocación del método ReadItemAsync.

string id = "9DB28F2B-ADC8-40A2-A677-B0AAFC32CAC8";
PartitionKey partitionKey = new("56400CF3-446D-4C3F-B9B2-68286DA3BB99");

ItemRequestOptions requestOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Session
};

ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey, requestOptions: requestOptions);

Para observar el uso de RU, utilice la propiedad RequestCharge de la variable de respuesta. La primera invocación de esta operación de lectura usa el número esperado de unidades de solicitud. En este ejemplo, sería una RU para una operación de lectura puntual. Las solicitudes posteriores no usan ninguna unidad de solicitud, ya que los datos se extraen de la memoria caché hasta que expiren.

Console.WriteLine($"Request charge:\t{response.RequestCharge:0.00} RU/s");

Configuración de consultas

Para configurar una consulta para usar la caché integrada, cree un objeto de tipo QueryRequestOptions. En este objeto, también debe cambiar manualmente el nivel de coherencia. A continuación, pase la variable options a la invocación del método GetItemQueryIterator.

string sql = "SELECT * FROM products";
QueryDefinition query = new(sql);

QueryRequestOptions queryOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Eventual
};

FeedIterator<Product> iterator = container.GetItemQueryIterator<Product>(query, requestOptions: queryOptions);

Para observar el uso de RU, también puede obtener la propiedad RequestCharge de cada objeto FeedResponse asociado a cada página de resultados. Si agrega los cargos de solicitud, obtendrá el cargo total de la solicitud para toda la consulta. Al igual que con las lecturas puntuales, la primera consulta usa el número típico de unidades de solicitud. Las consultas adicionales no usan unidades de solicitud hasta que los datos expiren en la memoria caché.

double totalRequestCharge = 0;
while(iterator.HasMoreResults)
{
    FeedResponse<Product> response = await iterator.ReadNextAsync();
    totalRequestCharge += response.RequestCharge;
    Console.WriteLine($"Request charge:\t\t{response.RequestCharge:0.00} RU/s");
}

Console.WriteLine($"Total request charge:\t{totalRequestCharge:0.00} RU/s");