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

Bei Datenintegrationsszenarien verwenden Sie alternative Schlüssel, um Vorgänge durchzuführen, bei denen Sie den Primärschlüsselwert eines Dataverse-Datensatzes nicht kennen. Sie können alternative Schlüssel nur für Tabellen verwenden, in denen sie definiert sind. Die meisten Dataverse-Tabellen haben keine alternativen Schlüssel, es sei denn, sie wurden so angepasst, dass sie diese enthalten.

Wenn Sie wissen möchten, wie Sie alternative Schlüssel für eine Tabelle definieren und identifizieren, lesen Sie die folgenden Artikel:

• Verwenden von Power Apps: Definieren von Alternativschlüsseln für den Verweis auf Zeilen
• Code verwenden: Arbeiten mit Alternativschlüsseln

Sie können alternative Schlüssel verwenden, indem Sie entweder die Dataverse Web-API oder das SDK für .NET benutzen.

Web-API

Wenn Sie die Web-API verwenden, referenzieren Sie einen bestimmten Datensatz über eine URL und verwenden dann die Http-Methoden POST, PATCH oder DELETE, um den Datenvorgang durchzuführen. Sie verwenden URLs auch, um Werte für einzelwertige Navigationseigenschaften mithilfe der @odata.bind-Syntax festzulegen oder als Parameter für Funktionen und Aktionen.

Die folgende Tabelle enthält Beispiele, die zeigen, wie Datensätze mit relativen URLs referenziert werden:

Situation	Beispiel
Mit einem Primärschlüssel	/accounts(00000000-0000-0000-0000-000000000001) ODER accounts(accountid=00000000-0000-0000-0000-000000000001) Siehe den folgenden Hinweis zu den Typen systemuser und team der Entitäten
Mit einem einzelnen Alternativschlüssel	/accounts(accountnumber='ABC123')
Mit mehrteiligen Alternativschlüsseln	/contacts(firstname='Joe',emailaddress1='abc@example.com')
Mit einem Alternativschlüssel, das eine Nachschlagespalte verwendet	/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000002) Wenn ein Alternativschlüssel für eine Nachschlagespalte definiert ist, müssen Sie den Namen des entsprechenden Nachfrage-Eigenschaft verwenden. Eine Nachschlage-Eigenschaft folgt der folgenden Namenskonvention: _<name of single-valued navigation property>_value.

Hinweis

Wegen der Art des Erbens von systemuser und team-Entitätstypen von dem principal-Entitätstyp können Sie keinen benannten Primärschlüssel verwenden, um auf diese Entitäten zu verweisen. Die Primärschlüssel für diese beiden Entitäten sind ownerid, statt systemuserid oder teamid. Der principal-Entitätstyp unterstützt die GET-Vorgänge nicht. Weitere Informationen: EntityType-Vererbung

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

Sie müssen die folgenden Bedingungen und möglichen Ausnahmen berücksichtigen, wenn Alternativschlüssel verwendet werden:

• Wenn Sie eine Spalte angeben, die nicht als eindeutiger Schlüssel definiert ist, wird ein Fehler ausgegeben, der darauf hinweist, dass die Verwendung von eindeutigen Schlüsselspalten erforderlich ist. 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 mit den folgenden Zeichen /, <, >, *, %, &, :, \\, ?, + werden derzeit nicht unterstützt.

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

SDK für .NET

Wenn Sie das SDK für .NET verwenden, gibt es zwei Möglichkeiten, alternative Schlüssel zu verwenden.

Verwenden der Entitätsklasse

Wenn Sie eine Instanz der Klasse Entity erstellen, können Sie die Schlüssel zur Identifizierung des Datensatzes mit den folgenden Entity Constructors angeben:

// 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 Werte werden der Eigenschaft Entity.KeyAttributes hinzugefügt, nicht der Eigenschaft Entity.Attributes. KeyAttributes werden verwendet, um einen Datensatz zu identifizieren. Attributes umfasst die Daten für den Datensatz.

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 Klasse EntityReference erstellen, können Sie die Schlüssel zur Identifizierung des Datensatzes mit Hilfe der folgenden EntityReference Konstruktoren angeben, die das gleiche Muster wie die Entity Klasse Konstruktoren 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) {…}    

• Sie können EntityReference verwenden, um Werte für Entitätssuchspalten festzulegen. Bei Verwendung zum Festlegen einer Nachschlagespalte werden die Schlüsselwerte verwendet, um den Primärschlüsselwert zu finden, und die Primärschlüsselwerte werden in der Datenbank gespeichert.
• Sie können EntityReference für Nachrichten verwenden, die diesen Typ als Eigenschaft verwenden, wie z.B. Delete unter Verwendung der DeleteRequest Klasse.

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

Sie müssen die folgenden Bedingungen und möglichen Ausnahmen berücksichtigen, wenn Alternativschlüssel verwendet werden:

• Die Eigenschaft Entity.Id wird verwendet, wenn sie angegeben wird. Wenn kein Wert angegeben wird, wird die KeyAttributeCollection geprüft. Wenn die KeyAttributeCollection nicht angegeben wird, wird ein Fehler ausgegeben.
• Wenn die angegebene KeyAttributeCollection eine Spalte enthält, die der Primärschlüssel der Tabelle ist und der Wert gültig ist, wird die Entity.Id Eigenschaft oder EntityReference.Id Eigenschaft mit dem angegebenen Wert aufgefüllt.
• Wenn die Schlüsselspalten bereitgestellt werden, versucht das System, den Satz der bereitgestellten Spalten mit den für die Entity festgelegten Schlüsseln abzugleichen. Findet er keine Übereinstimmung, gibt er einen Fehler aus. Wenn es eine Übereinstimmung findet, werden die angegebenen Werte für diese Spalten überprüft. Wenn er gültig ist, ruft er den Primärschlüsselwert des Datensatzes ab, der mit den angegebenen alternativen Schlüsselwerten übereinstimmt, und füllt die Entity.Id Eigenschaft oder EntityReference.Id Eigenschaft mit diesem Wert.
• Wenn Sie eine Spalte angeben, die nicht als eindeutiger Schlüssel definiert ist, wird ein Fehler ausgegeben, der darauf hinweist, dass die Verwendung von eindeutigen Schlüsselspalten erforderlich ist.

Siehe auch

Definieren Sie alternative Schlüssel für eine Tabelle
Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung
Einen Datensatz mit Upsert einfügen oder aktualisieren

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).