Utiliser les clés secondaires

Toutes les lignes de table Microsoft Dataverse possèdent des identificateurs uniques définis comme GUID. Il s’agit de la clé primaire de chaque table. 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 Dataverse. Cela vous permet d’avoir une référence locale à lier à la ligne Dataverse. 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 une colonne dans une table Dataverse pour qu’elle 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 une ligne dans Dataverse à la place de la clé primaire. Vous devez être en mesure de définir les colonnes qui représentent une identité unique pour vos lignes. Une fois que vous identifiez les colonnes qui sont uniques pour la table, 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 à l’aide de Power Apps.

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 colonnes de clé. Une fois les colonnes de clé définies, vous pouvez utiliser CreateEntityKey pour créer les clés pour une table. Ce message utilise le nom de la table 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 :

• Colonnes valides dans les définitions de table de clés

  Seules les colonnes des types suivants peuvent être incluses dans les définitions de tables de clés secondaires :

  Type de colonne	Nom d’affichage
  DecimalAttributeMetadata	Nombre décimal
  IntegerAttributeMetadata	Nombre entier
  StringAttributeMetadata	Une seule ligne de texte
  DateTimeAttributeMetadata	Date et heure
  LookupAttributeMetadata	Recherce
  PicklistAttributeMetadata	Groupe d’options

• 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 tables de clés secondaires pour une table

  10 est le nombre maximal de définitions de tables de clés secondaires pour une table dans une instance Dataverse.

• Caractères Unicode en valeur principale

  Si les données d’une colonne utilisée dans une clé secondaire contiennent l’un des caractères suivants /,<,>,*,%,&,:,\\,?,+ alors les actions retrieve (GET), update ou upsert (PATCH) ne fonctionnent 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 colonnes qui n’auront pas de données avec ces caractères.

• Non pris en charge dans les tables virtuelles

  Les clés secondaires ne sont pas prises en charge dans les tables virtuelles, car nous ne pouvons pas appliquer l’unicité quand les données se trouvent sur un autre système. Pour plus d’informations : Se familiariser avec les tables virtuelles (entités)

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 table, utilisez la propriété Keys de la EntityMetadata (classe EntityMetadata EntityType ou EntityMetadata). Elle permet de récupérer un groupe de clés pour une table.

Utilisez cette requête d’API web pour afficher toutes les tables et voir celles qui ont des clés secondaires :

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$expand=Keys($select=KeyAttributes)

Quelques exemples renvoyés par cette requête :

{
    "SchemaName": "Account",
    "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84",
    "Keys": [
        {
            "KeyAttributes": [
                "accountnumber"
            ],
            "MetadataId": "1dc7b1d2-6beb-ec11-bb3d-0022482ea769"
        }
    ]
},
{
    "SchemaName": "example_Table",
    "MetadataId": "8f521e41-8934-ec11-b6e6-002248242f3b",
    "Keys": [
        {
            "KeyAttributes": [
                "example_key1",
                "example_key2"
            ],
            "MetadataId": "2f16d0c6-88ea-ec11-bb3d-0022482ea769"
        }
    ]
}

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 d’une clé secondaire pour référencer un enregistrement
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
Définir des clés secondaires pour référencer des enregistrements

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).