다음을 통해 공유

웹 API를 사용하여 엔터티 검색

  • 아티클

 

게시 날짜: 2017년 1월

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

GET 요청을 사용하여 고유 식별자를 통해 리소스로 지정된 엔터티에 대한 데이터를 검색합니다. 엔터티를 검색할 때 특정 속성을 요청하고, 탐색 속성을 확장하여 관련 엔터티에서 속성을 반환할 수도 있습니다.

참고

엔터티 메타데이터를 검색하는 방법에 대한 정보는 웹 API를 사용하는 메타데이터 쿼리를 참조하십시오.

이 항목의 내용

기본 검색 예제

특정 속성 검색

대체 키를 이용하여 검색

단일 속성 값 검색

탐색 속성 값 검색

탐색 속성을 확장하여 엔터티에 대한 관련 엔터티 검색

확장된 엔터티에 적용하는 옵션

엔터티 검색 이후 변경되었는지 여부를 감지합니다.

서식이 지정된 값 검색

기본 검색 예제

이 예제에서는 00000000-0000-0000-0000-000000000001과 동일한 기본 키 값을 사용하여 거래처 엔터티 인스턴스에 대한 데이터를 반환합니다.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

한 번에 둘 이상의 엔터티를 검색하려면 웹 API를 사용하여 데이터 쿼리 항목의 기본 쿼리 예제을 참조하십시오.

주의

위의 예제는 데이터 검색에 대한 수행 모범 사례에 반하는 거래처 정보에 대한 모든 속성을 반환합니다. 이 예제는 Dynamics 365의 엔터티 인스턴스에 대한 기본 검색 방법을 설명하기 위한 것입니다. 이 예제에서는 모든 속성이 반환되었기 때문에 요청에 대한 응답 정보는 포함하지 않았습니다.

올바른 수행을 위해, 항상 $select 시스템 쿼리 옵션을 사용하여 데이터 검색 중에 반환되는 속성을 제한해야 합니다. 이에 대한 자세한 내용은 다음의 특정 속성 검색 섹션을 참조하십시오.

특정 속성 검색

$select 시스템 쿼리 옵션을 사용하여 쉼표로 구분되는 속성 이름 목록을 포함하여 반환되는 속성을 제한합니다. 이는 중요한 수행 모범 사례입니다. 속성이 $select를 사용하여 지정되지 않는 경우 모든 속성이 반환됩니다.

다음 예제에서는 00000000-0000-0000-0000-000000000001과 동일한 기본 키 값을 갖는 거래처 엔터티에 대한 name 및 revenue 속성을 검색합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue 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#accounts(name,revenue)/$entity",
"@odata.etag": "W/\"502186\"",
"name": "A. Datum Corporation (sample)",
"revenue": 10000,
"accountid": "00000000-0000-0000-0000-000000000001",
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"
}

특정 유형의 속성을 요청할 때 자동으로 반환할 추가 읽기 전용 속성이 표시됩니다.

금액 값을 요청하는 경우는 _transactioncurrencyid_value 조회 속성이 반환됩니다. 이 속성은 거래 통화의 GUID 값만을 포함하기 때문에 transactioncurrency EntityType을 사용하여 통화에 대한 정보를 검색하기 위해 이 값을 사용할 수 있습니다. 또한 주석을 요청하여 같은 요청에의 추가 데이터를 얻을 수 있습니다.추가 정보:조회 속성에 대한 데이터 검색

주소의 복합 특성의 일부인 속성을 요청하는 경우 복합 속성 또한 얻을 수 있습니다. 예를 들어, 쿼리가 연락처에 대한 address1_line1 속성을 요청하는 경우, address1_composite 속성 또한 반환됩니다.추가 정보:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes

대체 키를 이용하여 검색

엔터티의 대체 키가 정의되어 있으면 대체 키를 사용하여 엔터티에 대한 고유 식별자 대신 엔터티를 검색할 수도 있습니다. 예를 들어, Contact 엔터티에 firstname 및 emailaddress1 속성을 모두 포함하는 대체 키가 있을 경우, 다음과 같이 해당 키에 대해 제공되는 데이터를 통한 쿼리를 사용하여 연락처를 검색할 수 있습니다.

GET cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

