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

[アーティクル]
03/15/2023

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

注意

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

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

EntityMetadata をクエリするとき、Web API を使用したデータのクエリに記載されているのと同じ方法を使用しますが、いくつかのバリエーションがあります。 EntityDefinitions エンティティセットパスを使用して、EntityMetadata EntityType に関する情報を取得します。 EntityMetadata エンティティには多数のデータが含まれているので、必要なデータのみを慎重に取得する必要があります。次の例では、Account エンティティの定義の DisplayName、IsKnowledgeManagementEnabled、および 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 を使用して true の Value を持つエンティティのみを返すことができます。

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 値が Picklist の AttributeTypeCode 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'

属性の取得

EntityMetadata と AttributeMetadata の両方の 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 システムクエリオプションでプロパティを制限できます。次の例では、OptionSet の Options プロパティのみが含まれます。

要求:

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

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

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 派生型に使用できます。詳細: 属性の取得

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

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

返される言語を制限する

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

例: MetadataId を使用する

名前による例

関連項目

フィードバック

その他のリソース

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

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

返される言語を制限する

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

例: MetadataId を使用する

名前による例

関連項目

フィードバック

その他のリソース

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