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

Статья
05/23/2023

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

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

Создание уникального идентификатора для элемента

Уникальный идентификатор — это отдельная строка, которая идентифицирует элемент в контейнере. Свойство id является единственным обязательным свойством при создании нового документа JSON. Например, этот документ JSON является допустимым элементом в Azure Cosmos DB.

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

В области контейнера два элемента не могут совместно использовать один и тот же уникальный идентификатор.

Важно!

В свойстве 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 для NoSQL, см. в статье Свойства элемента.

Создание элемента

Примечание

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

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

В примерах также предполагается, что вы уже создали новый объект типа Product с именем newItem.

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

Для создания элемента вызовите один из следующих методов:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Создание элемента асинхронно

В примере ниже показано, как создать новый элемент асинхронно.

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

Метод Container.CreateItemAsync<> выдаст исключение, если возникнет конфликт с уникальным идентификатором существующего элемента. Дополнительные сведения о возможных исключениях см. в разделе Исключения CreateItemAsync<>.

Замена элемента асинхронно

В примере ниже показано, как заменить существующий элемент асинхронно.

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

Метод Container.ReplaceItemAsync<> требует, чтобы предоставленная строка для параметра id соответствовала уникальному идентификатору параметра item.

Создание или замена элемента асинхронно

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

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

Метод Container.UpsertItemAsync<> будет использовать уникальный идентификатор параметра item, чтобы определить, есть ли конфликт с существующим элементом, и соответствующим образом заменить элемент.

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

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

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

Share via