Web API を使用したクエリメタデータ

[アーティクル]
03/04/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Microsoft Dynamics 365 はメタデータ駆動型アプリケーションであるため、開発者は実行時にシステムメタデータをクエリして、組織が構成されている方法に適合させる必要があります。この機能は、RetrieveMetadataChangesRequest および Microsoft.Xrm.Sdk.Metadata.Query 名前空間のクラスを使用することによって、組織サービスを使用するだけでなく、Web API を使用して利用することができます。 Web API は、メタデータのクエリを可能にしますが、任意の時点からのメタデータの変更を検出する機能は備えていません。

このトピックの内容

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

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

属性の取得

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

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

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

EntityMetadata をクエリするとき、Web API を使用したクエリデータに記載されているのと同じ方法を使用します。この方法にはいくつかのバリエーションがあります。EntityDefinitions エンティティセットパスを使用して、EntityMetadata EntityType に関する情報を取得します。EntityMetadata エンティティには多数のデータが含まれているので、必要なデータのみを慎重に取得する必要があります。次の例は、Account エンティティのメタデータの DisplayName、IsKnowledgeManagementEnabled、および EntitySetName プロパティだけに対して返されるデータを示しています。MetadataId プロパティ値は常に返されます。

要求

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName&$filter=SchemaName eq 'Account' 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": "cc_WebAPI_ServiceURI/$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 cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

$filter 操作で複合型の使用

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

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

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

EntityMetadata 属性をクエリ

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

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')

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

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

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

注意

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

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

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

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

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

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

属性の取得

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

要求

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$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": "cc_WebAPI_ServiceURI/$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 cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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 が分かっていなければ、それらのすべてを取得することになります。グローバルオプションセットを使用する属性の GlobalOptionSet の単一値のナビゲーションプロパティ内から、グローバルオプションセットの定義にアクセスすることもできます。これは、すべての Entity types that inherit from activitypointer に対して使用できます。詳細:属性の取得

Web API を使用したクエリメタデータ

このトピックの内容

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

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

関連項目

その他のリソース

Web API を使用したクエリ メタデータ

このトピックの内容

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

$filter 操作で enum 型の使用

$filter 操作で複合型の使用

EntityMetadata 属性をクエリ

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

属性の取得

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

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

関連項目

その他のリソース

Web API を使用したクエリメタデータ

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