Udostępnij za pośrednictwem

Odczytywanie elementu w usłudze Azure Cosmos DB for NoSQL przy użyciu platformy .NET

  • Artykuł

DOTYCZY: NoSQL

Elementy w usłudze Azure Cosmos DB reprezentują określoną jednostkę przechowywaną w kontenerze. W interfejsie API for NoSQL element składa się z danych w formacie JSON z unikatowym identyfikatorem.

Odczytywanie elementów z unikatowymi identyfikatorami

Każdy element w usłudze Azure Cosmos DB for NoSQL ma unikatowy identyfikator określony przez id właściwość. W zakresie kontenera dwa elementy nie mogą współdzielić tego samego unikatowego identyfikatora. Jednak usługa Azure Cosmos DB wymaga zarówno unikatowego identyfikatora, jak i wartości klucza partycji elementu w celu szybkiego odczytu tego elementu. Jeśli dostępny jest tylko unikatowy identyfikator, należy wykonać mniej wydajne zapytanie , aby wyszukać element w wielu partycjach logicznych. Aby dowiedzieć się więcej na temat odczytów i zapytań dotyczących punktów, zobacz Optymalizowanie kosztów żądań odczytu danych.

Odczytywanie elementu

Uwaga

W przykładach w tym artykule przyjęto założenie, że zdefiniowano już typ języka C#, aby reprezentować dane o nazwie Product:

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

Aby wykonać odczyt punktu elementu, wywołaj jedną z następujących metod:

Odczytywanie elementu asynchronicznie

Poniższy przykładowy punkt odczytuje asynchronicznie pojedynczy element i zwraca zdeserializowany element przy użyciu podanego typu ogólnego:

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

Metoda Database.ReadItemAsync<> odczytuje element i zwraca obiekt typu ItemResponse<>. Typ ItemResponse<> dziedziczy z Response<> typu, który zawiera niejawny operator konwersji, aby przekonwertować obiekt na typ ogólny. Aby dowiedzieć się więcej na temat operatorów niejawnych, zobacz Operatory konwersji zdefiniowane przez użytkownika.

Alternatywnie możesz zwrócić typ ogólny ItemResponse<> i jawnie pobrać zasób. Bardziej ogólny typ ItemResponse<> zawiera również przydatne metadane dotyczące podstawowej operacji interfejsu API. W tym przykładzie metadane dotyczące opłaty za jednostkę żądania dla tej operacji są zbierane przy użyciu właściwości 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;

Odczytywanie elementu jako strumienia asynchronicznie

W tym przykładzie element jest odczytywany bezpośrednio jako strumień danych:

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

Metoda Container.ReadItemStreamAsync zwraca element jako Stream element bez deserializacji zawartości.

Jeśli nie planujesz deserializacji elementów bezpośrednio, użycie interfejsów API strumienia może poprawić wydajność, przekazując element jako strumień bezpośrednio do następnego składnika aplikacji. Aby uzyskać więcej wskazówek dotyczących optymalizowania zestawu SDK pod kątem scenariuszy o wysokiej wydajności, zobacz Porady dotyczące wydajności zestawu SDK.

Odczytywanie wielu elementów asynchronicznie

W tym przykładzie lista krotek zawierających unikatowy identyfikator i pary kluczy partycji są używane do wyszukiwania i pobierania wielu elementów:

// 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<> Zwraca listę elementów na podstawie unikatowych identyfikatorów i kluczy partycji, które podajesz. Ta operacja ma na celu lepsze opóźnienie niż zapytanie z instrukcjami IN w celu pobrania dużej liczby niezależnych elementów.

Następne kroki

Teraz, gdy znasz różne elementy, użyj następnego przewodnika, aby wykonać zapytanie o elementy.

Elementy kwerend