Partager via

Utiliser les clés secondaires

  • Article

Toutes les lignes du tableau ont un identifiant unique formaté sous forme de GUID. Microsoft Dataverse Ces identifiants constituent la clé primaire de chaque table. Lorsque vous devez effectuer une intégration avec un magasin de données externe, vous pourrez peut-être ajouter une colonne aux tables de base de données externes pour contenir une référence à l’identifiant unique d’une ligne Dataverse. Toutefois, il arrive que vous ne puissiez pas modifier la base de données externe. Avec des clés alternatives, vous pouvez désormais définir une colonne dans une table pour correspondre à un identifiant unique (ou à une combinaison unique de colonnes) utilisé par le magasin de données externe. Dataverse 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 alternatives à 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 clés définies, vous pouvez utiliser CreateEntityKey pour créer les clés d’une table. Ce message prend le nom de la table et les valeurs comme entrée pour créer la clé. EntityKeyMetadata

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

  • Colonnes valides dans les définitions de tables 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é, notamment en vérifiant que la taille totale de la clé ne viole pas les contraintes d’index basées sur SQL telles que 900 octets par clé et 16 colonnes par clé. Si la taille de la clé ne respecte pas les contraintes, un message d’erreur s’affiche.

  • Nombre maximal de définitions de table clé secondaire pour une table

    Il peut y avoir un maximum de dix (10) définitions de table clé secondaire pour une table dans une instance. Dataverse

  • Caractères Unicode dans la valeur clé

    Si les données dans une colonne utilisée dans un clé secondaire contiennent l’un des caractères suivants /,<,>,*,%,&,:,\\,?,+ , les actions de récupération (GET), de mise à jour ou d’insertion (PATCH) ne fonctionneront pas. Si vous avez uniquement besoin 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é sur des colonnes qui ne contiendront pas de données avec ces caractères.

  • Non pris en charge dans les tables virtuelles

    Les clés alternatives 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. Plus d’informations : Commencer 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 d’une table, utilisez la Keys propriété de EntityMetadata (EntityMetadata EntityType ou EntityMetadata classe). 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

Utilisez un clé secondaire pour référencer un enregistrement
Utilisez le suivi des modifications pour synchroniser les données avec des systèmes externes
Utilisez Upsert pour insérer ou mettre à jour un enregistrement
Définir des clés alternatives pour référencer les enregistrements