Share via

Définition de clés secondaires pour une entité

  • Article

Tous les enregistrements Dynamics 365 Customer Engagement (on-premises) possèdent des identificateurs uniques définis comme GUID. Il s’agit de la clé primaire de chaque entité. Lorsque vous devez procéder à une intégration avec une banque de données externes, vous pouvez ajouter une colonne aux tables de la base de données externes afin qu’elles contiennent une référence à l’identificateur unique dans Customer Engagement. Cela vous permet d’avoir une référence locale à lier à l’enregistrement Customer Engagement. Toutefois, il arrive que vous ne puissiez pas modifier la base de données externe. Avec les clés secondaires, vous pouvez désormais définir un attribut dans une entité des applications Customer Engagement pour qu’il corresponde à un identificateur unique (ou à une combinaison unique de colonnes) utilisé par la banque de données externes. Cette clé secondaire peut être utilisée pour identifier de manière unique un enregistrement dans Customer Engagement à la place de la clé primaire. Vous devez être en mesure de définir les attributs qui représentent une identité unique pour vos enregistrements. Une fois que vous identifiez les attributs qui sont uniques pour l’entité, vous pouvez les déclarer comme clés secondaires via l’interface utilisateur de personnalisation ou dans le code. Cette rubrique fournit des informations sur la définition des clés secondaires dans le modèle de données.

Création de clés secondaires

Vous pouvez créer des clés secondaires par programme ou à l’aide des outils de personnalisation. Pour plus d’informations sur l’utilisation des outils de personnalisation, voir Définir des clés secondaires pour référencer les enregistrements CRM.

Pour définir des clés secondaires par programme, vous devez d’abord créer un objet de type EntityKeyMetadata (ou utilisez EntityKeyMetadata EntityType pour l’API web). Cette classe contient les attributs de clé. Une fois les attributs de clé définis, vous pouvez utiliser CreateEntityKey pour créer les clés pour une entité. Ce message utilise le nom de l’entité et les valeurs EntityKeyMetadata comme entrées pour créer la clé.

Vous devez connaître les contraintes suivantes lorsque vous créez des clés secondaires :

  • Types d’attribut valides dans les définitions de clé

    Seuls les attributs des types suivants peuvent être inclus dans les définitions de clés secondaires :

    Type d’attribut Nom complet
    DecimalAttributeMetadata Nombre décimal
    IntegerAttributeMetadata Nombre entier
    StringAttributeMetadata Une seule ligne de texte
    DateTimeAttributeMetadata Date et heure
    LookupAttributeMetadata Lookup
    PicklistAttributeMetadata Picklist

Note

Les attributs DateTime, Lookup et Picklist ne sont pas disponibles pour les versions locales de Dynamics 365 Customer Engagement.

  • Les attributs doivent être valides pour la création et la mise à jour

    Chaque attribut utilisé dans la clé doit prendre en charge la création et la mise à jour. Pour plus d’informations : Opérations valides sur les attributs

  • Les attributs ne doivent pas avoir de sécurité appliquée au niveau du champ

  • Les attributs ne doivent pas être logiques ou hérités

    La plupart des attributs logiques et hérités sont configurés en mode lecture seule. Toutefois, nombre des attributs qui contiennent les informations d’adresse dans des entités telles que Compte et Contact sont logiques et ne peuvent pas être utilisés dans une clé, même s’ils sont inscriptibles. Pour plus d’informations : Attributs logiques

  • Taille de clé valide

    Lorsqu’une clé est créée, le système valide que la clé peut être prise en charge par la plateforme, notamment le fait que la taille totale de la clé n’enfreint pas les contraintes des index SQL, à savoir 900 octets par clé et 16 colonnes par clé. Si la taille de la clé ne remplit pas les contraintes, un message d’erreur s’affiche.

  • Nombre maximal de définitions de clés secondaires pour une entité

    5 est le nombre maximal de définitions de clés secondaires pour une entité dans une instance Customer Engagement.

  • Caractères spéciaux en valeur principale

    Si les données d’un champ utilisé dans une autre clé contiennent l’un des caractères suivants /,<,>,*,%,&,:,\\, les actions Get et Patch ne fonctionneront pas. Si vous n’avez besoin que d’unicité, cette approche fonctionnera, mais si vous devez utiliser ces clés dans le cadre de l’intégration de données, il est préférable de créer la clé pour les champs qui n’auront pas de données avec ces caractères.

Récupération et suppression de clés secondaires

Si vous devez récupérer ou supprimer des clés secondaires, vous pouvez utiliser l’interface utilisateur de personnalisation, sans devoir écrire de code. Toutefois, le Kit de développement logiciel fournit les deux messages suivants pour récupérer et supprimer des clés secondaires par programme.

Classe de demande de message Description
RetrieveEntityKeyRequest Récupère la clé secondaire spécifiée.
DeleteEntityKeyRequest Supprime la clé secondaire spécifiée.

Pour récupérer toutes les clés pour une entité, utilisez la nouvelle propriété Keys de EntityMetadata (classe EntityMetadata EntityType ou EntityMetadata). Elle permet de récupérer un groupe de clés pour une entité.

Surveillance de la création d’index pour les clés secondaires

Les clés secondaires utilisent des index de la base de données pour appliquer l’unicité et optimiser les performances de recherche. S’il existe un grand nombre d’enregistrements existants dans une table, la création d’index peut prendre du temps. Vous pouvez augmenter la réactivité de l’interface utilisateur de personnalisation et l’importation de la solution en établissant la création d’index comme processus en arrière-plan. La propriété EntityKeyMetadata.AsyncJob (EntityKeyMetadata EntityType ou EntityKeyMetadata) fait référence au travail asynchrone qui effectue la création d’index. La propriété EntityKeyMetadata.EntityKeyIndexStatus indique le statut de la clé lors de la progression du travail de création d’index. L’état peut être l’un des états suivants :

  • En attente
  • En cours
  • Actif
  • Échec

Lorsqu’une clé secondaire est créée à l’aide de l’API, si la création d’index échoue, vous pouvez rechercher la cause de la défaillance, résoudre les problèmes et réactiver la demande de clé à l’aide de ReactivateEntityKey (message ReactivateEntityKey Action ou ReactivateEntityKeyRequest).

Si la clé secondaire est supprimée alors qu’un travail de création d’index est toujours en attente ou en cours, le travail est annulé et l’index est supprimé.

Voir aussi

Utilisation de clés secondaires
Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
Utilisation de Upsert pour insérer ou mettre à jour un enregistrement