Vytvoření položky ve službě Azure Cosmos DB for NoSQL pomocí .NET

Článek
08/15/2024

PLATÍ PRO: NoSQL

Položky ve službě Azure Cosmos DB představují konkrétní entitu uloženou v kontejneru. V rozhraní API pro NoSQL se položka skládá z dat ve formátu JSON s jedinečným identifikátorem.

Vytvoření jedinečného identifikátoru pro položku

Jedinečný identifikátor je jedinečný řetězec, který identifikuje položku v kontejneru. Tato id vlastnost je jedinou povinnou vlastností při vytváření nového dokumentu JSON. Tento dokument JSON je například platná položka ve službě Azure Cosmos DB:

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

V rámci oboru kontejneru nemůžou dvě položky sdílet stejný jedinečný identifikátor.

Důležité

U id vlastnosti se rozlišují malá a velká písmena. Vlastnosti s názvem ID, iDIda _id budou považovány za libovolnou vlastnost JSON.

Po vytvoření je identifikátor URI položky v tomto formátu:

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

Při odkazování na položku pomocí identifikátoru URI použijte místo pole identifikátor id prostředků vygenerovaný systémem. Další informace o systémově generovaných vlastnostech položek ve službě Azure Cosmos DB for NoSQL najdete v tématu Vlastnosti položky.

Vytvoření položky

Poznámka:

Příklady v tomto článku předpokládají, že jste již definovali typ jazyka C#, který představuje vaše data s názvem Product:

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

Příklady také předpokládají, že jste již vytvořili nový objekt typu Product s názvem newItem:

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

Chcete-li vytvořit položku, zavolejte jednu z následujících metod:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Asynchronní vytvoření položky

Následující příklad vytvoří novou položku asynchronně:

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

Metoda Container.CreateItemAsync<> vyvolá výjimku, pokud dojde ke konfliktu s jedinečným identifikátorem existující položky. Další informace o potenciálních výjimkách najdete v tématu CreateItemAsync<> Výjimky.

Asynchronní nahrazení položky

Následující příklad nahrazuje existující položku asynchronně:

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

Metoda Container.ReplaceItemAsync<> vyžaduje zadaný řetězec, aby id parametr odpovídal jedinečnému identifikátoru parametru item .

Asynchronní vytvoření nebo nahrazení položky

Následující příklad vytvoří novou položku nebo nahradí existující položku, pokud již položka existuje se stejným jedinečným identifikátorem:

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

Metoda Container.UpsertItemAsync<> použije jedinečný identifikátor parametru item k určení, jestli došlo ke konfliktu s existující položkou a aby položku odpovídajícím způsobem nahradila.

Další kroky

Když jste teď vytvořili různé položky, přečtěte si položku pomocí další příručky.

Čtení položky

Sdílet prostřednictvím