Partilhar via

Detalhes de esquema para criar um modelo de mapeamento de metadados

Aplica-se a: Dynamics 365 Customer Service e Dynamics 365 Contact Center—apenas independente

Este artigo descreve os detalhes do esquema necessários para mapear informações de provedores de dados externos para as entidades do artigo de conhecimento e como você pode preparar seu próprio arquivo JSON de mapeamento de esquema usando vários campos e atributos.

Campos

A tabela a seguir lista os campos e detalhes de campo que você deve usar em seu esquema JSON.

Nome do campo Definição Obrigatório valor
Nome Nome da definição de campo Não Uma cadeia de caracteres que indica o nome do campo.
UniqueTargetFieldName O identificador exclusivo ou a chave alternativa da entidade do artigo de conhecimento. Normalmente, esse campo é o ID no lado do provedor de conteúdo. Sim Uma cadeia de caracteres que indica o nome do campo. Você pode definir o valor como "msydn_externalreferenceid"
ContentTargetFieldName O valor do campo não deve ser alterado. Sim Defina o valor como "content".
ApiPathLeafName O valor do campo não deve ser alterado. Sim Defina o valor como "knowledgearticles".
Lista<Definições de Campos> É uma lista de definições de campo. Sim Um conjunto de definições para os campos. Consulte a tabela a seguir para obter a lista de campos suportados para definir definições de campo.

Definições de campo

A tabela a seguir lista os atributos obrigatórios e opcionais que você pode usar em seu esquema de mapeamento de metadados.

Nome do campo Definição Obrigatório valor
TargetFieldName O nome do campo lógico do atributo de destino na entidade do artigo de conhecimento. Sim Qualquer cadeia de caracteres que indique o nome do campo de destino
TargetFieldType Indica o tipo do campo de destino. Sim Uma cadeia de caracteres que indica o tipo do campo.
DocFieldSource Indica como o valor do campo de origem é identificado e resolvido em tempo de execução Sim Defina o valor para um dos seguintes tipos de origem:
  • Regex
  • Meta
  • Constante
  • Endereço URL
  • Document
Para saber mais sobre esses tipos de dados, consulte a seção Tipos de fonte de campo a seguir.
DocFieldPattern Indica a natureza do campo de destino a ser obtido. Não Defina esse valor com base no valor DocFieldSource. Veja os exemplos abaixo sobre como definir DocFieldPatterns.
MaxLength É o comprimento máximo da cadeia de caracteres que pode ser armazenada no campo de destino. Não. Pode ser usado quando o atributo TargetFieldType é do tipo String Int
UseRegexCapture Armazena o padrão regex que pode ser aplicado à URL. Não. Pode ser usado quando o atributo TargetFieldType é do tipo String e o atributo DocFieldSource é do tipo Url. URL ou Cadeia de Carateres.

Tipos de fonte de campo

Os dados nos provedores de pesquisa externos podem ser definidos para qualquer um dos seguintes tipos de fonte de campo:

  • Regex: Use para indicar um tipo de expressão regular de dados.
  • Meta: Use para indicar que o valor do campo de destino é obtido de uma <metatag> no artigo de origem
  • Constante: Use para definir um valor estático para o campo de destino.
  • Url: Use para indicar a URL do documento de origem externa.
  • Documento: Use para indicar o conteúdo HTML do artigo.

Considerações para criar seu próprio modelo de mapeamento de metadados

Ao desenvolver seu próprio esquema de mapeamento, você deve ter certeza de configurar alguns campos obrigatórios e definir valores padrão para algumas definições de campo.

