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

[アーティクル]
08/24/2023

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

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

Attribute	Description
`Name`	単一値のナビゲーションプロパティの名前: 大文字と小文字を区別する
`Type`	関連したエンティティ型; 単一の値または型のコレクションにすることができる
`Partner`	関連付けの反対側にあるナビゲーションプロパティの名前
`Nullable="false"`	値が null 値である可能性があるかどうか

重要

ナビゲーションプロパティには、single-valued と collection-valued の 2 種類があります。ナビゲーションプロパティのタイプごとに機能が異なるため、この区別は重要です。

ナビゲーションプロパティ 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 エンティティ型を使用してアクセスできます。

Attribute	OneToManyRelationshipMetadata プロパティ	Description
`Name`	`ReferencingEntityNavigationPropertyName`	単一値のナビゲーションプロパティの名前。
`Partner`	`ReferencedEntityNavigationPropertyName`	コレクション値のナビゲーションプロパティの名前。

検索プロパティ

単一値のナビゲーションプロパティには、検索プロパティを参照する 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 エンティティ型を使用してアクセスできます。

Attribute	ManyToManyRelationshipMetadata プロパティ	Description
`Name`	`Entity1NavigationPropertyName`	エンティティ型のコレクション値ナビゲーションプロパティの名前
`Partner`	`Entity2NavigationPropertyName`	他のエンティティ型のコレクション値ナビゲーションプロパティの名前

次の手順

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

操作定義

参照

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

注意

ドキュメントの言語設定についてお聞かせください。簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。個人データは収集されません (プライバシーステートメント)。

次の方法で共有

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

検索プロパティ

マルチテーブル検索

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

多対一関連付け

多対多の関連付け

次の手順

参照

その他のリソース

次の方法で共有

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

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

検索プロパティ

マルチテーブル検索

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

多対一関連付け

多対多の関連付け

次の手順

参照

その他のリソース

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

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

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