Чтение элемента в Azure Cosmos DB для NoSQL с помощью .NET

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

Элементы в Azure Cosmos DB представляют определенную сущность, хранящуюся в контейнере. В API для NoSQL элемент состоит из данных в формате JSON с уникальным идентификатором.

Считывание элементов с уникальными идентификаторами

Каждый элемент в Azure Cosmos DB для NoSQL имеет уникальный идентификатор, заданный свойством id . В области контейнера два элемента не могут совместно использовать один и тот же уникальный идентификатор. Но Azure Cosmos DB нужны оба уникальных идентификатора и значение ключа секции элемента для выполнения операции точечного чтения для такого элемента. Если доступен только один уникальный идентификатор, вам придется выполнить менее эффективный запрос, чтобы выполнить поиск элемента в нескольких логических секциях. Дополнительные сведения об операциях точечного чтения и запросах см. в статье Оптимизация затрат на обработку запросов в Azure Cosmos DB.

Чтение элемента

Примечание

В примерах в этой статье предполагается, что вы уже определили тип C# для представления ваших данных с именем Product.

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

Чтобы выполнить операцию точечного чтения для элемента, вызовите один из следующих методов:

Асинхронное считывание элемента

В следующем примере точка асинхронно считывает один элемент и возвращает десериализованный элемент с помощью предоставленного универсального типа:

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

Метод Database.ReadItemAsync<> считывает элемент и возвращает объект типа ItemResponse<>. Тип ItemResponse<> наследуется из типа Response<>, который содержит неявный оператор преобразования для преобразования объекта в универсальный тип. Дополнительные сведения о неявных операторах см. в статье Операторы пользовательского преобразования.

Кроме того, можно вернуть универсальный тип ItemResponse<> и явно получить ресурс. Более универсальный тип ItemResponse<> также содержит полезные метаданные о базовой операции API. В этом примере метаданные об оплате за единицу запроса для этой операции собираются с помощью свойства 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;

Асинхронное чтение элемента в виде потока

В этом примере элемент считывается напрямую в виде потока данных:

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

Метод Container.ReadItemStreamAsync возвращает элемент в виде Stream без десериализации содержимого.

Если вы не планируете десериализировать элементы напрямую, использование API потоков может повысить производительность благодаря передаче элемента в виде потока непосредственно следующему компоненту приложения. Дополнительные советы по оптимизации пакета SDK для сценариев с высокой производительностью см. в советах по повышению производительности пакета SDK.

Асинхронное считывание нескольких элементов

В этом примере для поиска и извлечения нескольких элементов используется список кортежей, содержащих уникальные идентификаторы и пары ключей секций:

// 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<> возвращает список элементов на основе предоставленных вами уникальных идентификаторов и ключей секций. Эта операция предназначена для лучшей задержки, чем запрос с IN инструкциями для получения большого количества независимых элементов.

Дальнейшие действия

Теперь, когда вы считали различные элементы, воспользуйтесь следующим руководством для отправки запросов к элементам.

Элементы запроса