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

 

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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 Dynamics 365 à 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 Dynamics 365. 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 Dynamics 365 plus efficacement en utilisant le nouveau message UpsertRequest (mise à jour ou insertion).

Contenu de la rubrique

Utilisation de Upsert

Présentation du processus Upsert

Exemple de code

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 la définition d'entité qui sera utilisée dans une opération UpdateRequest ou CreateRequest. Elle inclut également tous les attributs requis 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 :

1. Envoyez UpsertRequest avec suffisamment de données pour une opération de création ou d'insertion.

2. Microsoft Dynamics 365 recherchera l'enregistrement ciblé par l'entité cible.

3. 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.

4. Si l'enregistrement n'existe pas :

   1. Copiez les valeurs des clés secondaires dans les attributs d'entités cibles.

   2. Appelez Create.

   3. Définissez la propriété RecordCreated sur true.

   4. Créez une classe EntityReference à partir du type d'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 de code Insérer ou mettre à jour un enregistrement à l'aide de Upsert du fichier ProductUpsertSample.cs contient la méthode ProcessUpsert suivante pour appliquer le message UpsertRequest au contenu d'un fichier XML pour créer des enregistrements ou mettre à jour des enregistrements existants.

public void ProcessUpsert(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;
        UpsertRequest request = new UpsertRequest()
        {
            Target = productToCreate
        };

        try
        {
            // Execute UpsertRequest and obtain UpsertResponse. 
            UpsertResponse response = (UpsertResponse)_serviceProxy.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;
        }

    }
    // Prompts to view the sample_product entity records.
    // If you choose "y", IE will be launched to display the new or updated records.
    if (PromptForView())
    {
        ViewEntityListInBrowser();
    }

}

Voir aussi

Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
Définition de clés secondaires pour une entité
Utilisation d'une clé secondaire pour créer un enregistrement

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright