Skapa ett objekt i Azure Cosmos DB for NoSQL med hjälp av .NET

  • Artikel

GÄLLER FÖR: NoSQL

Objekt i Azure Cosmos DB representerar en specifik entitet som lagras i en container. I API:et för NoSQL består ett objekt av JSON-formaterade data med en unik identifierare.

Skapa en unik identifierare för ett objekt

Den unika identifieraren är en distinkt sträng som identifierar ett objekt i en container. Egenskapen id är den enda obligatoriska egenskapen när du skapar ett nytt JSON-dokument. Det här JSON-dokumentet är till exempel ett giltigt objekt i Azure Cosmos DB:

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

Inom omfånget för en container kan två objekt inte dela samma unika identifierare.

Viktigt

Egenskapen id är skiftlägeskänslig. Egenskaper med namnet ID, Id, iDoch _id behandlas som en godtycklig JSON-egenskap.

När URI:n för ett objekt har skapats har den följande format:

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

När du refererar till objektet med hjälp av en URI använder du den systemgenererade resursidentifieraren i stället för fältet id . Mer information om systemgenererade objektegenskaper i Azure Cosmos DB för NoSQL finns i egenskaper för ett objekt

Skapa ett objekt

Anteckning

Exemplen i den här artikeln förutsätter att du redan har definierat en C#-typ som representerar dina data med namnet Product:

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

Exemplen förutsätter också att du redan har skapat ett nytt objekt av typen Produkt med namnet newItem:

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

Om du vill skapa ett objekt anropar du någon av följande metoder:

Skapa ett objekt asynkront

I följande exempel skapas ett nytt objekt asynkront:

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

Metoden Container.CreateItemAsync<> utlöser ett undantag om det finns en konflikt med den unika identifieraren för ett befintligt objekt. Mer information om potentiella undantag finns i CreateItemAsync<> undantag.

Ersätt ett objekt asynkront

I följande exempel ersätts ett befintligt objekt asynkront:

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

Metoden Container.ReplaceItemAsync<> kräver att den angivna strängen för parametern id matchar parameterns item unika identifierare.

Skapa eller ersätta ett objekt asynkront

I följande exempel skapas ett nytt objekt eller ett befintligt objekt ersätts om ett objekt redan finns med samma unika identifierare:

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

Metoden Container.UpsertItemAsync<> använder den unika identifieraren för parametern item för att avgöra om det finns en konflikt med ett befintligt objekt och för att ersätta objektet på rätt sätt.

Nästa steg

Nu när du har skapat olika objekt använder du nästa guide för att läsa ett objekt.

Läsa ett objekt