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

[アーティクル]
04/08/2022

注意

エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

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.0/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.0/$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 を使用することができます。

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

$filter 操作で enum 型の使用

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

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

$filter 操作で複合型の使用

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

GET [Organization URI]/api/data/v9.0/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.0/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.0/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

注意

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

このもう 1 つの例は、MoneyAttributeMetadata EntityType および DecimalAttributeMetadata EntityType 属性で使用できる Precision プロパティへのアクセスです。このプロパティにアクセスするには、これらの属性のコレクションを MoneyAttributeMetadata EntityType または DecimalAttributeMetadata EntityType としてキャストする必要があります。 MoneyAttributeMetadata へのキャストを示す例を以下に示します。

GET [Organization URI]/api/data/v9.0/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.0/EntityDefinitions(LogicalName='account')/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

属性の取得

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

要求

GET [Organization URI]/api/data/v9.0/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.0/$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.0/$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.0/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.0/$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.0/GlobalOptionSetDefinitions(08fa2cb2-e3fe-497a-9b5d-ee887f5cc3cd)

例: 名前を使用する

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

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

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

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

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

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

例: MetadataId を使用する

例: 名前を使用する

関連項目

フィードバック

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

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

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

例: MetadataId を使用する

例: 名前を使用する

関連項目

フィードバック

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