Propriedades de navegação da API Web

No documento $metadata CSDL, cada tipo de entidade que não é abstrato tem NavigationProperty elementos. NavigationProperty os elementos descrevem dados relacionados ao tipo de entidade atual. Ao recuperar um registro, você pode expandir as propriedades de navegação para incluir dados relacionados.

A tabela a seguir descreve os atributos dos NavigationProperty elementos.

Attribute	Description
`Name`	O nome da propriedade de navegação; diferencia maiúsculas de minúsculas
`Type`	O tipo de entidade relacionado; pode corresponder a um único valor ou a uma coleção de um tipo
`Partner`	O nome da propriedade de navegação do outro lado do relacionamento
`Nullable="false"`	Se o valor pode ser nulo

Importante

Há dois tipos de propriedades de navegação: com valor único e com valor de coleção. Essa distinção é importante porque os recursos de cada tipo de propriedade de navegação são diferentes.

Ao construir uma consulta com OData, não nos referimos a relacionamento de um para muitos, de muitos para um ou de muitos para muitos. Os dois tipos de propriedades de navegação descrevem como navegar nessas relações.

Quando uma propriedade Type de navegação se refere a um único valor, ela representa uma relação um para muitos que cria uma referência a outro registro de tabela. Essa relação geralmente é chamada de consulta. O exemplo a seguir é a propriedade de navegação da account tabela createdby :

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

Essa propriedade de navegação com valor único conecta vários account registros a um único systemuser registro. Cada registro systemuser tem uma propriedade de navegação com valor de coleção chamada lk_accountbase_createdby que account os conecta aos registros que o usuário criou.

Esses valores são armazenados em definições de relação. Você pode acessá-los usando o SDK OneToManyRelationshipMetadata ou o tipo de entidade da API OneToManyRelationshipMetadata Web, conforme descrito na tabela a seguir.

Attribute	Propriedade OneToManyRelationshipMetadata	Description
`Name`	`ReferencingEntityNavigationPropertyName`	O nome da propriedade de navegação com valor único.
`Partner`	`ReferencedEntityNavigationPropertyName`	O nome da propriedade de navegação com valor de coleção.

Propriedades de pesquisa

As propriedades de navegação com valor único têm um ReferentialConstraint com um atributo Property que se refere a uma propriedade de pesquisa. As propriedades de pesquisa usam a seguinte convenção de nomenclatura: _<name>_value. Saiba mais sobre as propriedades de pesquisa.

O ReferentialConstraint tem um ReferencedProperty atributo que identifica o nome da chave primária do tipo de entidade relacionado.

Na maioria dos casos, a propriedade <name> encontrada na pesquisa corresponde ao nome da propriedade de navegação, exceto quando a propriedade de navegação com valor único representa uma pesquisa de várias tabelas.

Consultas em várias tabelas

Quando a propriedade de navegação com valor único faz parte de uma busca multitabela ou polimórfica, uma única propriedade de busca é a ReferentialConstraint de mais de uma propriedade de navegação de valor único.

Um tipo de entidade pode ter algo semelhante à combinação a seguir, em que uma única _customerid_value propriedade de pesquisa dá suporte a várias propriedades de navegação de valor único que representam uma pesquisa de várias tabelas. Há uma propriedade de navegação com único valor para cada tipo de tabela que é compatível com a pesquisa em várias tabelas.

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

Nesses casos, definir o valor de qualquer uma das propriedades de navegação com valor único define todas as outras propriedades de navegação de valor único participante como nulas. O valor GUID da propriedade de pesquisa correspondente é alterado, mas você precisa obter anotações específicas para saber a qual tabela ela se refere agora. Mais informações: Consultar dados da propriedade

Quando uma propriedade Type de navegação se refere a um valor de coleção, ela representa um relacionamento muitos para um ou muitos para muitos. O exemplo a seguir é a propriedade de navegação da entidade Account_Tasks da conta:

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

Essa propriedade de navegação conecta um account registro a muitos task registros. Cada task tem uma propriedade de navegação de valor único chamada regardingobjectid_account_task que se refere ao account como o objeto correspondente.

A maneira como você trabalha com propriedades de navegação com valor de coleção usando OData é a mesma, independentemente de o relacionamento ser um para muitos ou muitos para muitos. Ambas são consideradas coleções e você interage com elas da mesma maneira.

Relacionamentos muitos para um

Um relacionamento muitos para um é a imagem espelhada de um relacionamento um para muitos. Ele tem uma propriedade de navegação de parceiro com valor único. No exemplo de propriedades de navegação com valor único anteriores, examinamos a createdby propriedade de navegação com valor único para o account tipo de entidade.

No tipo de entidade systemuser, existe o parceiro de propriedade de navegação com valor de coleção nomeado lk_accountbase_createdby.

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

Relacionamentos de muitos para muitos

Quando a Name e a Partner da propriedade de navegação com valor de coleção são as mesmas, isso representa um relacionamento muitos para muitos.

Relacionamentos muitos para muitos têm alguns detalhes de implementação que você pode encontrar nos documentos de serviço. Para a maioria dos casos de uso, você pode ignorá-los.

Por exemplo, cada relacionamento muitos para muitos tem uma tabela de interseção que a suporta. Essas tabelas de interseção têm tipos de entidade que normalmente têm quatro propriedades somente leitura. No exemplo a seguir, o tipo de entidade teammembership é uma tabela de interseção que dá suporte a um relacionamento muitos para muitos entre os tipos de entidade systemuser e 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>

Você não pode trabalhar com tipos de entidade que representam tabelas de intersecção diretamente porque todas as propriedades são somente leitura. Execute operações nas respectivas propriedades de navegação com valor de coleção para cada tipo de entidade. Mais informações: Associar e desassociar linhas de tabela usando a API Web

Para esse relacionamento muitos para muitos, o tipo de entidade systemuser tem a seguinte propriedade de navegação com valor de coleção:

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

O tipo de entidade team tem essa propriedade de navegação com valor de coleção:

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

Esses valores são armazenados em definições de relação. Você pode acessá-los usando o SDK ManyToManyRelationshipMetadata ou o tipo de entidade da API ManyToManyRelationshipMetadata Web, conforme descrito na tabela a seguir.

Attribute	Propriedade ManyToManyRelationshipMetadata	Description
`Name`	`Entity1NavigationPropertyName`	O nome da propriedade de navegação com valor de coleção para um dos tipos de entidade
`Partner`	`Entity2NavigationPropertyName`	O nome da propriedade de navegação com valor de coleção para o outro tipo de entidade

Próximas etapas

Saiba mais sobre definições de ação.

Definições de ação

Consulte também

Tipos e operações de API Web
Documentos do serviço de API Web
Web API EntityTypes
Propriedades da API Web
Ações de API Web
Funções de API Web
Tipos complexos e de enumeração de API Web
Utilizar a API Web do Dataverse
OData-Versão: 4.0. Parte 3: CSDL (Common Schema Definition Language) Plus Errata 03 7.1 Element edm:NavigationProperty

Feedback

Esta página foi útil?

Last updated on 2026-01-19

Partilhar via

Propriedades de navegação de valor único