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

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 :

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

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.