Een item maken in Azure Cosmos DB for NoSQL met behulp van .NET

Artikel
08/15/2024

VAN TOEPASSING OP: NoSQL

Items in Azure Cosmos DB vertegenwoordigen een specifieke entiteit die is opgeslagen in een container. In de API voor NoSQL bestaat een item uit JSON-geformatteerde gegevens met een unieke id.

Een unieke id voor een item maken

De unieke id is een afzonderlijke tekenreeks die een item in een container identificeert. De id eigenschap is de enige vereiste eigenschap bij het maken van een nieuw JSON-document. Dit JSON-document is bijvoorbeeld een geldig item in Azure Cosmos DB:

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

Binnen het bereik van een container kunnen twee items niet dezelfde unieke id delen.

Belangrijk

De id eigenschap is hoofdlettergevoelig. Eigenschappen met de naam ID, Id, iDen _id worden behandeld als een willekeurige JSON-eigenschap.

Zodra de URI voor een item is gemaakt, heeft deze indeling:

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

Wanneer u naar het item verwijst met behulp van een URI, gebruikt u de door het systeem gegenereerde resource-id in plaats van het id veld. Zie eigenschappen van een item voor meer informatie over door het systeem gegenereerde itemeigenschappen in Azure Cosmos DB for NoSQL

Een item maken

Notitie

In de voorbeelden in dit artikel wordt ervan uitgegaan dat u al een C#-type hebt gedefinieerd om uw gegevens met de naam Product weer te geven:

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

In de voorbeelden wordt ook ervan uitgegaan dat u al een nieuw object van het type Product met de naam newItem hebt gemaakt:

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

Als u een item wilt maken, roept u een van de volgende methoden aan:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Een item asynchroon maken

In het volgende voorbeeld wordt asynchroon een nieuw item gemaakt:

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

De Container.CreateItemAsync<> methode genereert een uitzondering als er een conflict is met de unieke id van een bestaand item. Zie CreateItemAsync<> uitzonderingen voor meer informatie over mogelijke uitzonderingen.

Een item asynchroon vervangen

In het volgende voorbeeld wordt een bestaand item asynchroon vervangen:

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

Voor Container.ReplaceItemAsync<> de methode moet de opgegeven tekenreeks voor de id parameter overeenkomen met de unieke id van de item parameter.

Een item asynchroon maken of vervangen

In het volgende voorbeeld wordt een nieuw item gemaakt of een bestaand item vervangen als er al een item bestaat met dezelfde unieke id:

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

De Container.UpsertItemAsync<> methode gebruikt de unieke id van de item parameter om te bepalen of er een conflict is met een bestaand item en om het item op de juiste manier te vervangen.

Volgende stappen

Nu u verschillende items hebt gemaakt, gebruikt u de volgende handleiding om een item te lezen.

Een item lezen

Delen via