次の方法で共有


Web API を使用したテーブル定義のクエリ

Microsoft Dataverse はメタデータ駆動型アプリケーションであるため、開発者は、組織の構成方法に適応するために、実行時にシステム定義をクエリする必要がある場合があります。 この機能は RESTful クエリ スタイルを使用します。

注意

また、EntityQueryExpression ComplexTypeRetrieveMetadataChanges Function.を使用するオブジェクト ベース スタイルを使用してクエリを作成できます。 この関数は、2 つの期間の間のテーブル定義への変更をキャプチャしたり、指定したクエリによって記述された限定された定義のセットを返すことができます。 詳細: セグメントクエリの定義

EntityMetadata エンティティ型をクエリ

EntityMetadataをクエリするときは、いくつかの違いはありますが、「 Web APIを使用してデータをクエリする 」で説明したのと同じ手法を使用します。 EntityDefinitions エンティティ セット パスを使用して、EntityMetadata EntityType に関する情報を取得します。 EntityMetadata エンティティには多数のデータが含まれているので、必要なデータのみを慎重に取得する必要があります。 次の例では、Account エンティティの定義の DisplayNameIsKnowledgeManagementEnabled、および EntitySetName プロパティだけに対して返されるデータを表示します。 MetadataId プロパティ値は常に返されます。

