Propiedades de navegación de la API web

Artículo
08/24/2023

En el documento $metadata de CSDL, cada tipo de entidad que no sea abstracta tiene elementos NavigationProperty. Los elementos NavigationProperty describen los datos relacionados con el tipo de entidad actual. Cuando recupere un registro, puede expandir las propiedades de navegación para incluir los datos relacionados.

La siguiente tabla describe los atributos de los elementos NavigationProperty.

Attribute	Descripción
`Name`	El nombre de la propiedad de navegación; distingue mayúsculas de minúsculas
`Type`	El tipo de entidad realcionado; puede ser para un solo valor o una colección de un tipo
`Partner`	El nombre de la propiedad de navegación en el otro lado de la relación
`Nullable="false"`	Si el valor puede ser NULL

Importante

Hay dos tipos de propiedades de navegación: un solo valor y valoradas como colección. Esta distinción es importante porque las funciones de cada tipo de propiedad de navegación son diferentes.

Cuando una propiedad de navegación Type se refiere a un solo valor, representa una relación de uno a varios que crea una referencia a otro registro de la tabla. Esta relación habitualmente se denomina búsqueda. El siguiente ejemplo es la propiedad de navegación account tabla createdby:

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

Esta propiedad de navegación de un solo valor conecta múltiples registros account a un solo registro systemuser. Cada registro systemuser tiene una propiedad de navegación valorada como colección denominada lk_accountbase_createdby que lo conecta con los registros account que el usuario ha creado.

Estos valores se almacenan en definiciones de relaciones. Puede acceder a ellos utilizando el tipo de entidad SDK OneToManyRelationshipMetadata o Web API OneToManyRelationshipMetadata, como se describe en la siguiente tabla.

Attribute	Propiedad OneToManyRelationshipMetadata	Descripción
`Name`	`ReferencingEntityNavigationPropertyName`	El nombre de la propiedad de navegación de un solo valor.
`Partner`	`ReferencedEntityNavigationPropertyName`	El nombre de la colección de navegación de un solo valor.

Propiedades de búsqueda

Las propiedades de navegación de un solo valor tienen un atributo ReferentialConstraint con un atributo Property que hace referencia a una propiedad de búsqueda. Las propiedades de búsqueda utilizan la siguiente convención de nomenclatura: _<name>_value. Obtenga más información acerca de las propiedades de búsqueda.

El atributo ReferentialConstraint tiene un atributo ReferencedProperty que identifica el nombre de la clave principal del tipo de entidad relacionada.

En la mayoría de los casos el <name> encontrado en la propiedad de búsqueda coincide con el nombre de la propiedad de navegación, excepto cuando la propiedad de nabegación de un valor represnta una búsqueda en varias tablas.

Búsquedas en varias tablas

Cuando la propiedad de navegación de un solo valor forma parte de una búsqueda de varias tablas, o polimórfica, hay una única propiedad de búsqueda que es ReferentialConstraint para más de una propiedad de navegación de un solo valor.

Un tipo de entidad puede tener algo como la siguiente combinación, donde una sola propiedad de búsqueda _customerid_value admite varias propiedades de navegación de un solo valor que representan una búsqueda en varias tablas. Hay una propiedad de navegación de un solo valor para cada tipo de tabla admitida por la búsqueda de varias tablas.

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

En estos casos, establecer el valor de cualquiera de las propiedades de navegación de un solo valor establece todas el resto de propiedades de navegación de un solo valor participantes en NULL. El valor GUID de la propiedad de búsqueda correspondiente cambia, pero debe recuperar las anotaciones específicas disponibles para saber a qué tabla se refiere ahora. Más información: Buscar datos de propiedades

Cuando una propiedad de navegación Type se refiere a un valor de colección, representa una relación de varios a uno o de varios a varios. El ejemplo siguienet es la propiedad de navegación Account_Tasks de la entidad de cuenta:

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

Esta propiedad de navegación conecta un registro account a varios registros task. Cada task tiene una propiedad de navegación de un solo valor llamada regardingobjectid_account_task que se refiere a la account como el objeto referente.

La forma en que trabaja con las propiedades de navegación valoradas como colección mediante OData es la misma independientemente de si la relación es de uno a varios o de varios a varios. Ambas se consideran colecciones y se interactúa con ellas de la misma manera.

Relaciones de varios a uno

Una relación de varios a uno es una imagen reflejada de una relación de uno a varios. Tiene una propiedad de navegación de un solo valor de partner. En el ejemplo Propiedades de navegación de un solo valor anterior, vimos la propiedad createdby de navegación de un solo valor para el tipo de entidad account.

En el tipo de entidad systemuser, existe el partner de la propiedad de navegación valorada como colección denominada lk_accountbase_createdby.

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

Relaciones de varios a varios

Cuando Name y Partner de la propiedad de navegación valorada como colección son iguales, representa una relación de varios a varios.

Las relaciones varios a varios tiene algunos detalles de implementación que puede encontrar en los documentos de servicio. Para la mayoría de los casos de uso, puede ignorarlos.

Por ejemplo, cada relación de varios a varios tiene una tabla de intersección que la respalda. Estas tablas de intersección tienen tipos de entidad que normalmente tienen solo cuatro propiedades de solo lectura. En el siguiente ejemplo, el tipo de entidad teammembership es una tabla de intersección que admite una relación de varios a varios entre tipos de entidad systemuser y 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>

No puede trabajar con tipos de entidad que representan tablas de intersección directamente porque todas las propiedades son de solo lectura. Realice operaciones en las respectivas propiedades de navegación valoradas como colección para cada tipo de entidad. Más información: Asociar y anular la asociación de filas de tabla usando la API web.

Para esta relación de varios a varios, el tipo de entidad systemuser tiene la siguiente propiedad de navegación valorada como colección:

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

El tipo de entidad team tiene esta propiedad de navegación valorada como colección:

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

Estos valores se almacenan en definiciones de relaciones. Puede acceder a ellos utilizando el tipo de entidad SDK ManyToManyRelationshipMetadata o Web API ManyToManyRelationshipMetadata, como se describe en la siguiente tabla.

Attribute	Propiedad ManyToManyRelationshipMetadata	Descripción
`Name`	`Entity1NavigationPropertyName`	El nombre de la propiedad de navegación valorada como colección para uno de los tipos de entidad
`Partner`	`Entity2NavigationPropertyName`	El nombre de la propiedad de navegación valorada como colección para el otro tipo de entidad

Pasos siguientes

Obtenga más información sobre las definiciones de acción.

Definiciones de acción

Consulte también

Tipos y operaciones de API web
Documentos de servicio de la API web
EntityTypes de la API web
Propiedades de API web
Acciones de la API web
Funciones de la API web
Tipos complejos y de enumeración de API web
Usar la API web de Dataverse
OData Version 4.0. Part 3: Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Compartir a través de

Propiedades de navegación de un solo valor