.NET kullanarak NoSQL için Azure Cosmos DB'de öğe okuma

  • Makale

UYGULANANLAR: NOSQL

Azure Cosmos DB'deki öğeler, kapsayıcı içinde depolanan belirli bir varlığı temsil eder. NoSQL API'sinde bir öğe, benzersiz tanımlayıcıya sahip JSON biçimli verilerden oluşur.

Benzersiz tanımlayıcılara sahip öğeleri okuma

NoSQL için Azure Cosmos DB'deki her öğenin özelliği tarafından id belirtilen benzersiz bir tanımlayıcısı vardır. Kapsayıcı kapsamında iki öğe aynı benzersiz tanımlayıcıyı paylaşamaz. Ancak Azure Cosmos DB, bu öğenin hızlı bir şekilde okunmasını sağlamak için hem benzersiz tanımlayıcıyı hem de öğenin bölüm anahtarı değerini gerektirir. Yalnızca benzersiz tanımlayıcı kullanılabiliyorsa, öğeyi birden çok mantıksal bölümde aramak için daha az verimli bir sorgu gerçekleştirmeniz gerekir. Nokta okumaları ve sorguları hakkında daha fazla bilgi edinmek için bkz. Veri okuma için istek maliyetini iyileştirme.

Öğe okuma

Not

Bu makaledeki örneklerde , Product adlı verilerinizi temsil etmek için zaten bir C# türü tanımladığınız varsayılır:

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

Öğenin nokta okumasını gerçekleştirmek için aşağıdaki yöntemlerden birini çağırın:

Öğeyi zaman uyumsuz olarak okuma

Aşağıdaki örnek nokta, tek bir öğeyi zaman uyumsuz olarak okur ve sağlanan genel türü kullanarak seri durumdan çıkarılmış bir öğe döndürür:

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

Database.ReadItemAsync<> yöntemi bir öğeyi okur ve türünde ItemResponse<>bir nesnesi döndürür. ItemResponse<> türü, nesneyi genel türe dönüştürmek için örtük bir dönüştürme işleci içeren türünden devralırResponse<>. Örtük işleçler hakkında daha fazla bilgi edinmek için bkz. kullanıcı tanımlı dönüştürme işleçleri.

Alternatif olarak ItemResponse<> genel türünü döndürebilir ve kaynağı açıkça alabilirsiniz. Daha genel ItemResponse<> türü, temel alınan API işlemi hakkında yararlı meta veriler de içerir. Bu örnekte, bu işlem için istek birimi ücretiyle ilgili meta veriler RequestCharge özelliği kullanılarak toplanır.

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

Öğeyi zaman uyumsuz olarak akış olarak okuma

Bu örnek, bir öğeyi doğrudan veri akışı olarak okur:

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

yöntemi, Container.ReadItemStreamAsync içeriği seri durumdan çıkarmadan öğeyi olarak Stream döndürür.

Öğeleri doğrudan seri durumdan çıkarmayı planlamıyorsanız, akış API'lerini kullanmak, öğeyi doğrudan uygulamanızın bir sonraki bileşenine akış olarak devrederek performansı artırabilir. SDK'yı yüksek performanslı senaryolar için iyileştirme hakkında daha fazla ipucu için bkz. SDK performans ipuçları.

Birden çok öğeyi zaman uyumsuz olarak okuma

Bu örnekte, birden çok öğeyi aramak ve almak için benzersiz tanımlayıcı ve bölüm anahtarı çiftleri içeren tanımlama grubu listesi kullanılır:

// 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<> , sağladığınız benzersiz tanımlayıcıları ve bölüm anahtarlarını temel alan öğelerin listesini döndürür. Bu işlem, çok sayıda bağımsız öğe getirmek için deyimleri olan IN bir sorgudan daha iyi gecikme süresi gerçekleştirmeye yöneliktir.

Sonraki adımlar

Artık çeşitli öğeleri okuduğunuza göre, öğeleri sorgulamak için sonraki kılavuzu kullanın.

Sorgu öğeleri