Propriétés de navigation de l’API web

Article
08/24/2023

Au sein du document de $métadonnées CSDL, chaque type d’entité qui n’est pas abstrait aura des éléments NavigationProperty. Les éléments NavigationProperty décrivent les données relatives au type d’entité actuel. Lorsque vous récupérez un enregistrement, vous pouvez développer les propriétés de navigation pour inclure les données associées.

Le tableau suivant décrit les attributs des éléments NavigationProperty.

Attribute	Description
`Name`	Nom de la propriété de navigation ; sensible à la casse
`Type`	Le type d’entité associé ; il peut s’agir d’une valeur unique ou d’une collection d’un type
`Partner`	Le nom de la propriété de navigation de l’autre côté de la relation
`Nullable="false"`	Indique si la valeur peut être nulle

Important

Il existe deux types de propriétés de navigation : à valeur unique et à valeur de collection. Cette distinction est importante, car les capacités de chaque type de propriété de navigation sont différentes.

Lorsqu’une propriété de navigation Type fait référence à une valeur unique, elle représente une relation un-à-plusieurs pour définir une référence à un autre enregistrement de table. Cette relation est généralement appelée une recherche. L’exemple suivant est la propriété de navigation createdby de la table account :

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

Cette propriété de navigation à valeur unique connecte plusieurs enregistrements account à un seul enregistrement systemuser. Chaque enregistrement systemuser aura une propriété de navigation à valeur de collection nommée lk_accountbase_createdby qui les relie aux enregistrements account créés.

Ces valeurs sont stockées dans des définitions de relation. Vous pouvez y accéder à l’aide du SDK OneToManyRelationshipMetadata ou du type d’entité API Web OneToManyRelationshipMetadata, comme décrit dans la table suivante.

Attribute	Propriété OneToManyRelationshipMetadata	Description
`Name`	`ReferencingEntityNavigationPropertyName`	Nom de la propriété de navigation à valeur unique.
`Partner`	`ReferencedEntityNavigationPropertyName`	Nom de la propriété de navigation à valeur de collection.

Propriétés de recherche

Les propriétés de navigation à valeur unique ont un ReferentialConstraint avec un attribut Property qui fait référence à une propriété de recherche. Les propriétés de recherche utilisent la convention de dénomination suivante : _<name>_value. Découvrir les propriétés de recherche.

La ReferentialConstraint a un attribut ReferencedProperty qui identifie le nom de la clé primaire du type d’entité associé.

Dans la plupart des cas, le <name> trouvé dans la propriété de recherche correspond au nom de la propriété de navigation, sauf si la propriété de navigation à valeur unique représente une recherche multi-tables.

Recherches multi-tables

Lorsque la propriété de navigation à valeur unique fait partie d’une recherche multi-tables (ou polymorphe), il y aura une seule propriété de recherche qui est la ReferentialConstraint pour plusieurs propriétés de navigation à valeur unique.

Un type d’entité peut avoir quelque chose comme la combinaison suivante où une seule propriété de recherche _customerid_value prend en charge plusieurs propriétés de navigation à valeur unique qui représentent une recherche multi-tables. Il y aura une propriété de navigation à valeur unique pour chaque type de table pris en charge par la recherche multi-tables.

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

Dans ces cas, la définition de la valeur de l’une des propriétés de navigation à valeur unique définit toutes les autres propriétés de navigation à valeur unique participantes sur null. La valeur GUID de la propriété de recherche correspondante changera, mais vous devrez récupérer des annotations spécifiques disponibles pour savoir à quelle table elle fait maintenant référence. Plus d’informations : Rechercher les données de propriété

Lorsqu’une propriété de navigation Type fait référence à une valeur de collection, elle représente une relation plusieurs-à-un ou plusieurs-à-plusieurs. L‘exemple suivant est la propriété de navigation Account_Tasks de l’entité de compte :

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

Cette propriété de navigation connecte un enregistrement account à plusieurs enregistrements task. Chaque task possède une propriété de navigation à valeur unique nommée regardingobjectid_account_task qui fait référence au account comme objet relatif.

La façon dont vous utilisez les propriétés de navigation à valeur de collection à l’aide d’OData est la même, que la relation soit une relation un-à-plusieurs ou plusieurs-à-plusieurs. Les deux sont considérées comme des collections et vous interagissez avec elles de la même manière.

Relations plusieurs-à-un

Une relation plusieurs-à-un est l’image miroir de la relation un-à-plusieurs. Elle aura une propriété de navigation partenaire à valeur unique. Dans l’exemple Propriétés de navigation à valeur unique précédent, nous avons regardé la propriété à valeur unique createdby pour l’entité de type account.

Au sein du type d’entité systemuser, vous trouverez le partenaire de propriété de navigation à valeur de collection nommé lk_accountbase_createdby.

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

Relations plusieurs-à-plusieurs

Lorsque le Name et le Partner de la propriété de navigation à valeur de collection sont identiques, cela représente une relation plusieurs-à-plusieurs.

Les relations plusieurs-à-plusieurs ont des détails de mise en œuvre que vous pouvez trouver dans les documents de service. Dans la plupart des cas d’utilisation, vous pouvez les ignorer.

Par exemple, chaque relation plusieurs-à-plusieurs a une table d’intersection qui la prend en charge. Ces tables d’intersection ont des types d’entité qui n’ont généralement que 4 propriétés en lecture seule. Ce qui suit est un exemple d’entité de type teammembership qui est une table d’intersection qui prend en charge une relation plusieurs-à-plusieurs entre les entités de type systemuser et team.

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

Vous ne pouvez pas utiliser les types d’entités qui représentent directement des tables d’intersection, car toutes les propriétés sont en lecture seule. Effectuez des opérations sur les propriétés de navigation à valeur de collection respectives pour chaque type d’entité. Plus d’informations : Associer et dissocier les lignes de table à l’aide de l’API web

Pour cette relation plusieurs à plusieurs, l’entité de type systemuser a cette propriété de navigation à valeur de collection :

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

L’entité de type team a cette propriété de navigation à valeur de collection :

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

Ces valeurs sont stockées dans des définitions de relation. Vous pouvez y accéder à l’aide du SDK ManyToManyRelationshipMetadata ou du type d’entité API Web ManyToManyRelationshipMetadata, comme décrit dans la table suivante.

Attribute	Propriété ManyToManyRelationshipMetadata	Description
`Name`	`Entity1NavigationPropertyName`	Nom de la propriété de navigation avec une valeur de collection prise en charge pour un de ces types d’entité
`Partner`	`Entity2NavigationPropertyName`	Nom de la propriété de navigation avec une valeur de collection prise en charge pour l’autre type d’entité

Étapes suivantes

Découvrez les définitions d’action.

Définitions de l’action

Voir aussi

Types d’API web et opérations
Documents de service de l’API web
EntityTypes de l’API web
Propriétés de l’API web
Actions de l’API web
Fonctions de l’API web
Types Complex et Enumeration de l’API web
Utiliser l’API Web Dataverse
Partie 3 de la version 4.0 d’OData : Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty

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

Partager via

Propriétés de navigation à valeur unique