웹 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 네임스페이스의 클래스를 사용하여 웹 API뿐만 아니라 조직 서비스를 사용하는 데 이용가능합니다. 웹 API는 메타 데이터 쿼리에 허용되지만 포인트에서 메타 데이터 변경 내용을 제 시간에 검색하는 기능을 제공하지 않습니다.

이 항목의 내용

EntityMetadata 엔터티 형식 쿼리

$필터 작업에 열거 형식 사용

$필터 작업에 복잡한 형식 사용

EntityMetadata 특성을 쿼리

특성 검색

관계 메타데이터 쿼리하기

전역 OptionSets 쿼리하기

EntityMetadata 엔터티 형식 쿼리

몇 가지 변형을 사용하여 EntityMetadata을 쿼할 때 웹 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를 사용할 수 있습니다.

쿼리에서 반환되는 메타 데이터 엔터티 수에는 제한이 없습니다. 페이징이 없습니다. 모든 일치 리소스는 첫 번째 응답에서 반환됩니다.

$필터 작업에 열거 형식 사용

열거형을 사용하는 속성의 값에 따른 메타 데이터 엔터티를 필터링 하려는 경우, 문자열 값 앞에 열겨형의 네임스페이스를 포함해야 합니다. Enum 형식은 메타 데이터 엔터티 및 복합 형식의 속성 값으로 사용됩니다. 예를 들면, OwnershipTypes EnumType를 사용하는 OwnershipType 속성을 기반으로 하는 엔터티를 필터링할 필요가 있는 경우, 다음 $filter를 사용하여 UserOwned인 엔터티만 반환할 수 있습니다.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

$필터 작업에 복잡한 형식 사용

컴플렉스 유형을 사용하는 속성의 값을 기반으로 하는 메타 데이터 엔터티를 필터링 하려는 경우, 밑에 있는 초기 유형으로의 경로를 포함해야 합니다. Complex 형식은 메타 데이터 엔터티에서 속성 값으로 사용됩니다. 예를 들면, BooleanManagedProperty ComplexType를 사용하는 CanCreateAttributes 속성을 기반으로 하는 엔터티를 필터링할 필요가 있는 경우, 다음 $filter를 사용하여 true의 Value를 가지는 엔터티만 반환할 수 있습니다.

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

이 패턴은 BooleanManagedProperty ComplexType와 작동하는데 그 이유는 점검할 초기 값이 한 단계 깊기 때문입니다. 하지만, 이는 Label ComplexType의 속성에서 작동하지 않습니다.

EntityMetadata 특성을 쿼리

Attributes 컬렉션 가치 탐색 속성을 확장하여 엔터티의 컨텍스트에 엔터티 특성을 쿼리할 수 있지만, 이는 모든 특성이 공유하는 AttributeMetadata EntityType에서 이용가능한 공통 속성만 포함하게 됩니다. 예를 들어, 다음 쿼리는 Picklist의 AttributeTypeCode EnumType 값과 동일한 AttributeType 값을 가지고 있는 모든 확장된 Attributes 및 엔티티의 LogicalName를 반환하게 됩니다.

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

하지만 이 쿼리의 $select 필터 내에서 PicklistAttributeMetadata EntityType 특성이 가지고 있는 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 참조), 각 유형에 대해 분리된 쿼리를 수행해야함을 의미합니다.

이것의 또다른 예는 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을 사용합니다. 이 경우, 이 독특한 특성으로 필터링을 하기 위해$필터 작업에 복잡한 형식 사용 및 $필터 작업에 열거 형식 사용에서 발견된 패턴을 결합해야 합니다. 다음 쿼리는 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를 알고 있는 경우, 다음과 같은 쿼리를 사용하여 개별 특성을 검색하고 속성 값에 엑세스할 수 있습니다. 쿼리는 특성의 LogicalName 속성을 검색할 뿐만 아니라 OptionSet 컬렉선-가치 탐색 속성을 확장합니다.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"
}

관계 메타데이터 쿼리하기

특성을 쿼리하는 방법과 거의 동일한 방식으로 주어진 엔터티의 컨텍스트에 있는 관계 메타 데이터를 검색할 수 있습니다.ManyToManyRelationships, ManyToOneRelationships 및 OneToManyRelationships 컬렉션-가치 탐색 속성은 Attributes 컬렉션-가치 탐색 속성과 같은 방식으로 쿼리될 수 있습니다.추가 정보:EntityMetadata 특성을 쿼리

그러나 엔터티 관계는 RelationshipDefinitions 엔터티 집합을 사용하여 쿼리할 수 있습니다. 모든 관계에 대한 SchemaName 속성을 얻기 위해 다음과 같은 쿼리를 사용할 수 있습니다.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

이 엔터티 집합을 쿼리할 때 이용가능한 속성은 RelationshipMetadataBase EntityType에 있는 것들로 제한됩니다.RelationshipMetadataBase에서 나온 엔터티 유형에서 나온 속성에 엑세스하려면, 다음과 같이 OneToManyRelationshipMetadata EntityType를 반환하기 위한 것과 같은 쿼리에 있는 캐스트를 포함할 필요가 있습니다.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

OneToManyRelationshipMetadata로 엔터티가 반환되고 유형화되기 때문에, ReferencedEntity와 같은 속성에서 필터를 하여 쿼리를 구성해 다음 쿼리에서 볼 수 있는 거래처 엔터티와 같은 특정 엔터티에 대한 일대다 엔터티 관계만을 반환할 수 있습니다.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

쿼리는 필터된 다음의 쿼리와 기본적으로 동일한 결과를 하는데 그 이유는 거래처 엔터티의 EntityMetadataOneToManyRelationships 컬렉션-가치 탐색 속성에 포함되어 있기 때문입니다. 이전 쿼리와 차이점은 거래처 엔터티에 대한 MetadataId을 알 필요가 없다는 것입니다.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/OneToManyRelationships?$select=SchemaName

전역 OptionSets 쿼리하기

GlobalOptionSetDefinitions 엔터티 집합 경로를 사용하여 전역 옵션 집합에 대한 정보를 검색할 수 있지만 이 경로는 $filter 시스템 쿼리 옵션의 사용을 지원하지 않습니다. 따라서, 특정 전역 옵션 집합에 대한 MetadataId을 모르는 경우, 모두를 검색하는 수밖에 없습니다. 이를 사용하는 특성을 위해 GlobalOptionSet 단일-가치 탐색 속성 내에서 나온 전역 옵션 집합의 정의에 엑세스할 수 있습니다. 이것은 모든 Entity types that inherit from activitypointer을 이용할 수 있습니다.추가 정보:특성 검색

참고 항목

웹 API를 Dynamics 365 메타데이터와 함께 사용
이름 또는 MetadataId로 메타데이터 검색
Web API를 사용하여 엔터티 정의 만들기 및 업데이트
Web API를 사용하여 엔터티 관계 만들기 및 업데이트

Microsoft Dynamics 365

다음을 통해 공유

웹 API를 사용하는 메타데이터 쿼리

이 항목의 내용

EntityMetadata 엔터티 형식 쿼리

$필터 작업에 열거 형식 사용

$필터 작업에 복잡한 형식 사용

EntityMetadata 특성을 쿼리

필요한 수준으로 필터링

특성 검색

관계 메타데이터 쿼리하기

전역 OptionSets 쿼리하기

참고 항목

추가 리소스