Verwenden Sie einen Alternativschlüssel, um auf einen Datensatz zu verweisen

Wenn Sie die Web-API verwenden, verweisen Sie mithilfe einer URL auf einen bestimmten Datensatz. Verwenden Sie dann die HTTP-Methoden POST, PATCH oder DELETE, um die Datenoperation auszuführen. Außerdem verwenden Sie URLs, um Werte für Einzelwert-Navigationseigenschaften mithilfe der @odata.bind Syntax oder als Parameter für Funktionen und Aktionen festzulegen.

Die folgende Tabelle enthält Beispiele, die zeigen, wie Sie mithilfe relativer URLs auf Datensätze verweisen:

Ausnahmen beim Verwenden von Alternativschlüsseln mit der Web-API

Beachten Sie bei der Verwendung alternativer Schlüssel die folgenden Bedingungen und mögliche Ausnahmen:

• Wenn Sie eine Spalte angeben, die nicht als eindeutiger Schlüssel definiert ist, tritt ein Fehler auf. Die Fehlermeldung ist: 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>'.

• Alternative Schlüsselwerte können einige Sonderzeichen nicht enthalten.

  Alternative Schlüsselwerte mit den folgenden Zeichen /,<,>,*,%,&,:,\\,?,+ werden nicht unterstützt. Diese Sonderzeichen sind in einem URL-Pfadsegment reserviert oder strukturell signifikant. Dataverse gibt einen Fehler zurück, wenn Sie eine GET Anforderung mit diesen Werten innerhalb der Klammern der URL senden. Der Workaround besteht nicht darin, einen einzelnen Datensatz abzurufen, sondern die alternativen Schlüsselwerte mit $filter zu verwenden, um eine Sammlung abzurufen, die den Datensatz enthält, der mit den alternativen Schlüsselwerten übereinstimmt.

  Beispiel: Anstelle dieser Anforderung, die fehlschlägt:

  GET [Organization URI]/api/data/v9.2/new_skts(new_name='M%26M')
  

  Verwenden Sie eine $filter Abfrage:

  GET [Organization URI]/api/data/v9.2/new_skts?$filter=new_name eq 'M%26M'&$select=new_name
  

  Wenn Sie nur auf den Datensatz zugreifen müssen, können Sie die Daten aus dem ersten (und nur) übereinstimmenden Datensatz in der value zurückgegebenen Sammlung übernehmen. Wenn Sie eine andere Aktion ausführen müssen, z. B. das Aktualisieren oder Löschen des Datensatzes, können Sie diesen Ansatz verwenden, um die ID des übereinstimmenden Datensatzes abzurufen und dann auf den Datensatz zu verweisen, der konventionell den ID-Wert anstelle des Werts alternativer Schlüssel verwendet.

  Anmerkung

  Parameteraliasen (@param) funktionieren nicht mit alternativer Schlüsselsyntax. Die Verwendung eines Parameteralias in einem Schlüsseldrädikat gibt einen 400 Fehler auch für Werte ohne Sonderzeichen zurück. Verwenden Sie stattdessen $filter.

Weitere Informationen: Datensatz unter Verwendung eines alternativen Schlüssels abrufen

Wenn Sie das SDK für .NET verwenden, können Sie alternative Schlüssel auf zwei Arten verwenden.

Verwenden der Entitätsklasse

Wenn Sie eine Instanz der Entity-Klasse erstellen, geben Sie die Schlüssel zum Identifizieren des Datensatzes mithilfe der folgenden Entitätskonstruktoren an:

// 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) {…}  

Diese Konstruktoren fügen der Entity.KeyAttributes-Eigenschaft Werte hinzu, nicht der Entity.Attributes-Eigenschaft. Verwenden Sie KeyAttributes, um einen Datensatz zu identifizieren. Attributes enthält die Daten des Datensatzes.

Wenn eine Tabelle beispielsweise ein Alternativschlüssel hat, das zwei Alternativschlüssel-Spalten enthält, können Sie die Entität auf diese Weise definieren.

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

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

Verwenden der EntityReference-Klasse

Wenn Sie eine Instanz der EntityReference-Klasse erstellen, geben Sie die Schlüssel zum Identifizieren des Datensatzes mithilfe der folgenden EntityReference-Konstruktoren an, die dasselbe Muster wie die Entitätsklassenkonstruktoren verwenden.

// 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) {…}    

• Verwenden Sie EntityReference, um Werte für Entitätssuchspalten festzulegen. Wenn Sie sie zum Festlegen einer Nachschlagespalte verwenden, finden die Schlüsselwerte den Primärschlüsselwert, und der Primärschlüsselwert wird in der Datenbank gespeichert.
• Verwenden Sie EntityReference für Nachrichten, die diesen Typ als Eigenschaft verwenden, z. B. Delete, unter Verwendung der DeleteRequest-Klasse.

Ausnahmen beim Verwenden von Alternativschlüsseln mit der SDK für .NET

Beachten Sie bei der Verwendung alternativer Schlüssel die folgenden Bedingungen und mögliche Ausnahmen:

• Das SDK verwendet die Entity.Id-Eigenschaft , wenn Sie sie bereitstellen. Wenn Sie sie nicht angeben, prüft das SDK das KeyAttributeCollection. Wenn Sie KeyAttributeCollection nicht angeben, gibt das SDK einen Fehler aus.
• Wenn die bereitgestellte KeyAttributeCollection Spalte eine Spalte enthält, die den Primärschlüssel der Tabelle darstellt und der Wert gültig ist, füllt das SDK die Entity.Id Eigenschaft oder EntityReference.Id Eigenschaft mit dem bereitgestellten Wert auf.
• Wenn Sie Schlüsselspalten angeben, versucht das System, den Satz von Spalten abzugleichen, die Sie mit den für die EntitySchlüssel definierten Schlüsseln angeben. Findet er keine Übereinstimmung, gibt er einen Fehler aus. Wenn eine Übereinstimmung gefunden wird, werden die bereitgestellten Werte für diese Spalten überprüft. Wenn gültig, ruft er den Primärschlüsselwert des Datensatzes ab, der den bereitgestellten alternativen Schlüsselwerten entspricht, und füllt die Entity.Id Eigenschaft oder EntityReference.Id-Eigenschaft mit diesem Wert auf.
• Wenn Sie eine Spalte angeben, die nicht als eindeutiger Schlüssel definiert ist, löst das SDK einen Fehler aus, der angibt, dass die Verwendung eindeutiger Schlüsselspalten erforderlich ist.