웹 API를 사용하여 데이터 쿼리

아티클
10/31/2017

게시 날짜: 2017년 1월

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

엔터티 집합에 대한 데이터를 검색하는 경우 GET 요청을 사용합니다. 데이터를 검색할 때 쿼리 옵션을 적용하여 원하는 데이터에 대한 기준과 반환해야 하는 엔터티 속성을 설정할 수 있습니다.

이 항목의 내용

기본 쿼리 예제

반환된 엔터티 수에 대한 제한

페이지에 반환할 엔터티 수를 지정합니다.

시스템 쿼리 옵션 적용

특정 속성을 요청합니다.

필터 결과

주문 결과

시스템 쿼리 옵션이 있는 매개 변수 별칭 사용

결과 제한

엔터티 수 검색

형식이 지정된 값 포함

조회 속성에 대한 데이터 검색

단일 값 탐색 속성을 기준으로 레코드 필터링

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

기본 쿼리 예제

이 예제는 accounts 엔터티 집합을 쿼리하고 $select 및 $top 시스템 쿼리 옵션을 사용하여 처음 3개 계정에 대한 name 속성을 반환합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

반환된 엔터티 수에 대한 제한

더 작은 페이지 크기를 지정하지 않으면 각 요청에 대해 최대 5000 엔터티가 반환됩니다. 쿼리 필터 조건과 일치하는 추가 엔티티가 있는 경우 @odata.nextLink 속성이 결과와 함께 반환됩니다. 새 GET 요청과 함께 @odata.nextLink 속성의 값을 사용하여 다음 데이터 페이지를 반환합니다.

참고

모델 엔터티에 대한 쿼리는 제한 또는 페이징되지 않습니다.추가 정보:웹 API를 사용하는 메타데이터 쿼리

페이지에 반환할 엔터티 수를 지정합니다.

odata.maxpagesize 선호 설정 값을 사용하여 응답에 반환되는 엔터티 수를 요청합니다.

참고

5000보다 큰 odata.maxpagesize 선호 설정 값은 사용할 수 없습니다.

다음 예제는 accounts 엔터티 집합을 쿼리하고 처음 3개 계정에 대한 name 속성을 반환합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

응답

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

@odata.nextLink 속성의 값을 사용하여 다음 레코드 집합을 요청합니다. 추가 시스템 쿼리 옵션을 변경하거나 값에 추가하지 마십시오. 추가 페이지에 대한 모든 후속 요청의 경우 원래 요청에 사용되는 동일한 odata.maxpagesize 선호 설정 값을 사용해야 합니다. 또한 이전에 검색한 페이지를 반환할 수 있도록 반환된 결과 또는 @odata.nextLink 속성의 값을 캐시합니다.

참고

@odata.nextLink 속성의 값은 URI 인코딩됩니다. 보내기 전에 값을 URI 인코딩하는 경우 URL의 XML 쿠키 정보가 오류를 초래합니다.

시스템 쿼리 옵션 적용

엔터티 집합에 대해 URL에 추가하는 각 시스템 쿼리 옵션은 쿼리 문자열 구문을 사용하여 추가됩니다. 첫 번째는 [?] 다음에 추가되고 후속 쿼리 옵션은 [&]를 사용하여 구분됩니다. 모든 쿼리 옵션은 다음 예에서 볼 수 있듯이 대/소문자를 구분입니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

특정 속성을 요청합니다.

$select 시스템 쿼리 옵션을 사용하여 다음 예제에 표시된 대로 반환되는 속성을 제한합니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

중요

이는 성능 모범 사례입니다. 속성이 $select를 사용하여 지정되지 않는 경우 모든 속성이 반환됩니다.

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

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

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

필터 결과

$filter 시스템 쿼리 옵션을 사용하여 엔터티가 반환되는 조건을 설정합니다.

표준 필터 연산자

웹 API는 다음 표에 나열된 표준 OData 필터 연산자를 지원합니다.

연산자	설명	예제
비교 연산자
eq	같음	$filter=revenue eq 100000
ne	같지 않음	$filter=revenue ne 100000
gt	보다 큼	$filter=revenue gt 100000
ge	보다 크거나 같음	$filter=revenue ge 100000
lt	보다 작음	$filter=revenue lt 100000
le	보다 작거나 같음	$filter=revenue le 100000
논리 연산자
and	논리곱	$filter=revenue lt 100000 and revenue gt 2000
or	논리합	$filter=contains(name,'(sample)') or contains(name,'test')
not	논리 부정	$filter=not contains(name,'sample')
그룹화 연산자
( )	우선 순위 그룹	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