Seu modelo de mapeamento deve incluir:

  • Os campos UniqueTargetFieldName, ContentTargetFieldName e ApiPathLeafName . Esses campos devem ser definidos com seus valores obrigatórios da seguinte maneira:

    • Defina o UniqueTargetFieldName como o campo msdyn_externalreferenceid pré-definido ou como um campo personalizado. Se estiver a utilizar um campo personalizado, certifique-se de que adiciona o campo como uma chave alternativa. Mais informações: Defina chaves alternativas para referenciar Dynamics 365 registos.
    • Inclua o campo ContentTargetFieldName e defina seu valor como "content".
    • Inclua o campo ApiPathLeafName e defina seu valor como "knowledgearticles".
    • Certifique-se de fornecer mapeamentos para os campos UniqueTargetField e ContentTargetField na lista FieldDefinitions .

    Seu esquema de mapeamento teria a seguinte aparência:

    
  {
    "Name": "{To be filled by you}",
    "UniqueTargetFieldName": "msdyn_externalreferenceid",
    "ContentTargetFieldName": "content",
    "ApiPathLeafName": "knowledgearticles"
    "FieldDefinitions": []
  }

  • Você deve incluir a lista FieldDefinitions abaixo e preencher seus atributos, como FieldUse, DocFieldSource, TargetFieldName e TargetFieldType com valores padrão. Certifique-se de incluir os seguintes campos e atributos com seus valores, "as-is", em seu modelo. No entanto, os campos Docfieldsource e Docfieldpattern para os campos de título e valor de conteúdo podem ser definidos por você como Regex, Meta, Document, Constant ou Url.

    
  {
    "FieldUse": "Create",
    "DocFieldSource": "ArticlePublicNumber",
    "TargetFieldName": "articlepublicnumber",
    "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Constant",
     "DocFieldPattern": "true",
     "TargetFieldName": "msdyn_isingestedarticle",
     "TargetFieldType": "Boolean"
  },
  {
     "DocFieldSource": "Url",
     "TargetFieldName": "msdyn_ingestedarticleurl",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "DataProvider",
     "TargetFieldName": "msdyn_integratedsearchproviderid@odata.bind",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Regex",
     "DocFieldPattern": "<title>(.*?)</title>",
     "TargetFieldName": "title",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Url",
     "TargetFieldName": "msdyn_externalreferenceid",
     "TargetFieldType": "String",
     "UseRegexCapture": "^https://.*?/(.*?)/.*/.*?([0-9A-F]{8}[-](?:[0-9A-F]{4}[-]){3}[0-9A-F]{12})$"
 }, 
  {
     "DocFieldSource": "Document",
     "TargetFieldName": "content",
     "TargetFieldType": "String"
  }

  • Depois de listar os campos obrigatórios e as informações de atributo, você pode incluir quaisquer mapeamentos de metadados adicionais e definir seus próprios valores personalizados para eles. Por exemplo, você pode incluir um tipo Meta de DocFieldSource e definir quaisquer valores personalizados para o atributo, da seguinte maneira.

    
   {
     "DocFieldSource": "Meta",
     "DocFieldPattern": "description",
     "TargetFieldName": "description",
     "TargetFieldType": "String",
     "MaxLength": 155
    }

Modelo de mapeamento de metadados de exemplo

Você pode usar o seguinte exemplo JSON de mapeamento de metadados como modelo para criar seu próprio modelo de mapeamento personalizado.


   {
     "Name": "Integrated Search Data Provider Name",
     "UniqueTargetFieldName": "msdyn_externalreferenceid",
     "ContentTargetFieldName": "content",
     "ApiPathLeafName": "knowledgearticles",
     "FieldDefinitions": [
     {
       "FieldUse": "Create",
       "DocFieldSource": "ArticlePublicNumber",
       "TargetFieldName": "articlepublicnumber",
       "TargetFieldType": "String"
      },
      {
        "DocFieldSource": "Constant",
        "DocFieldPattern": "true",
        "TargetFieldName": "msdyn_isingestedarticle",
        "TargetFieldType": "Boolean"
      },
      {
        "DocFieldSource": "Url",
        "TargetFieldName": "msdyn_ingestedarticleurl",
        "TargetFieldType": "String"  
      },
      {
        "DocFieldSource": "DataProvider",
        "TargetFieldName": "msdyn_integratedsearchproviderid@odata.bind",
        "TargetFieldType": "String"
      },
      {
        "DocFieldSource": "Regex",
        "DocFieldPattern": "<title>(.*?)</title>",
        "TargetFieldName": "title",
        "TargetFieldType": "String"
       },
       {
          "DocFieldSource": "Meta",
          "DocFieldPattern": "description",
          "TargetFieldName": "description",
          "TargetFieldType": "String",
          "MaxLength": 155
       },
       {
          "DocFieldSource": "Document",
          "TargetFieldName": "content",
          "TargetFieldType": "String"
        },
        {
          "DocFieldSource": "Url",
          "TargetFieldName": "msdyn_externalreferenceid",
          "TargetFieldType": "String",
          "UseRegexCapture": "^https://.*?/(.*?)/.*/.*?([0-9A-F]{8}[-](?:[0-9A-F]{4}[-]){3}[0-9A-F]{12})$"
        }
    ]
 }

