Lire un élément dans Azure Cosmos DB for NoSQL à l’aide de .NET

  • Article

S’APPLIQUE À : NoSQL

Les éléments dans Azure Cosmos DB représentent une entité spécifique stockée dans un conteneur. Dans l’API pour NoSQL, un élément se compose de données au format JSON avec un identificateur unique.

Lecture d’éléments avec des identificateurs uniques

Chaque élément dans Azure Cosmos DB for NoSQL a un identificateur unique spécifié par la propriété id. Dans l’étendue d’un conteneur, deux éléments ne peuvent pas partager le même identificateur unique. Toutefois, Azure Cosmos DB nécessite à la fois l’identificateur unique et la valeur de clé de partition d’un élément pour effectuer une lecture de point rapide de cet élément. Si seul l’identificateur unique est disponible, vous devez effectuer une requête moins efficace pour rechercher l’élément sur plusieurs partitions logiques. Pour en savoir plus sur les lectures de points et les requêtes, consultez Optimiser le coût des requêtes pour la lecture des données.

Lire un élément

Notes

Les exemples de cet article partent du principe que vous avez déjà défini un type C# pour représenter vos données nommé Product :

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

Pour effectuer une lecture de point d’un élément, appelez l’une des méthodes suivantes :

Lire un élément de manière asynchrone

L’exemple suivant lit un élément unique de manière asynchrone et retourne un élément désérialisé à l’aide du type générique fourni :

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

La méthode Database.ReadItemAsync<> lit un élément et retourne un objet de type ItemResponse<>. Le type ItemResponse<> hérite du type Response<>, qui contient un opérateur de conversion implicite pour convertir l’objet en type générique. Pour en savoir plus sur les opérateurs implicites, consultez Opérateurs de conversion définis par l’utilisateur.

Vous pouvez également retourner le type générique ItemResponse<> et obtenir explicitement la ressource. Le type ItemResponse<> plus général contient également des métadonnées utiles sur l’opération d’API sous-jacente. Dans cet exemple, les métadonnées relatives aux frais d’unité de requête pour cette opération sont collectées à l’aide de la propriété 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;

Lire un élément en tant que flux de manière asynchrone

Cet exemple lit un élément en tant que flux de données directement :

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

La méthode Container.ReadItemStreamAsync retourne l’élément sous la forme d’un élément Stream sans désérialiser le contenu.

Si vous ne prévoyez pas de désérialiser directement les éléments, l’utilisation des API de flux peut améliorer les performances en transférant directement l’élément en tant que flux au composant suivant de votre application. Pour plus d’informations sur la façon d’optimiser le SDK pour des scénarios hautes performances, consultez Conseils sur les performances du SDK.

Lire plusieurs éléments de manière asynchrone

Dans cet exemple, une liste de tuples contenant des paires d’identificateurs uniques et de clés de partitions est utilisée pour rechercher et récupérer plusieurs éléments :

// 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<> retourne une liste d’éléments en fonction des identificateurs uniques et des clés de partition que vous fournissez. Cette opération est destinée à effectuer une meilleure latence qu’une requête avec IN des instructions pour extraire un grand nombre d’éléments indépendants.

Étapes suivantes

Maintenant que vous avez lu différents éléments, utilisez le guide suivant pour interroger des éléments.

Éléments de requête