참고

이는 11.2.5.1.1 내장 필터 작업의 하위 집합입니다. 산술 연산자 및 비교 연산자는 웹 API에서 지원되지 않습니다.

표준 쿼리 함수

웹 API는 이러한 표준 OData 문자열 쿼리 함수를 지원합니다.

함수	예제
contains	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

참고

이는 11.2.5.1.2 내장 쿼리 함수의 하위 집합입니다.Date, Math, Type, Geo 및 다른 문자열 함수는 웹 API에서 지원되지 않습니다.

Microsoft Dynamics 365 웹 API 쿼리 함수

Microsoft Dynamics 365는 매개 변수를 받고 부울 값을 반환하는 많은 특수 함수를 제공하며 쿼리에서 필터 조건으로 사용할 수 있습니다. 이러한 함수 목록은 Web API Query Function Reference을 참조하십시오. 다음은 직원 수가 5와 2000명 사이인 계정을 검색하는 Between Function의 예입니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

추가 정보:함수를 사용하여 쿼리를 작성합니다..

주문 결과

$orderby 시스템 쿼리 옵션을 사용하여 항목이 반환되는 순서를 지정합니다.asc 또는 desc 접미사를 사용하여 각각 오름차순 또는 내림차순을 지정합니다. 기본값은 접미사를 적용하지 않은 경우 오름차순입니다. 다음 예제에서 매출액은 오름차순, 이름은 내림차순으로 정렬하는 계정의 이름과 매출액 속성을 검색하는 것을 보여줍니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

시스템 쿼리 옵션이 있는 매개 변수 별칭 사용

$filter 및 $orderby 시스템 쿼리 옵션에 대해 매개 변수 별칭을 사용할 수 있습니다. 매개 변수 별칭을 사용하면 같은 값을 요청에서 여러 번 사용할 수 있습니다. 별칭에 값이 할당되지 않은 경우 null로 간주됩니다.

매개 변수 별칭 없이 사용

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

매개 변수 별칭 사용

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=@p1 asc,@p2 desc&$filter=@p1 ne @p3&@p1=revenue&@p2=name

함수를 사용할 때는 매개 변수 별칭을 사용할 수도 있습니다.추가 정보:웹 API 기능 사용

결과 제한

$top 시스템 쿼리 옵션을 사용하여 반환되는 결과 수를 제한할 수 있습니다. 다음 예제에서는 처음 세 계정 엔터티만 반환합니다.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

참고

$top를 사용하여 결과를 제한하면 odata.maxpagesize 선호 설정이 적용되는 것이 방지됩니다.odata.maxpagesize 선호 설정 또는 $top를 사용할 수 있지만 둘을 동시에 사용할 수는 없습니다.odata.maxpagesize에 대한 자세한 내용은 페이지에 반환할 엔터티 수를 지정합니다.를 참조하십시오.

$count와 함께 $top를 사용해서는 안 됩니다.

엔터티 수 검색

값이 true인 $count 시스템 쿼리 옵션을 사용하여 최대 5000인 필터 조건과 일치하는 엔터티 수를 포함합니다.

참고

개수 값은 시스템의 총 엔터티 수를 나타내지 않습니다. 반환할 수 있는 엔터티의 최대 수로 제한됩니다.추가 정보:반환된 엔터티 수에 대한 제한

응답 @odata.count 속성은 odata.maxpagesize 선호 설정 제한에 관계 없이 필터 조건과 일치하는 엔터티 수를 포함합니다.

참고

$count와 함께 $top를 사용해서는 안 됩니다.

다음 예제에서는 이름에 “sample”이 포함되어 있지만 처음 세 계정만 반환하는 조건과 일치하는 10개의 계정이 있음을 보여줍니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

응답

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

개수를 제외한 데이터를 반환하지 않으려면 컬렉션에 $count을 적용하여 값만 가져올 수 있습니다.

요청

GET cc_WebAPI_ServiceURI/accounts/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

응답

HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

10

형식이 지정된 값 포함

결과가 있는 속성에 대해 서식이 지정된 값을 받으려면 값이 OData.Community.Display.V1.FormattedValue인 odata.include-annotations 선호 설정을 사용합니다. 응답은 다음과 같은 명명 규칙과 일치하는 속성이 있는 값을 포함합니다.

<propertyname>@OData.Community.Display.V1.FormattedValue

다음 예제에서는 계정 엔터티 집합을 쿼리하고 서식이 지정된 값을 지원하는 속성을 포함하여 첫 번째 레코드를 반환합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

