Web-API Navigationseigenschaften

  • Artikel

Im CSDL $metadata Dokument hat jeder Typ von Entität, der nicht abstrakt ist, NavigationProperty Elemente. NavigationProperty-Elemente beschreiben Daten, die sich auf den aktuellen Typ der Entität beziehen. Wenn Sie einen Datensatz abrufen, können Sie festlegen, Navigationseigenschaften zu erweitern, damit zugehörige Daten enthalten sind.

Die folgende Tabelle beschreibt die Attribute der NavigationProperty-Elemente.

Attribute Beschreibung
Name Der Name der Navigationseigenschaft; Groß- und Kleinschreibung wird beachtet
Type Der Typ der verknüpften Entität; kann sich auf einen einzelnen Wert oder eine Sammlung eines Typs beziehen.
Partner Der Name der Navigationseigenschaft auf der anderen Seite der Beziehung
Nullable="false" Ob der Wert Null sein kann

Wichtig

Es gibt zwei Typen von Navigationseigenschaften: Einzelwertig und Sammlungswertig. Diese Unterscheidung ist wichtig, weil die Funktionalitäten der einzelnen Typen von Navigationseigenschaften unterschiedlich sind.

Einzelwertige Navigationseigenschaften

Wenn sich eine Navigationseigenschaft Type auf einen einzelnen Wert bezieht, stellt sie eine n:m-Beziehung dar, die einen Verweis auf einen anderen Datensatz der Tabelle erstellt. Diese Beziehung wird allgemein als Suchfeld bezeichnet. Das folgende Beispiel ist die Navigationseigenschaft account der Tabelle createdby:

<NavigationProperty 
    Name="createdby" 
    Type="mscrm.systemuser" 
    Nullable="false" 
    Partner="lk_accountbase_createdby">
    <ReferentialConstraint 
        Property="_createdby_value" 
        ReferencedProperty="systemuserid" />
</NavigationProperty>

Diese einwertige Navigationseigenschaft verbindet mehrere account-Datensätze mit einem einzigen systemuser-Datensatz. Jeder systemuser-Datensatz hat eine Navigationseigenschaft mit dem Wert lk_accountbase_createdby, die ihn mit den account-Datensätzen verbindet, die der Benutzer erstellt hat.

Diese Werte werden in Beziehungsdefinitionen gespeichert. Sie können über den SDK OneToManyRelationshipMetadata oder den Web-API OneToManyRelationshipMetadata Typ der Entitäten darauf zugreifen, wie in der folgenden Tabelle beschrieben.

Attribute OneToManyRelationshipMetadata-Eigenschaft Beschreibung
Name ReferencingEntityNavigationPropertyName Der Name der einwertigen Navigationseigenschaft.
Partner ReferencedEntityNavigationPropertyName Der Name der sammlungswertigen Navigationseigenschaft.

Sucheigenschaften

Einwertige Navigationseigenschaften haben eine ReferentialConstraint mit einem Property-Attribut, das auf eine Lookup-Eigenschaft verweist. Suchfeld-Eigenschaften verwenden die folgende Benennungskonvention: _<name>_value. Lernen Sie mehr über Suchfeld-Eigenschaften.

Das ReferentialConstraint hat ein ReferencedProperty-Attribut, das den Primärschlüsselnamen des zugehörigen Entitätstyps identifiziert.

In den meisten Fällen stimmt die <name> in der Lookup-Eigenschaft mit dem Namen der Navigationseigenschaft überein, außer wenn die Navigationseigenschaft mit einem Wert ein Suchfeld mit mehreren Tabellen darstellt.

Suchen mit mehreren Tabellen

Wenn die einwertige Navigationseigenschaft Teil eines polymorphen Suchfelds mit mehreren Tabellen ist, ist ein einziges Suchfeld die ReferentialConstraint für mehr als eine einwertige Navigationseigenschaft.

Ein Typ einer Entität kann etwa die folgende Kombination aufweisen, bei der eine einzelne _customerid_value Suchfeld-Eigenschaft mehrere einwertige Navigationseigenschaften unterstützt, die ein Suchfeld mit mehreren Tabellen darstellen. Für jeden Typ von Tabellen, der vom Suchfeld für mehrere Tabellen unterstützt wird, gibt es eine Navigationseigenschaft mit einem Wert.

<EntityType 
    Name="socialprofile" 
    BaseType="mscrm.crmbaseentity">
    <Key>
        <PropertyRef Name="socialprofileid" />
    </Key>
    <Property 
        Name="_customerid_value" <!-- lookup property -->
        Type="Edm.Guid">
        <Annotation 
            Term="Org.OData.Core.V1.Description" 
            String="Shows the customer that this social profile belongs to." />
    </Property>
    <NavigationProperty 
        Name="customerid_contact" <!-- Name different from lookup property -->
        Type="mscrm.contact" 
        Nullable="false" 
        Partner="Socialprofile_customer_contacts">
        <ReferentialConstraint 
            Property="_customerid_value" <!--  Reference to lookup property  -->
            ReferencedProperty="contactid" />
    </NavigationProperty>
    <NavigationProperty 
        Name="customerid_account" <!-- Name different from lookup property -->
        Type="mscrm.account" 
        Nullable="false" 
        Partner="Socialprofile_customer_accounts">
        <ReferentialConstraint 
            Property="_customerid_value"  <!--  Reference to lookup property  -->
            ReferencedProperty="accountid" />
    </NavigationProperty>