언제든지 검색, 업데이트 또는 삭제할 엔터티를 고유하게 식별해야 할 경우 해당 엔터티에 대해 구성된 대체 키를 사용할 수 있습니다. 기본적으로 엔터티에 대해 구성된 대체 키가 없습니다. 대체 키는 조직이 추가할 경우에만 사용할 수 있습니다.

단일 속성 값 검색

엔터티에 대한 단일 속성 값을 검색하려는 경우 엔터티에 대한 URI에 속성 이름을 첨부하여 해당 속성에 대한 값만 반환할 수 있습니다. 이는 응답에서 반환되어야 할 데이터가 적기 때문에 수행 모범 사례입니다.

이 예제에서는 거래처 엔터티에 대한 이름 속성 값만 반환합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name 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(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

탐색 속성 값 검색

개별 속성 값을 검색하는 방식과 동일한 방식으로 개별 엔터티를 참조하는 URI에 탐색 속성 이름을 첨부하여 탐색 속성 값(조회 필드)에 액세스할 수도 있습니다.

다음 예제에서는 primarycontactid 단일 값 탐색 속성을 사용하여 거래처의 기본 연락처 전체 이름을 반환합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname 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#contacts(fullname)/$entity",
"@odata.etag": "W/\"500128\"",
"fullname": "Rene Valdes (sample)",
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
}

컬렉션 값 탐색 속성의 경우, 관련 엔터티로 참조만 반환하거나 관련 엔터티 수만 반환하도록 요청하는 옵션이 있습니다.

다음 예제에서는 /$ref을 요청에 추가하여 특정 거래처와 관련된 업무에 대한 참조만 반환합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref 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#Collection($ref)",
"value": [
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
},
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)"
}
]
}

다음 예제에서는 /$count가 첨부된 Account_Tasks 컬렉션 값 탐색 속성을 사용하여 특정 거래처와 관련된 업무 수를 반환합니다.

  • 요청

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • 응답

    2

참고

반환되는 값에는 이것이 UTF-8 문서임을 나타내는 UTF-8 BOM(바이트 순서 표시) 문자()가 포함됩니다.

탐색 속성을 확장하여 엔터티에 대한 관련 엔터티 검색

$expand 시스템 쿼리 옵션을 사용하여 관련 엔터티 데이터가 반환되는 것을 제어합니다. 탐색 속성에는 두 가지 유형이 있습니다.

  • 단일 값 다 대 일 관계를 지원하고 다른 엔터티에 참조 설정이 가능한 조회 특정에 해당하는 탐색 속성

  • 컬렉션 값 일 대 다 또는 다 대 다 관계에 해당하는 탐색 속성

탐색 속성 이름만 포함시킬 경우, 관련 레코드에 대한 모든 속성을 받게 됩니다. 탐색 속성 이름 뒤 괄호 안의 $select 시스템 쿼리 옵션을 사용하여 관련 레코드에 대해 반환되는 속성을 제한할 수 있습니다. 단일 값과 값 컬렉션 탐색 속성에 모두 사용합니다.

참고

엔터티 집합에 대한 관련 엔터티를 검색하려면 탐색 속성을 확장하여 관련 엔터티 검색를 참조하십시오.

  • 단일 값 탐색 속성을 확장하여 엔터티 인스턴스에 대한 관련 엔터티 검색: 다음 예제는 모든 거래처 엔터티에 대한 연락처를 검색하는 방법을 보여 줍니다. 관련 연락처 레코드의 경우, contacid와 전체 이름만 검색합니다.

    • 요청

      GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid($select=contactid,fullname) 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(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"primarycontactid":{
"@odata.etag":"W/\"550626\"",
"contactid":"c59648c3-68f7-e511-80d3-00155db53318",
"fullname":"Nancy Anderson (sample)"
}
}

    엔터티 인스턴스에 대해 관련 엔터티를 반환하는 대신, $ref 옵션을 사용하여 단일 값 탐색 속성을 확장하여 관련 엔터티에 참조(링크)를 반환할 수도 있습니다. 다음 예제는 거래처 엔터티에 대한 연락처 레코드에 링크를 반환합니다.

    • 요청

      GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid/$ref 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(name,primarycontactid)/$entity",
