Utilisation d’une clé secondaire pour référencer un enregistrement

Vous utiliserez des clés alternatives avec des scénarios d’intégration de données pour effectuer des opérations de données lorsque vous ne connaissez pas la valeur de clé primaire d’un enregistrement Dataverse. Vous ne pouvez utiliser des clés alternatives que pour les tables où elles sont définies. La plupart des tables Dataverse n’auront pas de clés alternatives à moins qu’elles n’aient été personnalisées pour les inclure.

Pour comprendre comment définir et identifier des clés secondaires pour une table, voir les articles suivants :

• Utilisation de Power Apps : Définir des clés secondaires pour référencer des lignes
• Utilisation du code : Utiliser les clés secondaires

Vous pouvez utiliser des clés alternatives à l’aide de l’API web Dataverse ou du SDK pour .NET.

API web

Lorsque vous utilisez l’API Web, vous référencez un enregistrement spécifique à l’aide d’une URL, puis utilisez les méthodes http POST, PATCH ou DELETE pour effectuer l’opération de données. Vous utilisez également des URL pour définir des valeurs pour les propriétés de navigation à valeur unique à l’aide de la syntaxe @odata.bind, ou en tant que paramètres de fonctions et d’actions.

La table suivante fournit des exemples montrant comment référencer des enregistrements à l’aide d’URL relatives :

Situation	Exemple
Avec une clé primaire	/accounts(00000000-0000-0000-0000-000000000001) OU accounts(accountid=00000000-0000-0000-0000-000000000001) Voir la note suivante sur les types d’entité systemuser et team
Avec une clé secondaire	/accounts(accountnumber='ABC123')
Avec des clés secondaires en plusieurs parties	/contacts(firstname='Joe',emailaddress1='abc@example.com')
Avec une clé secondaire qui utilise une colonne de recherche	/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000002) Quand une clé secondaire est définie pour une colonne de recherche, vous devez utiliser le nom de la Propriété de recherche correspondante. Une propriété de recherche suit la convention d’affectation de noms suivante : _<name of single-valued navigation property>_value.

Notes

A cause de comment les types d’entités systemuser et team héritent du type d’entité principal, vous ne pouvez pas utiliser une clé primaire nommée pour référencer ces entités. Les clés primaires de ces deux entités sont ownerid, plutôt que systemuserid ou teamid. Le type d’entité principal ne prend pas en charge les opérations GET. Pour plus d’informations, voir : Héritage de type d’entité

Exceptions lors de l’utilisation de clés secondaires avec l’API web

Vous devez tenir compte des conditions et des exceptions possibles suivantes lorsque vous utilisez des clés secondaires :

• Si vous spécifiez une colonne définie qui n’est pas définie comme clé unique, une erreur est générée, indiquant qu’il est nécessaire d’utiliser des colonnes principales uniques. Le message d’erreur est : The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'.
• Les valeurs de clé secondaire avec les caractères suivants /,<,>,*,%,&,:,\\,?,+ ne sont pas prises en charge actuellement.

Plus d’informations : Récupérer un enregistrement utilisant une clé secondaire

SDK pour .NET

Lorsque vous utilisez le SDK pour .NET, il existe deux manières d’utiliser des clés alternatives.

Utilisation de la classe Entité

Lorsque vous créez une instance de la classe d’entité, vous pouvez préciser les clés à utiliser pour identifier l’enregistrement avec les constructeurs d’entité suivants :

// For use with the primary key
public Entity (string logicalName, Guid id) {…} 
// For use with a single alternate key value
public Entity (string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}  

Ces valeurs sont ajoutées à la propriété Entity.KeyAttributes, et non à la propriété Entity.Attributes. KeyAttributes sont utilisés pour identifier un enregistrement. Attributes contient les données de l’enregistrement.

Par exemple, quand une table a une clé secondaire qui inclut deux colonnes clé secondaire, vous pouvez définir l’entité de cette façon.

KeyAttributeCollection keys = new KeyAttributeCollection() {
   { "example_key1", 5 },
   { "example_key2", 5 }
};

Entity thing = new Entity("example_thing", keys);
thing["example_name"] = "Test Name";

Utilisation de la classe EntityReference

Lorsque vous créez une instance de la classe EntityReference, vous pouvez spécifier les clés à utiliser pour identifier l’enregistrement à l’aide des constructeurs EntityReference qui utilisent le même modèle que les constructeurs Entity class.

// For use with the primary key
public EntityReference(string logicalName, Guid id) {…}
// For use with a single alternate key value
public EntityReference(string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}    

• Vous pouvez utiliser EntityReference pour définir des valeurs pour les colonnes de recherche d’entité. Quand elles sont utilisées pour définir une colonne de recherche, les valeurs de clé sont utilisées pour trouver la valeur de clé primaire, et les valeurs de clé primaire sont stockées dans la base de données.
• Vous pouvez utiliser EntityReference pour les messages qui utilisent ce type comme propriété, comme Delete en utilisant la classe DeleteRequest.

Exceptions pendant l’utilisation de clés secondaires avec le Kit de développement logiciel (SDK) pour .NET

Vous devez tenir compte des conditions et des exceptions possibles suivantes lorsque vous utilisez des clés secondaires :

• La propriété Entity.Id est utilisée si elle est fournie. Si elle n’est pas fournie, elle examine la KeyAttributeCollection. Si KeyAttributeCollection n’est pas fournie, une erreur est générée.
• Si la KeyAttributeCollection fournie comprend une colonne qui est la clé primaire de la table et si la valeur est valide, il remplit la propriété Entity.Id ou la propriété EntityReference.Id avec la valeur fournie.
• Si les colonnes de clé sont fournies, le système tente de faire correspondre l’ensemble des colonnes fournies avec les clés définies pour Entity. Si aucune correspondance n’est trouvée, une erreur est générée. Si une correspondance est trouvée, les valeurs fournies pour ces colonnes sont validées. Si valide, elle récupère la valeur de clé principale de l’enregistrement correspondant aux valeurs des autres clés fournies, et renseigne la propriété Entity.Id ou la propriété EntityReference.Id avec cette valeur.
• Si vous spécifiez une colonne définie qui n’est pas définie comme clé unique, une erreur est générée, indiquant qu’il est nécessaire d’utiliser des colonnes principales uniques.

Voir aussi

Définition de clés secondaires pour la table
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

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é).