Utilisation de Upsert pour insérer ou mettre à jour un enregistrement

Article
04/26/2022
2 minutes de lecture

Vous pouvez réduire la complexité des scénarios d’intégration de données en utilisant le message UpsertRequest. En chargeant des données dans Microsoft Dataverse à partir d’un système externe, par exemple avec un scénario d’intégration de données en bloc, vous pouvez ne pas savoir si un enregistrement existe déjà dans Dataverse. Dans ce cas, vous ne savez pas si vous devez appeler une opération UpdateRequest ou CreateRequest. Vous devez alors commencer par rechercher un enregistrement pour déterminer s’il existe avant d’effectuer l’opération appropriée. Vous pouvez désormais réduire cette complexité et charger des données dans Dataverse plus efficacement en utilisant le nouveau message UpsertRequest (mise à jour ou insertion).

Utilisation de Upsert

Il est préférable d’utiliser UpsertRequest uniquement lorsque vous n’êtes pas sûr que l’enregistrement existe. C’est-à-dire lorsque vous ne savez pas si vous devez appeler une opération CreateRequest ou UpdateRequest. L’utilisation de UpsertRequest réduit les performances par rapport à CreateRequest. Si vous êtes certain que l'enregistrement n'existe pas, utilisez CreateRequest.

UpsertRequest contient une propriété nommée Target. Cette propriété contient l’instance d’entité qui sera utilisée dans une opération UpdateRequest ou CreateRequest. Elle inclut également toutes les colonnes requises par CreateRequest pour le type d’entité cible afin que l’enregistrement soit créé s’il n’existe pas.

Vous pouvez inspecter RecordCreated pour déterminer si l’enregistrement a été créé. RecordCreated sera true si l’enregistrement n’existait pas et a été créé. Il sera false si l’enregistrement existait déjà et a été mis à jour. Target sera une EntityReference pour l’enregistrement existant ou pour l’enregistrement qui a été créé.

Pour comprendre le fonctionnement de UpsertRequest, voir la section suivante.

Présentation du processus Upsert

Les étapes suivantes décrivent la logique de traitement lorsque UpsertRequest est reçu :

Envoyez UpsertRequest avec suffisamment de données pour une opération de création ou d'insertion.
Dataverse recherchera l’enregistrement ciblé par l’entité cible.
Si l'enregistrement existe :
1. Définissez la propriété ID de l'entité cible avec l'ID de l'enregistrement trouvé.
2. Appelez Update.
3. Définissez la propriété RecordCreated sur false.
4. Créez une EntityReference à partir de l'entité cible de la mise à jour comme valeur de Target.
5. Retournez UpsertResponse.
Si l’enregistrement n’existe pas :
1. Copiez toutes les valeurs de clé secondaire que la cible n’a pas déjà dans sa collection d’attributs, dans les attributs de l’entité cible.
2. Appelez Create.
3. Définissez la propriété RecordCreated sur true.
4. Créez une classe EntityReference à partir de l’entité cible. Le résultat de l’ID de la requête Create contient la valeur de Target.
5. Retournez UpsertResponse.
L’illustration suivante montre le processus qui se déroule lorsque la classe UpsertRequest est reçue.

Exemple de code

L’exemple Insérer ou mettre à jour un enregistrement à l’aide de Upsert de l’exemple ProductUpsertSample.cs contient la méthode ProcessUpsert suivante pour appliquer le message UpsertRequest du contenu d’un fichier XML pour créer des enregistrements ou mettre à jour des enregistrements existants.

public static void ProcessUpsert(CrmServiceClient service, String Filename)
{
    Console.WriteLine("Executing upsert operation.....");
    XmlTextReader tr = new XmlTextReader(Filename);
    XmlDocument xdoc = new XmlDocument();
    xdoc.Load(tr);
    XmlNodeList xnlNodes = xdoc.DocumentElement.SelectNodes("/products/product");

    foreach (XmlNode xndNode in xnlNodes)
    {
        String productCode = xndNode.SelectSingleNode("Code").InnerText;
        String productName = xndNode.SelectSingleNode("Name").InnerText;
        String productCategory = xndNode.SelectSingleNode("Category").InnerText;
        String productMake = xndNode.SelectSingleNode("Make").InnerText;

        //use alternate key for product
        Entity productToCreate = new Entity("sample_product", "sample_productcode", productCode);

        productToCreate["sample_name"] = productName;
        productToCreate["sample_category"] = productCategory;
        productToCreate["sample_make"] = productMake;
        var request = new UpsertRequest()
        {
            Target = productToCreate
        };

        try
        {
            // Execute UpsertRequest and obtain UpsertResponse. 
            var response = (UpsertResponse)service.Execute(request);
            if (response.RecordCreated)
                Console.WriteLine("New record {0} is created!", productName);
            else
                Console.WriteLine("Existing record {0} is updated!", productName);
        }

        // Catch any service fault exceptions that Microsoft Dynamics CRM throws.
        catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault>)
        {
            throw;
        }
    }
}

Voir aussi

Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
Définition de clés secondaires pour la table
Utilisation de clés secondaires

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Utilisation de Upsert pour insérer ou mettre à jour un enregistrement