미리 정의된 쿼리 검색 및 실행

아티클
10/31/2017

게시 날짜: 2017년 1월

적용 대상: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365을 통해 관리자가 모든 사용자가 사용할 수 있는 시스템 보기를 만들 수 있습니다. 개별 사용자가 응용 프로그램에서 다시 사용할 상세하게 찾기 쿼리를 저장할 수 있습니다. 둘 다 Web API를 사용하여 검색하고 실행할 수 있는 미리 정의된 쿼리를 나타냅니다.FetchXml을 사용하여 쿼리를 작성하고 이를 데이터 검색에 사용할 수도 있습니다.

이 항목의 내용

미리 정의된 쿼리

사용자 지정 FetchXML 사용

미리 정의된 쿼리

Microsoft Dynamics 365을 통해 여기에 나열된 대로 두 가지 유형의 쿼리를 정의, 저장 및 실행할 수 있습니다.

쿼리 유형	설명
저장 쿼리	엔터티에 대한 시스템 정의 보기 이 보기는 savedquery EntityType에 저장됩니다.추가 정보:엔터티 보기 사용자 지정
사용자 쿼리	상세하게 찾기는 하나의 엔터티에 대해 사용자가 저장한 내용을 검색합니다. 이 보기는 userquery EntityType에 저장됩니다.추가 정보:UserQuery(저장된 보기) 엔터티

이러한 유형의 엔터티는 모두에 대한 기록에는 반환할 데이터에 대한 FetchXML 정의가 포함됩니다. 각 엔터티 유형을 쿼리하여 기본 키 값을 검색할 수 있습니다. 기본 키 값으로 기본 키 값을 전달하여 쿼리를 실행할 수 있습니다. 예를 들어, 활성 계정 저장된 쿼리를 실행하려면 먼저 이와 같은 쿼리를 사용하는 기본 키가 있어야 합니다.

GET cc_WebAPI_ServiceURI/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

그런 다음 savedqueryid 값을 사용하고 이 값을 accounts 엔터티 집합에 대한 savedQuery 매개 변수 값으로 보낼 수 있습니다.

GET cc_WebAPI_ServiceURI/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

같은 방식으로 userqueryid를 얻고 이것을 저장된 쿼리에 상응하는 returnedtypecode에 맞는 엔터티 집합에 대한 userQuery 매개 변수 값으로 보냅니다.

GET cc_WebAPI_ServiceURI/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

쿼리를 적절한 유형의 컬렉션에 적용

이 외에, 단순히 주 엔터티 집합 컬렉션에 저장된 쿼리를 적용할 경우에는 저장된 쿼리 또는 사용자 쿼리를 사용하여 적절한 유형의 엔터티 컬렉션에 대한 동일한 필터링을 적용할 수도 있습니다. 예를 들어, 특정 엔터티와 관련된 엔터티에 대한 쿼리를 적용하려는 경우 동일한 패턴을 적용할 수 있습니다. 예를 들어, URL은 opportunity_parent_account 컬렉션 값 네비게이션 속성을 통해 특정 계정과 관련된 기회에 대한 기회 열기 쿼리를 적용합니다.

GET cc_WebAPI_ServiceURI/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

사용자 지정 FetchXML 사용

FetchXML은 집계 수행 기능을 제공하는 전용 쿼리 언어입니다. 저장된 쿼리와 savedquery EntityType 및 userquery EntityType에 저장된 사용자 쿼리에는 각각 쿼리를 정의하는 fetchxml 속성이 포함됩니다.IOrganizationService로 직접 FetchXML을 사용할 수 있습니다.RetrieveMultiple 메서드 또는 RetrieveMultipleRequest 방식추가 정보:FetchXML을 사용하여 쿼리 작성

Web API에서 결과를 반환할 FetchXML 매개 변수를 사용하는 쿼리의 루트 엔터티에 해당하는 엔터티 집합에 인코딩된 URL FetchXML을 쿼리로 보낼 수 있습니다. 예를 들어, 엔터티로 계정을 가진 다음 FetchXML을 보유할 수 있습니다.

<fetch mapping='logical'> 
   <entity name='account'>
      <attribute name='accountid'/> 
      <attribute name='name'/> 
