Leggere un elemento in Azure Cosmos DB for NoSQL con .NET

Articolo
08/15/2024

SI APPLICA A: NoSQL

Gli elementi in Azure Cosmos DB rappresentano un'entità specifica archiviata all'interno di un contenitore. Nell'API per NoSQL, un elemento è costituito da dati formattati per JSON con un identificatore univoco.

Lettura di elementi con identificatori univoci

Ogni elemento in Azure Cosmos DB for NoSQL ha un identificatore univoco specificato dalla proprietà id. Nell'ambito di un contenitore, due elementi non possono condividere lo stesso identificatore univoco. Azure Cosmos DB richiede tuttavia sia l'identificatore univoco che il valore della chiave di partizione di un elemento per poter eseguire una rapida lettura di punti di tale elemento. Se è disponibile solo l'identificatore univoco, è necessario eseguire una query meno efficiente per cercare l'elemento in più partizioni logiche. Per altre informazioni sulle letture di punti e sulle query, consultare l'articolo su come ottimizzare il costo delle richieste per la lettura di dati.

Leggere un elemento

Nota

Gli esempi forniti in questo articolo presuppongono che sia già stato definito un tipo C# per rappresentare i dati denominati Prodotto:

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

Per eseguire una lettura di punti di un elemento, usare uno dei metodi seguenti:

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

Leggere un elemento in modo asincrono

L'esempio seguente esegue la lettura di punti di un singolo elemento in modo asincrono e restituisce un elemento deserializzato usando il tipo generico specificato:

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

Il metodo Database.ReadItemAsync<> legge un elemento e restituisce un oggetto di tipo ItemResponse<>. Il tipo ItemResponse<> eredita dal tipo Response<>, che contiene un operatore di conversione implicito per convertire l'oggetto nel tipo generico. Per altre informazioni sugli operatori impliciti, consultare gli operatori di conversione definiti dall'utente.

In alternativa, è possibile restituire il tipo genericoItemResponse<> e ottenere la risorsa in modo esplicito. Il tipo ItemResponse<> più generico contiene anche metadati utili per l'operazione API sottostante. In questo esempio, i metadati relativi all'addebito delle unità richiesta per questa operazione vengono raccolti usando la proprietà 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;

Leggere un elemento come flusso in modo asincrono

Questo esempio legge un elemento direttamente come flusso di dati:

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

Il metodo Container.ReadItemStreamAsync restituisce l'elemento come Stream senza deserializzare i contenuti.

Se non si prevede di deserializzare direttamente gli elementi, l'uso delle API di flusso può migliorare le prestazioni trasferendo l'elemento come flusso direttamente al componente successivo dell'applicazione. Per altri suggerimenti su come ottimizzare l'SDK per scenari con prestazioni elevate, consultare Suggerimenti per incrementare le prestazioni dell'SDK.

Leggere più elementi in modo asincrono

In questo esempio, viene usato un elenco di tuple contenenti coppie di chiave di partizione e identificatore univoco per cercare e recuperare più elementi:

// 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<> restituisce un elenco di elementi in base agli identificatori univoci e alle chiavi di partizione fornite. Questa operazione è progettata per eseguire una migliore prestazione in termini di latenza rispetto a una query con istruzioni IN per recuperare un numero elevato di elementi indipendenti.

Passaggi successivi

Dopo aver letto vari elementi, usare la guida successiva per eseguire query sugli elementi.

Eseguire query sugli elementi

Condividi tramite