Web API ナビゲーション プロパティ

CSDL $metadata ドキュメント 内で、抽象的でない各エンティティ型は NavigationProperty 要素を含みます。 NavigationProperty 要素は、現在のエンティティ型に関連するデータを記述します。 レコードの取得時に、関連データを含めるためにナビゲーション プロパティを拡張することができます。

次の表に、NavigationProperty 要素の属性を説明します。

単一値ナビゲーション プロパティ

ナビゲーション プロパティ Type が単一の値を参照する場合、別のテーブル レコードへの参照を作成する 1 対多の関係を表します。 この関連付けは通常検索と呼ばれます。 次の例は、account テーブル createdby ナビゲーション プロパティです。

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

この単一値のナビゲーション プロパティは、複数の account レコードを単一の systemuser レコードに接続します。 各 systemuser レコードには、ユーザーが作成した account レコードに接続する lk_accountbase_createdby という名前のコレクション値のナビゲーション プロパティが含まれるようになります。

これらの値は関連付け定義に保存されます。 次の表で説明するように、SDK OneToManyRelationshipMetadata または Web API OneToManyRelationshipMetadata エンティティ型を使用してアクセスできます。

検索プロパティ

単一値のナビゲーション プロパティには、検索プロパティを参照する Property 属性のある ReferentialConstraint があります。 検索プロパティでは、_<name>_value という命名規則が使用されます。 検索プロパティに関する詳細。

ReferentialConstraint には、関連するエンティティ型の主キー名を識別する ReferencedProperty 属性があります。

ほとんどの場合、検索プロパティで表示される <name> は、単一値ナビゲーション プロパティがマルチテーブル検索を表す場合を除いて、ナビゲーション プロパティの名前と一致します。

マルチテーブル検索

単一値のナビゲーション プロパティが、マルチテーブル、またはポリモーフィック、検索の一部である場合、1 つ以上ある単一値のナビゲーション プロパティの ReferentialConstraint である単一の検索プロパティが表示されます。

エンティティ型には次のような組み合わせがあり、単一の _customerid_value 検索プロパティが、マルチテーブル検索を表す複数ある単一値のナビゲーション プロパティをサポートします。 マルチテーブル検索でサポートされるテーブルのタイプごとに、単一値のナビゲーション プロパティが 1 つあります。

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

このような場合、単一値のナビゲーション プロパティのいずれかの値を設定すると、参加している他のすべての単一値のナビゲーション プロパティが null 値に設定されます。 対応する検索プロパティの GUID 値は変更されますが、現在どのテーブルを参照しているかを知るために、使用可能な特定の注釈を取得する必要があります。 詳細情報: プロパティデータの参照

コレクション値ナビゲーション プロパティ

ナビゲーション プロパティ Type がコレクション値を参照する場合、多対一、または多対多の関連付けを表します。 たとえば、これは取引先企業エンティティの Account_Tasks ナビゲーション プロパティです。

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

このナビゲーション プロパティは、account レコードを多数の task レコードに接続します。 各 task には、関係するオブジェクトとして account を参照する regardingobjectid_account_task という名前の単一値ナビゲーション プロパティが含まれます。

OData を使用してコレクション値のナビゲーション プロパティを操作する方法は、関連付けが一対多でも多対多でも同じです。 どちらもコレクションと見なされ、同じ方法で操作します。

多対一関連付け

多対一の関連付けは、一対多の関連付けのミラー イメージです。 パートナーの単一値ナビゲーション プロパティがあります。 以前の単一値のナビゲーション プロパティ の例では、account エンティティ型の createdby 単一値ナビゲーション プロパティを確認しました。

systemuser エンティティ型には、lk_accountbase_createdby という名前のコレクション値ナビゲーション プロパティ パートナーがあります。

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

多対多の関連付け

コレクション値ナビゲーション プロパティの Name と Partner が同じ場合、多対多の関連付けを表します。

サービス ドキュメントで、多対多の関連付けの実装に関する詳細を参照できます。 ほとんどのユース ケースは無視できます。

たとえば、すべての多対多の関連付けには、それをサポートする交差テーブルがあります。 これらの交差テーブルには、通常は 4 つの読み取り専用プロパティしかないエンティティ型があります。 次の例では、systemuser と team エンティティ型間の多対多の関連付けをサポートする交差テーブルである teammembership エンティティ型が示されています。

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

すべてのプロパティが読み取り専用であるため、交差テーブルを直接表すエンティティ型を操作することはできません。 各エンティティ型のそれぞれのコレクション値ナビゲーション プロパティで操作を実行します。 詳細: Web API を使用して、テーブル行を関連付けおよび関連付けを解除する

この多対多の関連付けでは、systemuser エンティティ型には、次のコレクション値ナビゲーション プロパティがあります。

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

team エンティティ型には、このコレクション値ナビゲーション プロパティがあります。

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

これらの値は関連付け定義に保存されます。 次の表で説明するように、SDK ManyToManyRelationshipMetadata または Web API ManyToManyRelationshipMetadata エンティティ型を使用してアクセスできます。

次の手順

アクションの定義について説明します。

参照

Web API の種類および操作
Web API サービス ドキュメント
Web API EntityTypes
Web API プロパティ
Web API アクション
Web API 関数
Web API の複合型および列挙の種類
Dataverse Web API の使用
OData バージョン 4.0 パート 3: Common Schema Definition Language (CSDL) Plus Errata 03 7.1 Element edm:NavigationProperty