Skemadetaljer til opbygning af en skabelon til tilknytning af metadata

Applies to: Dynamics 365 Customer Service og Dynamics 365 Contact Center – kun selvstændige

I denne artikel beskrives de skemaoplysninger, der kræves for at knytte oplysninger fra eksterne dataudbydere til videnartikelobjekterne, og hvordan du kan forberede din egen JSON-fil til skematilknytning ved hjælp af forskellige felter og attributter.

Felter

I følgende tabel vises de felter og feltoplysninger, du skal bruge i JSON-skemaet.

Feltnavn	Definition	Påkrævet	Værdi
Name	Navn på feltdefinitionen	Nej	En streng, der angiver navnet på feltet.
UniqueTargetFieldName	Det entydige id eller den alternative nøgle for videnartikelobjektet. Dette felt er typisk id'et på indholdsudbydersiden.	Ja	En streng, der angiver navnet på feltet. Du kan indstille værdien til "msydn_externalreferenceid"
IndholdsmålFeltNavn	Feltværdien bør ikke ændres.	Ja	Indstil værdien til "indhold".
ApiPathLeafName	Feltværdien bør ikke ændres.	Ja	Angiv værdien til "videnartikler".
Definition af listefelt<>	Er en liste over feltdefinitioner.	Ja	Et sæt definitioner for felterne. Se følgende tabel for at få en liste over understøttede felter til angivelse af feltdefinitioner.

Definitioner af felter

I følgende tabel vises de påkrævede og valgfrie attributter, som du kan bruge i dit metadatatilknytningsskema.

Feltnavn	Definition	Påkrævet	Værdi
Navn på målfelt	Er det logiske feltnavn på målattributten i videnartikelobjektet.	Ja	En streng, der angiver navnet på målfeltet
TargetFieldType	Angiver typen af målfelt.	Ja	En streng, der angiver typen af feltet.
DocFieldSource	Angiver, hvordan kildefeltværdien identificeres og fortolkes på kørselstidspunktet	Ja	Angiv værdien til en af følgende kildetyper: Regex Meta Konstant URL-adresse Document Du kan få mere at vide om disse datatyper i følgende afsnit Feltkildetyper.
DocFieldPattern	Angiver arten af det målfelt, der skal hentes.	Nej	Angiv denne værdi baseret på værdien DocFieldSource. Se eksemplerne nedenfor på, hvordan du indstiller DocFieldPatterns.
Maks. længde	Er den maksimale længde af den streng, der kan gemmes i målfeltet.	Antal Kan bruges, når attributten TargetFieldType er af typen String	Int
UseRegexCapture	Gemmer det regex-mønster, der kan anvendes på URL-adressen.	Antal Kan bruges, når attributten TargetFieldType er af typen Streng, og attributten DocFieldSource er af typen URL.	URL eller streng.

Feltkildetyper

Dataene i de eksterne søgemaskiner kan indstilles til en af følgende feltkildetyper:

• Regex: Bruges til at angive en regulær udtrykstype for data.
• Meta: Bruges til at angive, at værdien i målfeltet er hentet fra et <metatag> i kildeartiklen
• Konstant: Bruges til at angive en statisk værdi for målfeltet.
• URL: Bruges til at angive URL-adressen til det eksterne kildedokument.
• Dokument: Bruges til at angive artiklens HTML-indhold.

Overvejelser i forbindelse med opbygning af din egen skabelon til metadatatilknytning

Når du udvikler dit eget tilknytningsskema, skal du sørge for at konfigurere nogle få obligatoriske felter og angive standardværdier for nogle feltdefinitioner.

Din kortlægningsskabelon skal indeholde:

• Felterne UniqueTargetFieldName, ContentTargetFieldName og ApiPathLeafName . Disse felter skal angives til de krævede værdier på følgende måde:

  • Angiv UniqueTargetFieldName til det indbyggede msdyn_externalreferenceid-felt eller til et brugerdefineret felt. Hvis du bruger et brugerdefineret felt, skal du sørge for at tilføje feltet som en alternativ nøgle. Flere oplysninger: Definér alternative nøgler til at referere til Dynamics 365-poster.
  • Medtag feltet ContentTargetFieldName, og angiv dets værdi til "content".
  • Medtag feltet ApiPathLeafName, og angiv dets værdi til "videnartikler".
  • Sørg for, at du angiver tilknytninger for både felterne UniqueTargetField og ContentTargetField på listen Feltdefinitioner .

  Dit tilknytningsskema vil se sådan ud:

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

• Du skal medtage nedenstående liste FieldDefinitions og udfylde dens attributter, f.eks. FieldUse, DocFieldSource, TargetFieldName og TargetFieldType , med standardværdier. Sørg for at medtage følgende felter og attributter med deres værdier, "as-is", i skabelonen. Du kan dog indstille Docfieldsource og Docfieldpattern for felterne titel og indholdsværdi til enten Regex, Meta, Document, Constant eller 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"
    }
  
  

• Når du har angivet de obligatoriske felter og attributoplysninger, kan du medtage eventuelle yderligere metadatatilknytninger og angive dine egne brugerdefinerede værdier for dem. Du kan f.eks. medtage metatypen DocFieldSource og angive eventuelle brugerdefinerede værdier for attributten på følgende måde.

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

Eksempel på skabelon til metadatatilknytning

Du kan bruge følgende JSON-eksempel på metadatatilknytning som skabelon til at oprette din egen brugerdefinerede tilknytningsskabelon.

   {
     "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})$"
        }
    ]
 }

Transforme, tilknytte eksterne kildedata til vidensfelter

Når du knytter oplysninger fra eksterne dataudbydere til viden-artikelenheder, skal du transformere værdien, før du kan knytte dem til viden-attributten for målet, hvis kildeværdien er af en anden datatype. Du kan oprette en plug-in og registrere den på Create- og Update-meddelelser, så attributterne for videnartiklen for mål har værdier, der er indbygget i artiklerne fra de eksterne udbydere.

Hvis du vil transformere og tilknytte kildeværdierne, skal du udføre følgende trin:

1. Opret et brugerdefineret felt i KnowledgeArticle-objektet. Flere oplysninger i Sådan opretter og redigerer du kolonner.
2. Knyt den påkrævede eksterne kildeværdi til det brugerdefinerede felt, der netop er oprettet. Få mere at vide under Konfigurer skematilknytning for videnartikler (prøveversion). Det er en midlertidig tilknytning, hvorfra plug-in'en henter kildeværdien.
3. Opret en plug-in. Få mere at vide under Opret et plug-in-projekt.
4. Du kan skrive din egen kode for at konvertere den eksterne kildeværdi og knytte den til den påkrævede målattribut for videnartikel.
   I dette eksempel viser vi, hvordan du kan knytte en kildeværdi af typen Streng til en artikelfeltattribut af typen OptionSet. Erstat hele klassen med følgende eksempelkode i den plug-in, du har oprettet.

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

3. Registrer plug-in'en på Create- og Update-SDK-meddelelserne for objektet KnowledgeArticle i fasen PreOperation. Flere oplysninger: Registrere en plug-in

Relaterede oplysninger

Administrere integrerede søgemaskiner
Se og bruge indsigt for søgemaskiner.