Usar Upsert para inserir ou atualizar um registro

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

Você pode reduzir a complexidade envolvida nos cenários de integração de dados usando a mensagem UpsertRequest. Ao carregar dados de um sistema externo no Microsoft Dynamics 365, por exemplo, em um cenário de integração de dados em massa, talvez você não saiba se já existe um registro no Dynamics 365. Nesse caso, você não sabe se deve chamar uma operação UpdateRequest ou CreateRequest. Isso resulta na consulta do registro primeiro para determinar se ele existe antes de executar a operação adequada. Agora você pode reduzir essa complexidade e carregar dados no Dynamics 365 com mais eficiência usando a nova mensagem (Atualizar ou Inserir) UpsertRequest.

Neste tópico

Usando Upsert

Noções básicas sobre o processo de Upsert

Código de exemplo

Usando Upsert

É melhor usar UpsertRequest somente quando você não tiver certeza se o registro existe. Ou seja, quando você não sabe se deve chamar uma operação CreateRequest ou UpdateRequest. Há redução no desempenho ao usar UpsertRequest versus usar o CreateRequest. Se você tiver certeza de que o registro não existe, use CreateRequest.

O UpsertRequest inclui uma propriedade chamada Target. Essa propriedade contém a definição de entidade que será usada em uma operação UpdateRequest ou CreateRequest. Ela também inclui todos os atributos exigidos pelo CreateRequest para o tipo de entidade de destino a fim de que o registro possa ser criado, caso não exista.

Você pode inspecionar o RecordCreated para determinar se um registro foi criado. O RecordCreated será verdadeiro se o registro não existia e foi criado. Ele será falso se o registro já existia e foi atualizado. O Target será uma EntityReference para o registro que foi encontrado ou para o registro que foi criado.

O trecho de código a seguir mostra como UpsertRequest é usado.

Para saber como UpsertRequest funciona, consulte a seção a seguir.

Noções básicas sobre o processo de Upsert

As seguintes etapas descrevem a lógica de processamento quando um UpsertRequest é recebido:

1. Enviar UpsertRequest com dados suficientes para uma operação de criação ou inserção.

2. O Microsoft Dynamics 365 pesquisará o registro-alvo pela entidade de destino.

3. Se o registro existir:

   1. Defina a propriedade de ID da entidade de destino com a ID do registro localizado.

   2. Chame a atualização.

   3. Defina RecordCreated como false.

   4. Crie um EntityReference da entidade de destino da atualização como o valor de Target.

   5. Retorne o UpsertResponse.

4. Se o registro não existir:

   1. Copie todos os valores de chave alternativa nos atributos de entidade de destino.

   2. Chame Create.

   3. Defina RecordCreated como true.

   4. Crie um EntityReference do tipo de entidade de destino e o resultado de ID da solicitação Create como o valor de Target.

   5. Retorne o UpsertResponse.

A ilustração a seguir mostra o processo que se desdobra quando um UpsertRequest é recebido.

Código de exemplo

O exemplo Inserir ou atualizar um registro usando Upsert do arquivo ProductUpsertSample.cs contém o método ProcessUpsert a seguir para aplicar a mensagem UpsertRequest ao conteúdo de um arquivo XML para criar novos registros ou atualizar os existentes.

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();
    }

}

Confira Também

Usar o controle de alterações para sincronizar dados com sistemas externos
Definir chaves alternativas para uma entidade
Usar uma chave alternativa para criar um registro

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais