Lectura de un elemento en Azure Cosmos DB for NoSQL mediante .NET

Artículo
08/15/2024

SE APLICA A: NoSQL

Los elementos de Azure Cosmos DB representan una entidad específica almacenada dentro de un contenedor. En la API para NoSQL, un elemento consta de datos con formato JSON con un identificador único.

Lectura de elementos con identificadores únicos

Cada elemento de Azure Cosmos DB for NoSQL tiene un identificador único especificado por la propiedad id. Dentro del ámbito de un contenedor, dos elementos no pueden compartir el mismo identificador único. Sin embargo, Azure Cosmos DB requiere tanto el identificador único como el valor de clave de partición de un elemento para realizar una lectura puntual rápida de ese elemento. Si solo está disponible el identificador único, tendría que realizar una consulta menos eficaz para buscar el elemento en varias particiones lógicas. Para más información sobre las lecturas puntuales y consultas, consulte el artículo sobre optimización del costo de solicitudes para leer datos.

Lectura de un elemento

Nota:

En los ejemplos de este artículo se supone que ya ha definido un tipo de C# para representar los datos denominados Product:

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Para realizar una lectura puntual de un elemento, use uno de los métodos siguientes:

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Lectura de un elemento de forma asincrónica

El siguiente ejemplo realiza una lectura puntual de un único elemento de forma asincrónica y devuelve un elemento deserializado mediante el tipo genérico proporcionado:

// Read existing item from container
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

El método Database.ReadItemAsync<> lee un elemento y devuelve un objeto de tipo ItemResponse<>. El tipo ItemResponse<> hereda del tipo Response<>, que contiene un operador de conversión implícito para convertir el objeto en el tipo genérico. Para más información sobre los operadores implícitos, consulte Operadores de conversión definidos por el usuario.

Como alternativa, puede devolver el tipo genérico ItemResponse<> y obtener explícitamente el recurso. El tipo ItemResponse<> más general también contiene metadatos útiles sobre la operación de API subyacente. En este ejemplo, los metadatos sobre el cargo de la unidad de solicitud para esta operación se recopilan mediante la propiedad RequestCharge.

// Read existing item from container
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get response metadata
double requestUnits = readResponse.RequestCharge;
HttpStatusCode statusCode = readResponse.StatusCode;

// Explicitly get item
Product readItemExplicit = readResponse.Resource;

Lectura de un elemento como flujo de forma asincrónica

En este ejemplo se lee un elemento como un flujo de datos directamente:

// Read existing item from container
using ResponseMessage readItemStreamResponse = await container.ReadItemStreamAsync(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get stream from response
using StreamReader readItemStreamReader = new(readItemStreamResponse.Content);

// (optional) Get stream content
string content = await readItemStreamReader.ReadToEndAsync();

El método Container.ReadItemStreamAsync devuelve el elemento como Stream sin deserializar el contenido.

Si no tiene previsto deserializar los elementos directamente, el uso de las API de flujo puede mejorar el rendimiento entregando el elemento como un flujo directamente al siguiente componente de la aplicación. Para obtener más sugerencias sobre cómo optimizar el SDK para escenarios de alto rendimiento, consulte el artículo sobre sugerencias de rendimiento del SDK.

Lectura de varios elementos de forma asincrónica

En este ejemplo, se usa una lista de tuplas que contienen pares de claves de partición e identificadores únicos para buscar y recuperar varios elementos:

// Create partition key object
PartitionKey partitionKey = new("gear-surf-surfboards");

// Create list of tuples for each item
List<(string, PartitionKey)> itemsToFind = new()
{
    ("68719518388", partitionKey),
    ("68719518381", partitionKey)
};

// Read multiple items
FeedResponse<Product> feedResponse = await container.ReadManyItemsAsync<Product>(
    items: itemsToFind
);

foreach (Product item in feedResponse)
{
    Console.WriteLine($"Found item:\t{item.name}");
}

Container.ReadManyItemsAsync<> devuelve una lista de elementos basados en los identificadores únicos y las claves de partición que proporcione. Esta operación está pensada para mejorar la latencia que una consulta con instrucciones IN para capturar un gran número de elementos independientes.

Pasos siguientes

Ahora que ha leído varios elementos, use la siguiente guía para consultar elementos.

Elementos de consulta

Compartir vía