Transformar, mapear dados de origem externa para campos de conhecimento

Ao mapear informações de fornecedores de dados externos para entidades de artigos de conhecimento, se o valor de origem for de um tipo de dados diferente, terá de transformar o valor antes de o mapear para o atributo de conhecimento de destino. Pode criar um plug-in e registá-lo em mensagens Create e Update, de modo a que os atributos do artigo de conhecimento de destino tenham valores alinhados com os artigos dos fornecedores externos.

Para transformar e mapear os valores de origem, efetue os seguintes passos:

  1. Crie um campo personalizado na entidade KnowledgeArticle. Mais informações em Como criar e editar colunas.
  2. Mapeie o valor de origem externa necessário para o campo personalizado recém-criado. Saiba mais em Configurar mapeamento de esquema de artigos de conhecimento (pré-visualização) Este é um mapeamento temporário a partir do qual o seu plug-in pega no valor de origem.
  3. Criar um plug-in. Saiba mais em Criar um projeto de plug-in.
  4. Pode escrever o seu próprio código para converter o valor de origem externa e mapeá-lo para o atributo do artigo de conhecimento de destino necessário.
    Neste exemplo, mostramos como pode mapear um valor de origem do tipo Cadeia de carateres para um atributo de campo de artigo do tipo OptionSet. No plug-in que criou, substitua toda a classe pelo código de amostra seguinte.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.Remoting.Contexts;
using System.Runtime.Remoting.Services;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using Microsoft.Xrm.Sdk.Metadata;

