Utiliser les clés secondaires

Toutes les lignes de table Microsoft Dataverse ont un identificateur unique au format GUID. Ces identificateurs sont la clé primaire de chaque table. Lorsque vous devez procéder à une intégration avec un magasin de données externes, vous pouvez ajouter une colonne aux tables externes de la base de données pour contenir une référence à l’identificateur unique d’une ligne dans 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 le magasin 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	Lookup
  PicklistAttributeMetadata	Groupe d’options

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

• Taille de clé valide

  Lorsqu’une clé est créée, le système valide la clé, y compris que la taille totale de la clé n’enfreint pas les contraintes d’index basées sur SQL, comme 900 octets par clé et 16 colonnes par clé. Si la taille de la clé ne répond pas aux contraintes, un message d’erreur s’affiche.

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

  Il peut y avoir un maximum de dix (10) définitions de table 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 de récupération (GET), de mise à jour ou d’upsert (PATCH) ne fonctionneront pas. Si vous n’avez besoin que d’unicité, cette approche fonctionne, 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é dans les colonnes qui n’auront pas de données contenant 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é lorsque 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.

Pour récupérer toutes les clés pour une table, 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 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