Créer des documents

6 minutes

Pour créer un élément, nous devons d’abord créer une variable dans le code C# du type Product .

Product saddle = new()
{
    id = "027D0B9A-F9D9-4C96-8213-C8546C4AAE71",
    categoryId = "26C74104-40BC-4541-8EF5-9892F7F03D72",
    name = "LL Road Seat/Saddle",
    price = 27.12d,
    tags = new string[] 
    {
        "brown",
        "weathered"
    }
};

Supposons qu'il existe déjà une variable de type Microsoft.Azure.Cosmos.Container nommée container.

Nous pouvons appeler de façon asynchrone la méthode CreateItemAsync<> en passant le type Product et la nouvelle variable d’élément dans le constructeur.

await container.CreateItemAsync<Product>(saddle);

Cet appel de la méthode crée le nouvel élément, mais ne comprend aucune métadonnée sur le résultat de l’opération. Vous pouvez également stocker le résultat de l’opération dans une variable de type ItemResponse<>.

ItemResponse<Product> response = await container.CreateItemAsync<Product>(saddle);

HttpStatusCode status = response.StatusCode;
double requestUnits = response.RequestCharge;

Product item = response.Resource;

Si vous utilisez un bloc try-catch, vous pouvez gérer le type CosmosException , qui inclut une propriété StatusCode pour les valeurs de code d’état HTTP. Il existe quelques codes d’état HTTP courants que vous devez prendre en compte dans votre code d’application :

Code	Titre	Raison
400	Demande incorrecte	Quelque chose n’allait pas avec l’élément figurant dans le corps de la demande
403	Interdit	Le conteneur était probablement plein
409	Conflit	L’élément dans le conteneur avait probablement déjà un ID correspondant
413	RequestEntityTooLarge	L’élément dépasse la taille maximale de l’entité
429	Trop de requêtes	La demande actuelle dépasse le nombre maximal de RU/s provisionné pour le conteneur

Dans l’exemple suivant, nous gérons un scénario de conflit où l’élément existe déjà dans le conteneur et revenons à un bloc général de gestion des exceptions pour d’autres scénarios :

try
{
    await container.CreateItemAsync<Product>(saddle);
}
catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // Add logic to handle conflicting ids
}
catch(CosmosException ex) 
{
    // Add general exception handling logic
}

Pour créer un élément dans un conteneur Azure Cosmos DB, vous devez d’abord créer une instance de votre modèle d’élément. Dans Python, ce processus peut être effectué en définissant une instance de la classe Product .

saddle = Product(
        internal_id="2a7816bf-9a3c-4f33-b7d7-84efb3923538",
        name="Road Warrior Saddle",
        category_id="26C74104-40BC-4541-8EF5-9892F7F03D72",
        price=65.15,
        tags=["black", "cushioned", "leather"]
    ).to_dict()

Rappelez-vous que la classe Product a une to_dict méthode qui convertit l’instance en dictionnaire. Cette classe mappe également la internal_id propriété à la id propriété, dont Azure Cosmos DB a besoin.

Supposons qu’il existe déjà une variable de type azure.cosmos.Container nommé conteneur.

Vous pouvez utiliser la méthode create_item pour créer un élément dans le conteneur.

container.create_item(body=saddle)

Cet appel de la méthode crée le nouvel élément, mais il ne fournit pas de métadonnées sur le résultat de l’opération. Vous pouvez également capturer la réponse de l’opération dans une variable. La get_response_headers() méthode récupère les métadonnées relatives à l’opération, telles que le coût de la requête et la valeur ETag de l’élément créé, ce qui permet des scénarios de concurrence optimiste.

response = container.create_item(body=saddle)
# Get response headers
headers = response.get_response_headers()

# Retrieve the created item
item = response

# Extract metadata from headers
request_charge = headers.get('x-ms-request-charge')
etag = headers.get('etag')

# Output the metadata
print(f"Request Charge: {request_charge}")
print(f"etag: {etag}")

print(f"Item created: {item}")

x-ms-request-charge : Unités de requête (RU) utilisées par l’opération.
etag: valeur unique qui représente la version de l’élément.

Gestion des exceptions

Le Kit de développement logiciel (SDK) Python déclenche des exceptions pour différents scénarios. Vous pouvez gérer ces exceptions à l’aide d’un try-except bloc. L’exception CosmosHttpResponseError inclut des informations utiles telles que le code d’état HTTP. Voici quelques codes d’état HTTP courants que vous pouvez rencontrer :

