.NET を使って Azure Cosmos DB for NoSQL の項目を作成する

[アーティクル]
08/15/2024

適用対象: NoSQL

Azure Cosmos DB 内の項目は、コンテナー内に格納されている特定のエンティティを表します。 NoSQL 用 API では、項目は一意の識別子を含む JSON 形式のデータから成ります。

項目の一意識別子を作成する

一意識別子は、コンテナー内の項目を識別する個別の文字列です。 id プロパティが、新しい JSON ドキュメントを作成するときに必要な唯一のプロパティです。たとえば、次の JSON ドキュメントは Azure Cosmos DB で有効な項目です。

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

1 つのコンテナーのスコープ内で 2 つの項目が同じ一意識別子を共有することはできません。

重要

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

項目を作成するには、次のいずれかのメソッドを呼び出します。

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 パラメーターの一意識別子を使用して、既存の項目と競合が発生しているかどうかが判断され、その項目が適切に置き換えられます。

次のステップ

さまざまな項目を作成したので、次のガイドを使用して項目を読み取ります。

項目を読み取る

次の方法で共有