Partager via

Créer un élément dans Azure Cosmos DB for NoSQL à l’aide de .NET

  • Article

S’APPLIQUE À : NoSQL

Les éléments dans Azure Cosmos DB représentent une entité spécifique stockée dans un conteneur. Dans l’API pour NoSQL, un élément se compose de données au format JSON avec un identificateur unique.

Créer un identificateur unique pour un élément

L’identificateur unique est une chaîne distincte qui identifie un élément au sein d’un conteneur. La propriété id est la seule propriété requise lors de la création d’un document JSON. Par exemple, ce document JSON est un élément valide dans Azure Cosmos DB :

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

Dans l’étendue d’un conteneur, deux éléments ne peuvent pas partager le même identificateur unique.

Important

La propriété id respecte la casse. Des propriétés nommées ID, Id, iD et _id seront traitées comme une propriété JSON arbitraire.

Une fois créé, l’URI d’un élément est au format suivant :

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

Lorsque vous référencez l’élément à l’aide d’un URI, utilisez l’identificateur de ressource généré par le système au lieu du champ id. Pour plus d’informations sur les propriétés d’élément générées par le système dans Azure Cosmos DB for NoSQL, consultez Propriétés d’un élément.

Créer un élément

Notes

Les exemples de cet article partent du principe que vous avez déjà défini un type C# pour représenter vos données nommé Product :

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

Les exemples partent également du principe que vous avez déjà créé un objet de type Product nommé newItem :

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

Pour créer un élément, appelez l’une des méthodes suivantes :

Créer un élément de façon asynchrone

L’exemple suivant crée un élément de manière asynchrone :

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

La méthode Container.CreateItemAsync<> lève une exception s’il existe un conflit avec l’identificateur unique d’un élément existant. Pour en savoir plus sur les exceptions potentielles, consultez CreateItemAsync<>Exceptions.

Remplacer un élément de façon asynchrone

L’exemple suivant remplace un élément existant de façon asynchrone :

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

La méthode Container.ReplaceItemAsync<> impose que la chaîne fournie pour le paramètre id corresponde à l’identificateur unique du paramètre item.

Créer ou remplacer un élément de façon asynchrone

L’exemple suivant crée un élément ou remplace un élément existant s’il existe déjà un élément avec le même identificateur unique :

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

La méthode Container.UpsertItemAsync<> utilise l’identificateur unique du paramètre item pour déterminer s’il existe un conflit avec un élément existant et pour remplacer l’élément de manière appropriée.

Étapes suivantes

Maintenant que vous avez créé différents éléments, utilisez le guide suivant pour lire un élément.

Lire un élément