응답

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

조회 속성에 대한 데이터 검색

쿼리에 조회 속성이 포함되는 경우 이러한 속성의 데이터에 대한 추가 정보를 제공하는 주석을 요청할 수 있습니다. 대부분의 경우 관련 엔터티에 포함된 단일 값 탐색 속성과 데이터 지식을 사용하여 동일한 데이터가 파생될 수 있습니다. 그러나 속성이 둘 이상의 엔터티 유형을 참조할 수 있는 조회 속성을 나타내는 경우 이 정보는 조회 속성으로 참조되는 엔터티 유형을 알려줄 수 있습니다.추가 정보:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

이 속성에 사용할 수 있는 두 가지 다른 유형의 주석이 있습니다.

Annotation	설명
Microsoft.Dynamics.CRM.associatednavigationproperty	엔터티에 대한 참조를 포함하는 단일 값 탐색 속성의 이름입니다.
Microsoft.Dynamics.CRM.lookuplogicalname	조회로 참조되는 엔터티의 논리 이름입니다.

이러한 속성은 형식이 지정된 값 포함에서 설명하는 대로 서식이 지정된 값을 포함할 수도 있습니다. 서식이 지정된 값과 마찬가지로 원하는 특정 유형의 주석에 설정된 odata.include-annotations 선호 설정을 사용하여 다른 주석을 반환하거나 값을 "*"로 설정하고 모두 3개를 반환할 수 있습니다. 다음 샘플은 주석이 포함된 incident 엔터티 _customerid_value 조회 속성에 대한 정보를 검색하는 요청과 응답을 보여줍니다.

요청

GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

응답

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

단일 값 탐색 속성을 기준으로 레코드 필터링

탐색 속성을 사용하여 현재 엔터티와 관련된 데이터에 액세스할 수 있습니다.단일 값 다 대 일 관계를 지원하고 다른 엔터티에 참조 설정이 가능한 조회 특정에 해당하는 탐색 속성추가 정보:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

엔터티 집합 레코드를 단일 값 탐색 속성 값에 따라 필터링할 수 있습니다. 예를 들어, 지정된 거래처에 대한 하위 거래처를 검색할 수 있습니다. 필터 레코드에 대해 단일 값 탐색 속성에서 참조하는 엔터티의 기본 특성 값만 사용할 수 있습니다. 예를 들면 다음과 같습니다.

지정된 연락처 ID에 대해 일치하는 모든 거래처 검색

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 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)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

지정된 거래처 ID에 대한 하위 거래처를 검색합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

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

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

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

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

참고

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

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

요청

GET cc_WebAPI_ServiceURI/accounts?$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))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

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

요청

GET cc_WebAPI_ServiceURI/accounts?$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)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

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

다음 예제에서는 상위 다섯 개 거래처 레코드에 할당된 작업을 검색합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=Account_Tasks($select%20=%20subject,%20scheduledstart) 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,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

단일 값 및 컬렉션 값 탐색 속성 모두를 확장하여 관련 엔터티 검색: 다음 예제에서는 단일 값 및 컬렉션 값 탐색 속성 모두를 이용하여 엔터티 집합에 대한 관련 엔터티를 확장하는 방법을 보여 줍니다. 앞에서 설명한 대로 컬렉션 값 탐색 속성을 호가장하여 엔터티 집합에 대해 관련 엔터티를 검색하면 관련 엔터티에 대한 @odata.nextLink 속성을 반환합니다. 새 GET 요청과 함께 @odata.nextLink 속성의 값을 사용하여 필요한 데이터를 반환하는 것이 좋습니다.

이 예제에서는 상위 세 개 거래처에 할당된 연락처 및 작업을 검색합니다.

요청

GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  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,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

참고 항목

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

Microsoft Dynamics 365

다음을 통해 공유

웹 API를 사용하여 데이터 쿼리

이 항목의 내용

기본 쿼리 예제

반환된 엔터티 수에 대한 제한

페이지에 반환할 엔터티 수를 지정합니다.

시스템 쿼리 옵션 적용

특정 속성을 요청합니다.

필터 결과

표준 필터 연산자

표준 쿼리 함수

Microsoft Dynamics 365 웹 API 쿼리 함수

주문 결과

시스템 쿼리 옵션이 있는 매개 변수 별칭 사용

결과 제한

엔터티 수 검색

형식이 지정된 값 포함

조회 속성에 대한 데이터 검색

단일 값 탐색 속성을 기준으로 레코드 필터링

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

참고 항목

추가 리소스