namespace PowerApps.Samples
{
   /// <summary>
   /// The plug-in shows the sample code to map the external source value to the target attribute, when they're of different types
   /// </summary>
   /// <remarks>
   /// To showcase the capabilities of the plugin, we have added 2 new attributes to the KnowledgeArticle entity.
   /// The first attribute new_documentationcentersourcevalue is a String attribute that is mapped to the external source value. This is a temporary mapping that stores the source value.
   /// The plugin picks up the source value from new_documentationcentersourcevalue. The source value can take the following values: Develop, Content, and Test.
   ///The second attribute, new_documentationcenter, is the target attribute of type OptionSet to which the source value must actually be mapped to.
   /// Develop with value 100000000, Content with value 100000001, and Test with value 100000002
   /// The goal of this plugin to read the value from the new_documentationcentersourcevalue, retrieve the option set metadata of the target attribute new_documentationcenter, and map it to the value in new_documentationcentersourcevalue.
   /// </remarks>
   public sealed class KnowledgePlugin : IPlugin
   {
       /// <summary>
       /// Execute method that is required by the IPlugin interface.
       /// </summary>
       /// <param name="serviceProvider">The service provider from which you can obtain the
       /// tracing service, plug-in execution context, organization service, and more.</param>
       public void Execute(IServiceProvider serviceProvider)
       {
           //Extract the tracing service for use in debugging sandboxed plug-ins.
           ITracingService tracingService =
               (ITracingService)serviceProvider.GetService(typeof(ITracingService));

           // Obtain the execution context from the service provider.
           IPluginExecutionContext context = (IPluginExecutionContext)
               serviceProvider.GetService(typeof(IPluginExecutionContext));

           // The InputParameters collection contains all the data passed in the message request.
           if (context.InputParameters.Contains("Target") &&
               context.InputParameters["Target"] is Entity)
           {
               // Obtain the target entity from the input parameters.
               Entity entity = (Entity)context.InputParameters["Target"];

               // Verify that the target entity represents knowledgearticle.
               if (entity.LogicalName != "knowledgearticle")
               {
                   tracingService.Trace("KnowledgePlugin: Plugin is incorrectly called for the entity: " + entity.LogicalName);
                   return;
               }

               //Skip the plugin for RootArticles
               const string isRootArticleAttributeName = "isrootarticle";
               bool isRootArticle = entity.GetAttributeValue<bool>(isRootArticleAttributeName);
               if (isRootArticle)
               {
                   tracingService.Trace("KnowledgePlugin: Returning for Root Article");
                   return;
               }

               try
               {
                   const string sourceValueAttributeName = "new_documentationcentersourcevalue";
                   const string targetValueAttributeName = "new_documentationcenter";

                   //Get the source value
                   string sourceValue = entity.GetAttributeValue<string>(sourceValueAttributeName);
                   if (string.IsNullOrEmpty(sourceValue))
                   {
                       tracingService.Trace("KnowledgePlugin: " + sourceValueAttributeName + " is not set");
                       return;
                   }

                   // Obtain the organization service reference.
                   IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
                   IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

                   // Retrieve the option set metadata of the target field.
                   OptionSetMetadata retrievedOptionSetMetadata = RetrieveOptionSet(service, entity, targetValueAttributeName, tracingService);

                   // Check if the source data value is present in the retrieved target option set metadata.
                   OptionMetadata matchedOptionMetadata = retrievedOptionSetMetadata?.Options?.First(optionMetadata => optionMetadata.Label.UserLocalizedLabel.Label == sourceValue);
                   if (matchedOptionMetadata == null || matchedOptionMetadata.Value == null)
                   {
                       tracingService.Trace("KnowledgePlugin: Matching OptionMetadata is not found");
                       return;
                   }

                   // Map the option set value of the string new_documentationcentersourcevalue to the target option set new_documentationcenter.
                   int optionSetValue = (int)matchedOptionMetadata.Value;
                   entity[targetValueAttributeName] = new OptionSetValue(optionSetValue);
                   tracingService.Trace("KnowledgePlugin: Successfully set the value.");
               }
               catch (FaultException<OrganizationServiceFault> ex)
               {
                   throw new InvalidPluginExecutionException("An error occurred in the KnowledgePlugin plug-in." + ex + "\n InnerException: " + ex.InnerException);
               }

               catch (Exception ex)
               {
                   tracingService.Trace("Exception in KnowledgePlugin: {0}", ex);
                   throw ex;
               }
           }
       }

       /// <summary> 
       /// Fetch the optionset metadata from the entity metadata
       /// </summary>
       /// <param name="service">Organization Details</param>
       /// <param name="entity">Entity record</param>
       /// <param name="targetValueAttributeName">Optionset Attribute Name</param>
       /// <param name="tracingService">Tracing Service</param>
       private OptionSetMetadata RetrieveOptionSet(IOrganizationService service, Entity entity, string targetValueAttributeName, ITracingService tracingService)
       {
           RetrieveEntityRequest retrieveEntityRequest = new RetrieveEntityRequest
           {
               LogicalName = entity.LogicalName,
               EntityFilters = EntityFilters.Attributes,
               RetrieveAsIfPublished = true
           };
           RetrieveEntityResponse retrieveEntityResponse = (RetrieveEntityResponse)service.Execute(retrieveEntityRequest);
           EntityMetadata metadata = retrieveEntityResponse.EntityMetadata;
           PicklistAttributeMetadata picklistMetadata = metadata.Attributes.FirstOrDefault(attribute => string.Equals(attribute.LogicalName, targetValueAttributeName, StringComparison.OrdinalIgnoreCase)) as PicklistAttributeMetadata;
           return picklistMetadata.OptionSet;
       }
   }
}
  1. Registe o plug-in em mensagens SDK Create e Update da entidade KnowledgeArticle na fase PreOperation. Mais informações: Registar um plug-in

Gerir fornecedores de pesquisa integrada
Ver e utilizar informações para fornecedores de pesquisa

  • Last updated on