.NET을 사용하여 Azure Cosmos DB for NoSQL에서 항목 읽기

아티클
08/15/2024

적용 대상: NoSQL

Azure Cosmos DB의 항목은 컨테이너 내에 저장된 특정 엔터티를 나타냅니다. API for NoSQL에서 항목은 고유 식별자가 있는 JSON 형식 데이터로 구성됩니다.

고유 식별자가 있는 항목 읽기

Azure Cosmos DB for NoSQL의 모든 항목에는 id 속성으로 지정된 고유 식별자가 있습니다. 컨테이너 범위 내에서 두 항목은 동일한 고유 식별자를 공유할 수 없습니다. 그러나 Azure Cosmos DB는 해당 항목의 빠른 지점 읽기를 수행하기 위해 항목의 고유 식별자 및 파티션 키 값이 모두 필요합니다. 고유 식별자만 사용할 수 있는 경우 여러 논리 파티션에서 항목을 조회하려면 덜 효율적인 쿼리를 수행해야 합니다. 지점 읽기 및 쿼리에 대한 자세한 내용은 데이터 읽기에 대한 요청 비용 최적화를 참조하세요.

항목 읽기

참고 항목

이 문서의 예제에서는 Product라는 데이터를 나타내는 C# 형식을 이미 정의했다고 가정합니다.

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

항목의 지점 읽기를 수행하려면 다음 메서드 중 하나를 호출합니다.

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

비동기적으로 항목 읽기

다음 예제에서는 단일 항목에 대해 비동기적으로 지점 읽기를 수행하고 제공된 제네릭 형식을 사용하여 역직렬화된 항목을 반환합니다.

// 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 문을 사용하여 많은 독립 항목을 가져오는 쿼리보다 대기 시간 면에서 성능이 더 좋습니다.

다음 단계

이제 다양한 항목을 읽었으므로 다음 가이드를 사용하여 항목을 쿼리합니다.

쿼리 항목

다음을 통해 공유