"@odata.etag":"W/\"550616\"",
"name":"Adventure Works (sample)",
"accountid":"00000000-0000-0000-0000-000000000001",
"_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",
"primarycontactid":{
"@odata.id":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
}
}

    • 컬렉션 값 탐색 속성을 확장하여 엔터티 인스턴스에 대한 관련 엔터티 검색: 다음 예제는 거래처 레코드에 할당된 모든 업무를 검색하는 방법을 보여 줍니다.

      • 요청

        GET cc_WebAPI_ServiceURI/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
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(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
"@odata.etag":"W/\"514069\"","name":"Sample Child Account 1","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

      참고

      컬렉션 값 탐색 매개 변수를 확장하여 엔터티 집합에 대해 관련 엔터티를 검색하면 관련 엔터티에 대한 @odata.nextLink 속성을 대신 반환합니다. 새 GET 요청과 함께 @odata.nextLink 속성의 값을 사용하여 필요한 데이터를 반환하는 것이 좋습니다.추가 정보:탐색 속성을 확장하여 관련 엔터티 검색

  • 단일 값 및 컬렉션 값 탐색 속성 모두를 확장하여 엔터티 인스턴스에 대한 관련 엔터티 검색: 다음 예제에서는 단일 값 및 컬렉션 값 탐색 속성 모두를 이용하여 엔터티 인스턴스에 대한 관련 엔터티를 확장하는 방법을 보여 줍니다.

    • 요청

      GET cc_WebAPI_ServiceURI/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) 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#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity","@odata.etag":"W/\"514069\"","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid":{
"@odata.etag":"W/\"514074\"","createdon":"2016-04-06T00:29:04Z",
"name":"Adventure Works (sample)",
"accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
},"Account_Tasks":[
{
"@odata.etag":"W/\"514085\"",
"subject":"Sample Task 1",
"scheduledstart":"2016-04-11T15:00:00Z",
"activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514082\"",
"subject":"Sample Task 2",
"scheduledstart":"2016-04-13T15:00:00Z",
"activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
}
]
}

참고

관련 엔터티에 대한 URI 또는 관련 엔터티 수만 반환할 경우 /$ref 또는 /$count 경로 세그먼트를 사용할 수 없습니다.

확장된 엔터티에 적용하는 옵션

컬렉션 값 탐색 속성용으로 반환되는 엔터티에 대해 특정 시스템 쿼리 옵션을 적용할 수 있습니다. 컬렉션 값 탐색 속성 이름 뒤 괄호 안에 들어있는 세미콜론으로 구분된 시스템 쿼리 옵션 목록을 사용합니다.$select, $filter, $orderby, $top를 사용할 수 있습니다.

다음 예제에서는 "1"로 끝나는 subject로 거래처 관련 업무 엔터티 결과를 필터링합니다.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

다음 예제에서는 createdon 속성에 따라 관련 업무가 오름차순으로 반환되어야 한다고 지정합니다.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

다음 예제에서는 첫 번째 관련 업무만 반환합니다.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

참고

이것은 OData 버전 4.0 1부: 프로토콜 및 정오표 02의 "11.2.4.2.1 확장 옵션" 섹션에 설명된 시스템 쿼리 옵션의 하위 집합입니다.$skip, $count, $search$expand 및 $levels 옵션은 웹 API에 대해 지원되지 않습니다.

엔터티 검색 이후 변경되었는지 여부를 감지합니다.

성능 모범 사례로 필요한 데이터만 요청해야 합니다. 이전에 엔터티 레코드를 검색한 경우 이전에 검색한 레코드와 관련된 ETag를 사용하여 해당 레코드에 조건부 검색을 수행할 수 있습니다. 자세한 내용은 조건부 검색을 참조하십시오.

서식이 지정된 값 검색

개별 레코드 검색에 대한 서식이 지정된 값을 요청 엔터티 집합을 쿼리하는 경우와 동일한 방식으로 수행합니다.추가 정보:형식이 지정된 값 포함

참고 항목

웹 API 기본 작업 샘플(C#)
웹 API 기본 작업 샘플(클라이언트 쪽 JavaScript)
웹 API를 사용하여 작업 수행
HTTP 요청 및 처리 오류 작성
웹 API를 사용하여 데이터 쿼리
웹 API를 사용하여 엔터티 만들기
웹 API를 사용하여 엔터티 업데이트 및 삭제
웹 API를 사용하여 엔터티 연결 및 연결 해제
웹 API 기능 사용
웹 API 작업 사용
웹 API를 사용하여 일괄 작업 실행
웹 API를 사용하여 다른 사용자를 가장
웹 API를 사용하여 조건부 작업을 수행

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 저작권 정보