</EntityType>

In diesen Fällen setzt das Setzen des Wertes einer der einwertigen Navigationseigenschaften alle anderen beteiligten einwertigen Navigationseigenschaften auf Null. Der Wert der entsprechenden Suchfeld-Eigenschaft GUID ändert sich, aber Sie müssen bestimmte Anmerkungen abrufen, um zu wissen, auf welche Tabelle sie sich jetzt bezieht. Weitere Informationen: Suche Dateneigenschaft

Gemeinsam bewertete Navigationseigenschaften

Wenn sich eine Type-Navigationseigenschaft auf einen Sammlungswert bezieht, steht sie für eine N:1- oder N:N-Beziehung. Das folgende Beispiel ist die Navigationseigenschaft Account_Tasks der Entität „Konto“:

<NavigationProperty 
    Name="Account_Tasks" 
    Type="Collection(mscrm.task)" 
    Partner="regardingobjectid_account_task" 
/>

Diese Navigationseigenschaft verbindet einen account-Datensatz mit vielen task-Datensätzen. Jede task hat eine einwertige Navigationseigenschaft namens regardingobjectid_account_task die sich auf das account als betreffendes Objekt bezieht.

Die Art und Weise, wie Sie mit sammlungsbewerteten Navigationseigenschaften unter Verwendung von OData arbeiten, ist dieselbe, unabhängig davon, ob es sich um eine n:m- oder m:m-Beziehung handelt. Beide werden als Sammlungen betrachtet und Sie interagieren auf die gleiche Weise mit ihnen.

n:1-Beziehungen

Eine N:1-Beziehung ist die Spiegelung der 1:N-Beziehung. Es hat eine Partner-Eigenschaft für die Navigation mit einem Wert. Im früheren Einzelwert Navigationseigenschaften Beispiel haben wir uns die Einzelwert Navigationseigenschaft createdby für den Typ account Entität angesehen.

Im Typ systemuser der Entität existiert die Navigationseigenschaft collection-valued partner mit dem Namen lk_accountbase_createdby.

<NavigationProperty Name="lk_accountbase_createdby"
    Type="Collection(mscrm.account)"
    Partner="createdby" />

m:m-Beziehungen

Wenn der Name und der Partner der sammlungswertigen Navigationseigenschaften gleich sind, steht dies für eine N:N-Beziehung.

N:N-Beziehungen enthalten einige Implementierungsdetails in den Servicedokumenten. In den meisten Anwendungsfällen können Sie sie ignorieren.

Zum Beispiel hat jede n:m-Beziehung eine Überschneidungstabelle, die sie unterstützt. Diese Intersect-Tabellen haben Typen von Entitäten, die normalerweise vier schreibgeschützte Eigenschaften haben. Im folgenden Beispiel ist der Entitätstyp teammembership eine Intersect-Tabelle, die eine m:m-Beziehung zwischen den Entitätstypen systemuser und team unterstützt:

<EntityType Name="teammembership"
    BaseType="mscrm.crmbaseentity">
    <Key>
        <PropertyRef Name="teammembershipid" />
    </Key>
    <Property Name="systemuserid"
        Type="Edm.Guid" />
    <Property Name="versionnumber"
        Type="Edm.Int64" />
    <Property Name="teammembershipid"
        Type="Edm.Guid" />
    <Property Name="teamid"
        Type="Edm.Guid" />
</EntityType>

Sie können nicht direkt mit Entitätstypen arbeiten, die Schnittmengentabellen darstellen, da alle Eigenschaften schreibgeschützt sind. Führen Sie Operationen für die jeweiligen sammlungswertigen Navigationseigenschaften für jeden Entitätstyp durch. Mehr Informationen: Tabellenzeilen mithilfe der Web-API zurordnen und ihre Zuordnung aufheben.

Für diese m:m-Beziehung hat der Typ systemuser Entität die folgende Navigationseigenschaft mit dem Wert einer Sammlung:

<NavigationProperty Name="teammembership_association"
    Type="Collection(mscrm.team)"
    Partner="teammembership_association" />

Der Entitätstyp team hat diese sammlungsbewertete Navigationseigenschaft:

<NavigationProperty Name="teammembership_association"
    Type="Collection(mscrm.systemuser)"
    Partner="teammembership_association" />

Diese Werte werden in Beziehungsdefinitionen gespeichert. Sie können über den SDK ManyToManyRelationshipMetadata oder den Web-API ManyToManyRelationshipMetadata Typ der Entitäten darauf zugreifen, wie in der folgenden Tabelle beschrieben.

Attribute ManyToManyRelationshipMetadata-Eigenschaft Beschreibung
Name Entity1NavigationPropertyName Der Name der sammlungswertigen Navigationseigenschaft für einen der Typen von Entitäten
Partner Entity2NavigationPropertyName Der Name der Navigationseigenschaft mit dem Wert „collection“ für den anderen Typ der Entität

Nächste Schritte,

Erfahren Sie mehr über Aktionsdefinitionen.

Aktionsdefinitionen

Siehe auch

Internet API-Typen und -Vorgänge
Web-API-Dienstdokumente
Web API EntityTypes
Web-API-Eigenschaften
Web-API-Aktionen
Web-API-Funktionen
Web-API komplexe Typen und Aufzählungstypen
Verwenden Sie die Web-API Dataverse
OData-Version 4.0 Teil 3: Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty

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