Code	Titre	Raison
400	Demande incorrecte	Quelque chose n’allait pas avec l’élément figurant dans le corps de la demande
403	Interdit	Le conteneur était probablement plein
409	Conflit	L’élément dans le conteneur avait probablement déjà un ID correspondant
413	RequestEntityTooLarge	L’élément dépasse la taille maximale de l’entité
429	Trop de requêtes	La demande actuelle dépasse le nombre maximal de RU/s provisionné pour le conteneur

Voici un exemple de gestion de ces exceptions :

from azure.cosmos.exceptions import CosmosHttpResponseError

try:
    container.create_item(body=saddle)
except CosmosHttpResponseError as ex:
    if ex.status_code == 409:  # Conflict
        print("Conflict: Item with the same id already exists.")
    elif ex.status_code == 429:  # Too Many Requests
        print("Too many requests: Reduce request rate or increase RU/s provisioned.")
    elif ex.status_code == 400:  # Bad Request
        print("Bad request: Check the structure of the item being sent.")
    else:
        print(f"HTTP error occurred: Status code {ex.status_code}, message: {ex.message}")
except Exception as ex:
    print(f"An unexpected error occurred: {ex}")

Pour créer un élément, vous devez d’abord définir un objet qui représente vos données.

Définir l’élément

Définissez l’élément en JavaScript en tant qu’objet avec toutes les propriétés nécessaires. Par exemple, voici comment définir un élément de produit :

const saddle = new Product(
    "027D0B9A-F9D9-4C96-8213-C8546C4AAE72", // internalId
    "LL Road Seat/Saddle", // name
    "26C74104-40BC-4541-8EF5-9892F7F03D72", // categoryId
    27.12, // price
    ["brown", "weathered"] // tags
);

Cet objet a les propriétés suivantes :

internalId: identificateur unique de l’élément.
categoryId: propriété qui correspond au chemin de clé de partition du conteneur.
Autres propriétés, telles que name, priceet tags, qui décrivent l’élément.

Rappelez-vous que la classe Product a une toJSON() méthode qui convertit l’objet en chaîne JSON. Cette classe mappe également la internalId propriété à la id propriété, dont Azure Cosmos DB a besoin.

Créer l’élément

Supposons qu’il existe déjà une variable de type Container nommé conteneur. Vous pouvez utiliser la méthode items.create pour créer l’élément.

const { resource: item } = await container.items.create(saddle);

Cette méthode envoie une demande pour créer l’élément dans le conteneur Azure Cosmos DB.

Récupérer les métadonnées

La réponse renvoyée par la méthode items.create inclut des en-têtes qui fournissent des métadonnées utiles sur l’opération, telles que les frais de requête et la valeur ETag, permettant ainsi des scénarios optimistes de concurrence.

const { resource: item, headers } = await container.items.create(saddle);

const requestCharge = headers["x-ms-request-charge"];
const etag = headers.etag;

console.log(`Request Charge: ${requestCharge}`);
console.log(`etag: ${etag}`);
console.log("Item created:", item);

x-ms-request-charge : Unités de requête (RU) utilisées par l’opération.
etag: valeur unique qui représente la version de l’élément.

Gérer les erreurs

Lorsque vous créez un élément, des erreurs peuvent se produire, telles que des conflits ou des requêtes non valides. Utilisez un try-catch bloc pour gérer ces erreurs. Voici quelques codes d’état HTTP courants que vous pouvez rencontrer :

Code	Titre	Raison
400	Demande incorrecte	Quelque chose n’allait pas avec l’élément figurant dans le corps de la demande
403	Interdit	Le conteneur était probablement plein
409	Conflit	L’élément dans le conteneur avait probablement déjà un ID correspondant
413	RequestEntityTooLarge	L’élément dépasse la taille maximale de l’entité
429	Trop de requêtes	La demande actuelle dépasse le nombre maximal de RU/s provisionné pour le conteneur

try {
    const { resource: item, headers } = await container.items.create(saddle);
    console.log("Item created:", item);
} catch (error) {
    if (error.code === 409) {
        console.log(`Conflict: Item with the same id (${saddle.id}) already exists.`);
    } else if (error.code === 429) {
        console.log("Too many requests: Reduce request rate or increase RU/s provisioned.");
    } else if (error.code === 400) {
        console.log("Bad request: Check the structure of the item being sent.");
    } else {
        console.log(`An unexpected error occurred: ${error.message}`);
    }
}

Cette implémentation garantit que vous pouvez créer des éléments, récupérer des métadonnées pour les diagnostics et gérer correctement les erreurs.

Commentaires

Cette page a-t-elle été utile ?