</entity>
</fetch>

이 FetchXML의 URL 인코딩 값은 다음과 같습니다.

%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E

URL에 함수를 포함하는 대부분의 프로그래밍 언어는 문자열을 인코딩합니다. 예를 들어, JavaScript에서는 encodeURI 함수를 사용합니다. 모든 RESTful 웹 서비스로 보내는 요청은 모두 URL 인코딩해야 합니다. URL을 브라우저 주소 표시줄에 붙여 넣을 경우 주소를 자동으로 URL 인코딩해야 합니다. 다음 샘플은 계정에 대한 엔터티 집합 경로를 사용하여 이전에 표시된 FetchXML로 GET 요청을 보여 줍니다.

요청

GET cc_WebAPI_ServiceURI/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E 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#accounts(accountid,name)","value":[
    {
      "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)"
    },{
      "@odata.etag":"W/\"502172\"","accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1","name":"Litware, Inc. (sample)"
    },{
      "@odata.etag":"W/\"502174\"","accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1","name":"Adventure Works (sample)"
    },{
      "@odata.etag":"W/\"506705\"","accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1","name":"Fabrikam, Inc. (sample)"
    },{
      "@odata.etag":"W/\"506701\"","accountid":"91390c24-9c72-e511-80d4-00155d2a68d1","name":"Blue Yonder Airlines (sample)"
    },{
      "@odata.etag":"W/\"502180\"","accountid":"93390c24-9c72-e511-80d4-00155d2a68d1","name":"City Power & Light (sample)"
    },{
      "@odata.etag":"W/\"502182\"","accountid":"95390c24-9c72-e511-80d4-00155d2a68d1","name":"Contoso Pharmaceuticals (sample)"
    },{
      "@odata.etag":"W/\"506704\"","accountid":"97390c24-9c72-e511-80d4-00155d2a68d1","name":"Alpine Ski House (sample)"
    },{
      "@odata.etag":"W/\"502186\"","accountid":"99390c24-9c72-e511-80d4-00155d2a68d1","name":"A. Datum Corporation (sample)"
    },{
      "@odata.etag":"W/\"502188\"","accountid":"9b390c24-9c72-e511-80d4-00155d2a68d1","name":"Coho Winery (sample)"
    },{
      "@odata.etag":"W/\"504177\"","accountid":"0a3238d4-f973-e511-80d4-00155d2a68d1","name":"Litware, Inc."
    }
  ]
}

참고

링크 엔터티를 포함하는 FetchXML 쿼리의 응답 및 그 특성은 '.'는 '_x002e_'가 되고 '@'는 '_x0040_'가 되는 유니코드 특수 문자를 포함합니다.

FetchXML로 페이징

FetchXML로 fetch 요소의 page 및 count 특성을 설정하여 페이징을 적용할 수 있습니다. 예를 들어, 2에 대해 계정에 대한 쿼리와 엔터티 수 제한을 설정하고 첫 페이지만 반환하려면 다음 FetchXML을 사용합니다.

<fetch mapping="logical" page="1" count="2">
 <entity name="account">
  <attribute name="accountid" />
  <attribute name="name" />
  <attribute name="industrycode" />
 <order attribute="name" />
 </entity>
</fetch>

FetchXML을 통한 요청을 사용하여 쿠키 페이징을 요청하고 이를 쿼리에 포함시킬 수도 있습니다.추가 정보:FetchXML을 사용하여 대형 결과 집합 페이징

페이징 쿠키는 주석으로 요청해야 합니다.Microsoft.Dynamics.CRM.fetchxmlpagingcookie 및 @Microsoft.Dynamics.CRM.fetchxmlpagingcookie 속성 사용(또는 포함)이 결과와 함께 반환되도록 odata.include-annotations 기본 설정을 설정합니다.

참고 항목

Microsoft Dynamics 365

다음을 통해 공유

미리 정의된 쿼리 검색 및 실행

이 항목의 내용

미리 정의된 쿼리

쿼리를 적절한 유형의 컬렉션에 적용

사용자 지정 FetchXML 사용

FetchXML로 페이징

참고 항목

추가 리소스