要求:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{  
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(DisplayName,IsKnowledgeManagementEnabled,EntitySetName)",  
 "value": [  
  {  
   "DisplayName": {  
    "LocalizedLabels": [  
     {  
      "Label": "Account",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Account",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "IsKnowledgeManagementEnabled": false,  
   "EntitySetName": "accounts",  
   "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84"  
  }  
 ]  
}  
  

$select システム クエリ オプションが付いた EntityMetadata プロパティのいずれかを使用することが可能であり、またプリミティブ値や列挙値を使用するプロパティに対して $filter を使用することができます。

クエリで返されるエンティティ メタデータの数に制限はありません。 ページ区切りはありません。 すべての一致するリソースが最初の応答で返されます。

返される言語を制限する

環境に多くの言語がプロビジョニングされている場合、返されるデータの量が増大する可能性があります。 最高のパフォーマンスを得るには、LabelLanguages パラメーターを使用して、返される言語の LCID 値を使用して、返される言語ラベルを制限します。

言語コードは 4 桁または 5 桁のロケール ID です。 有効なロケール ID 値は、ロケール ID (LCID) の一覧のページで確認できます。

たとえば、次を追加すると、ローカライズされた言語ラベルが英語に制限されます: &LabelLanguages=1033

$filter 操作で enum 型の使用

列挙を使用するプロパティの値に基づいてエンティティ メタデータをフィルター処理する必要がある場合は、その文字列値の前に、その列挙の名前空間を含める必要があります。 Enum 型は、エンティティ メタデータおよび複合型のみのプロパティ値として使用されます。 たとえば、OwnershipTypes Enumtype を使用する OwnershipType プロパティに基づいてエンティティをフィルター処理する必要がある場合、次の $filter を使用して UserOwned であるエンティティのみを返すことができます。

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'  

$filter 操作で複合型の使用

複合型を使用するプロパティの値に基づいてエンティティ メタデータをフィルター処理する必要がある場合は、その文字列値の前に、基になるプリミティブ型へのパスを含める必要があります。 複合型は、エンティティ メタデータのみのプロパティ値として使用されます。 たとえば、BooleanManagedProperty ComplexType を使用する CanCreateAttributes プロパティに基づいてエンティティをフィルター処理する必要がある場合、次の $filter を使用して trueValue を持つエンティティのみを返すことができます。

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true  

このパターンは、チェックの対象のプリミティブ値は 1 レベル深いので、BooleanManagedProperty ComplexType に対して機能します。 ただし、これは Label ComplexType のプロパティでは機能しません。

EntityMetadata 属性をクエリ

Attributes コレクション値ナビゲーション プロパティを拡張することによってエンティティのコンテキストでエンティティ属性をクエリできますが、これには、すべての属性が共有する AttributeMetadata EntityType で使用できる一般的なプロパティのみが含まれます。 たとえば、次のクエリは、そのエンティティの LogicalName と、AttributeType 値が PicklistAttributeTypeCode EnumType 値と等しい、すべての展開された属性を返します。

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')  

PicklistAttributeMetadata EntityType 属性のこのクエリの $select フィルターの範囲内にある、OptionSet または GlobalOptionSet コレクションの値ナビゲーション プロパティを含めることはできません。

特定の種類の属性のプロパティを取得するには、Attributes コレクション値ナビゲーション プロパティを必要な型にキャストする必要があります。 次のクエリは PicklistAttributeMetadata EntityType 属性のみを返し、このクエリには LogicalName だけでなく、OptionSet および GlobalOptionSet コレクション値ナビゲーション プロパティの展開も含まれます

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet  

注意

OptionSet および GlobalOptionSet コレクション値ナビゲーション プロパティが EnumAttributeMetadata EntityType, 内で定義されているにもかかわらず、これらの属性をこの型にキャストすることはできません。 すなわち、これらのプロパティも継承する他の種類に対してフィルター処理が必要な場合 (「EnumAttributeMetadata から継承するエンティティの種類」を参照)、種類ごとにフィルター処理するためにクエリを別々に実行する必要があります。

また、MoneyAttributeMetadata EntityType 属性と DecimalAttributeMetadata EntityType 属性で利用できる Precision 属性にアクセスすることもその例です。 このプロパティにアクセスするには、属性コレクションを MoneyAttributeMetadata EntityType または DecimalAttributeMetadata EntityType のいずれかにキャストする必要があります。 MoneyAttributeMetadata へのキャストを示す例を以下に示します。

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

必要なレベル別のフィルター処理

AttributeMetadata EntityType RequiredLevel プロパティは、Value プロパティが AttributeRequiredLevel EnumType であるところ、特殊な AttributeRequiredLevelManagedProperty ComplexType を使用します。 この場合には、$filter 操作で複合型の使用$filter 操作で enum 型の使用 にあるパターンを結合して、この固有のプロパティでフィルター処理する必要があります。 次のクエリでは、ApplicationRequired である取引先企業エンティティの属性をフィルター処理します。

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'  

属性の取得

EntityMetadataAttributeMetadata の両方の MetadataId が分かっている場合、または LogicalName の値をわかっている場合、次のようにクエリを使用して、個々の属性を取得してプロパティにアクセスできます。 このクエリは、OptionSet コレクション値ナビゲーション プロパティの展開だけでなく、この属性の LogicalName プロパティを取得します。 Microsoft.Dynamics.CRM.PicklistAttributeMetadata として属性をキャストし、OptionSet コレクション値ナビゲーション プロパティにアクセスする必要があります。

要求:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet)/$entity",  
"LogicalName": "preferredappointmentdaycode",  
"MetadataId": "5967e7cc-afbb-4c10-bf7e-e7ef430c52be",  
"OptionSet@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet/$entity",  
"OptionSet": {  
 "Options": [  
  {  
   "Value": 0,  
   "Label": {  
    "LocalizedLabels": [  
     {  
      "Label": "Sunday",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Sunday",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "Description": {  
    "LocalizedLabels": [],  
    "UserLocalizedLabel": null  
   },  
   "Color": null,  
   "IsManaged": true,  
   "MetadataId": null,  
   "HasChanged": null  
  }  
Additional options removed for brevity  
 ],  
 "Description": {  
  "LocalizedLabels": [  
   {  
    "Label": "Day of the week that the account prefers for scheduling service activities.",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Day of the week that the account prefers for scheduling service activities.",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
   "HasChanged": null  
  }  
 },  
 "DisplayName": {  
  "LocalizedLabels": [  
   {  
    "Label": "Preferred Day",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Preferred Day",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
   "HasChanged": null  
  }  
 },  
 "IsCustomOptionSet": false,  
 "IsGlobal": false,  
 "IsManaged": true,  
 "IsCustomizable": {  
  "Value": true,  
  "CanBeChanged": false,  
  "ManagedPropertyLogicalName": "iscustomizable"  
 },  
 "Name": "account_preferredappointmentdaycode",  
 "OptionSetType": "Picklist",  
 "IntroducedVersion": null,  
 "MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735",  
 "HasChanged": null  
}  
}  

この属性のどのプロパティも必要とせず、OptionsSet などのコレクション値ナビゲーション プロパティの値のみが必要な場合は、それを URL に含めて、多少クエリの効率を上げるために、$select システム クエリ オプションでプロパティを制限できます。 次の例では、OptionSetOptions プロパティのみが含まれます。

要求:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet?$select=Options HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
OData-MaxVersion: 4.0  
OData-Version: 4.0  

応答:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{  
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions('account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",  
"Options": [{  
  "Value": 0,  
  "Label": {  
   "LocalizedLabels": [{  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }],  
   "UserLocalizedLabel": {  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }  
  },  
  "Description": {  
   "LocalizedLabels": [],  
   "UserLocalizedLabel": null  
  },  
  "Color": null,  
  "IsManaged": true,  
  "MetadataId": null,  
  "HasChanged": null  
 }  
Additional options removed for brevity  
],  
"MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735"  
}  

関連付けのメタデータのクエリ

属性のクエリとほぼ同じ方法で、特定のエンティティのコンテキストで、関連付けメタデータを取得することができます。 ManyToManyRelationshipsManyToOneRelationships、および OneToManyRelationships コレクション値ナビゲーション プロパティは、Attributes コレクション値ナビゲーション プロパティと同様にクエリすることができます。 詳細: EntityMetadata 属性をクエリ

ただし、エンティティ関連付けも、RelationshipDefinitions エンティティ セットを使用してクエリすることができます。 次のようなクエリを使用して、すべての関連付けの SchemaName プロパティを取得できます。

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions?$select=SchemaName  

このプロパティはこのエンティティ セットをクエリしたときに使用可能になり、その使用は RelationshipMetadataBase EntityType のプロパティに限定されます。 RelationshipMetadataBase から継承するエンティティの種類からプロパティにするには、次のようなクエリに含めて、OneToManyRelationshipMetadata EntityType のみを返す必要があります。

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName  

返されるエンティティは OneToManyRelationshipMetadata として型指定されるので、ReferencedEntity などのプロパティに対してフィルター処理を行って、次のクエリに示されるように、取引先企業エンティティなどの特定のエンティティの一対多のエンティティ関連付けのみを返すクエリを作成することができます。

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account' 

このクエリは、取引先企業エンティティの EntityMetadataOneToManyRelationships コレクション値ナビゲーション プロパティに含まれているため、基本的には、フィルター処理される次のクエリと同じ結果を返します。 その違いは、前のクエリの場合は、取引先企業エンティティの MetadataId を知る必要がないということです。

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/OneToManyRelationships?$select=SchemaName  

グローバル オプション セットのクエリ

GlobalOptionSetDefinitions エンティティ セット パスを使用してグローバル オプション セットに関する情報を取得できますが、このパスは、$filter システム クエリ オプションの使用をサポートしていません。 したがって、単一のグローバル オプション セットは、MetadataId または一意の名前でのみ入手できます。

例: MetadataId を使用する

次の例は、MetadataId を使用してグローバル オプション セットを取得する方法を示します。

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(08fa2cb2-e3fe-497a-9b5d-ee887f5cc3cd)

名前による例

次の例は、名前を使用してグローバル オプション セットを取得する方法を示します。

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(Name='incident_caseorigincode')

グローバル オプション セットを使用する属性の GlobalOptionSet の単一値のナビゲーション プロパティ内から、グローバル オプション セットの定義にアクセスすることもできます。 これはすべての EnumAttributeMetadata EntityType 派生型に使用できます。 詳細: 属性の取得

関連項目

Dataverse メタデータで Web API を使用する
名前または MetadataId でのメタデータの取得
Web API を使用したメタデータのエンティティおよび属性
Web API を使用したエンティティ関係のモデリング
Web API テーブル スキーマ操作サンプル
Web API テーブル スキーマ操作サンプル (C#)

注意

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

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