다음을 통해 공유


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

적용 대상: NoSQL

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

항목에 대한 고유 식별자 만들기

고유 식별자는 컨테이너 내의 항목을 식별하는 고유 문자열입니다. id 속성은 새 JSON 문서를 만들 때 유일한 필수 속성입니다. 예를 들어 이 JSON 문서는 Azure Cosmos DB의 유효한 항목입니다.

{
  "id": "unique-string-2309509"
}

컨테이너 범위 내에서 두 항목은 동일한 고유 식별자를 공유할 수 없습니다.

Important

id 속성은 대/소문자를 구분합니다. ID, Id, iD_id라는 임의의 JSON 속성으로 처리됩니다.

만들어지면 항목에 대한 URI는 다음과 같은 형식입니다.

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

URI를 사용하여 항목을 참조할 때 id 필드 대신 시스템 생성 리소스 식별자를 사용합니다. Azure Cosmos DB for NoSQL의 시스템 생성 항목 속성에 대한 자세한 내용은 항목의 속성을 참조하세요.

항목 만들기

참고 항목

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

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

또한 이 예제에서는 newItem이라는 Product 형식의 새 개체를 이미 만들었다고 가정합니다.

// Create new item and add to container
Product item = new(
    id: "68719518388",
    category: "gear-surf-surfboards",
    name: "Sunnox Surfboard",
    quantity: 8,
    sale: true
);

항목을 만들려면 다음 메서드 중 하나를 호출합니다.

비동기적으로 항목 만들기

다음 예제에서는 새 항목을 비동기적으로 만듭니다.

Product createdItem = await container.CreateItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

기존 항목의 고유 식별자와 충돌이 있는 경우 Container.CreateItemAsync<> 메서드가 예외를 throw합니다. 잠재적 예외에 대해 자세히 알아보려면 CreateItemAsync<> 예외를 참조하세요.

항목을 비동기적으로 바꾸기

다음 예제에서는 기존 항목을 비동기적으로 바꿉니다.

Product replacedItem = await container.ReplaceItemAsync<Product>(
    item: item,
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Container.ReplaceItemAsync<> 메서드는 item 매개 변수의 고유 식별자와 일치하도록 id 매개 변수에 제공된 문자열이 필요합니다.

항목을 비동기적으로 만들기 또는 바꾸기

다음 예제에서는 동일한 고유 식별자를 가진 항목이 이미 있는 경우 새 항목을 만들거나 기존 항목을 바꿉니다.

Product upsertedItem = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Container.UpsertItemAsync<> 메서드는 item 매개 변수의 고유 식별자를 사용하여 기존 항목과 충돌이 있는지 확인하고 항목을 적절하게 대체합니다.

다음 단계

이제 다양한 항목을 만들었으므로 다음 가이드를 사용하여 항목을 읽습니다.