Query Data using the Web API

適用於以下版本: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

一些說明: 最近一直使用web api 進行資料查詢，大多數情況下由於’‘時間緊，任務重’’，從文件上貼上下來，改下引數，能跑就行，管他是用腳跑還是用手在地上爬。所以就造成了技術知識沒有系統性，每次用的時候都要來查詢，很不方便。為了方便後人同時也為了提升自我，根據官方文件將幾種常用的方法解釋下並貼出示例程式碼以供理解學習。

​ 如果要檢索實體集的資料，使用GET請求。在檢索資料時，可以應用查詢選項來設定所需資料和返回的實體屬性的標準。

​ 本文包含以下內容

• 基本查詢示例(Basic query example)
• 限制被返回實體的數量(Limits on number of entities returned)
• 指定在一頁中返回實體記錄的數量(Specify the number of entities to return in a page)
• 應用系統查詢選項(Apply system query options)
• 請求特定屬性(Request specific properties)
• 過濾結果(Filter results)
• 排序結果(Order results)
• 使用引數別名和系統查詢選項(Use parameter aliases with system query options)
• 限制結果(Limit results)
• 檢索實體的的數量(Retrieve a count of entities)
• 包括格式化的值(Include formatted values)
• 檢索有關LookUp屬性的資料(Retrieve data about lookup properties)
• 根據單值導航屬性過濾記錄(Filter records based on single-valued navigation property)
• 通過展開導航屬性檢索相關實體(Retrieve related entities by expanding navigation properties)

---

基本查詢示例(Basic query example)

這個示例查詢帳戶(account)實體集，並使用$select和$top系統查詢選項返回前三個帳戶(account)記錄的name屬性

請求

GET [Organization URI]/api/data/v8.2/accounts?$select=name&$top=3 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": "[Organization URI]/api/data/v8.2/$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屬性將與結果一起返回。使用@odata.nextLink屬性值和(with)一個新的GET請求來返回下一頁資料。示例參照上文用法

指定在一頁中返回實體記錄的數量

在請求中設定odata.maxpagesize preference值的來確定返回的實體記錄的數量

不能設定odata.maxpagesize preference value 大於 5000.

下面的示例查詢客戶(account)實體集，並返回前三個帳戶(account)的name屬性。

請求

GET [Organization URI]/api/data/v8.2/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": "[Organization URI]/api/data/v8.2/$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": "[Organization URI]/api/data/v8.2/accounts?$select=name&$skiptoken=%
}

應用系統查詢選項

實體集附加到URL的每個系統查詢選項都是使用查詢字串語法新增的。第一個附加在?和後續查詢選項使用&分隔。如下面的示例所示，所有查詢選項都是區分大小寫的。

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

請求特定屬性

使用$select系統查詢選項來限制返回的屬性，如下例所示。

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue

這是一個效能最佳好的例子。如果屬性沒有使用$select指定，那麼將返回所有屬性。

If you request a money value, the _transactioncurrencyid_value lookup property will be returned. This property contains only the GUID value of the transaction currency so you could use this value to retrieve information about the currency using the transactioncurrency EntityType. Alternatively, by requesting annotations you can also get additional data in the same request. More information: Retrieve data about lookup properties

If you request a property that is part of a composite attribute for an address, you will get the composite property as well. For example, if your query requests the address1_line1 property for a contact, the address1_composite property will be returned as well(無論翻譯都會變味，還是貼原文意會吧Orz)

過濾結果

使用 $filter系統查詢選項設定將返回的實體。

標準過濾操作符

比較運算子(Comparison Operators)

操作符	描述	示例
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

邏輯運算子(Logical Operators)

操作符	描述	示例
and	與	$filter=revenue lt 100000 and revenue gt 2000
or	或	$filter=contains(name,’(sample)’) or contains(name,‘test’)
not	非	$filter=not contains(name,‘sample’)

分組操作符(Grouping Operators)

操作符	描述	示例
( )	優先順序分組	(contains(name,‘sample’) or contains(name,‘test’)) and revenue gt 5000

標準查詢方法

web API支援以下標準的OData字串查詢函式

方法	示例
contains	$filter=contains(name,’(sample)’)
endswith	$filter=endswith(name,‘Inc.’)
startswith	$filter=startswith(name,‘a’)

This is a sub-set of the 11.2.5.1.2 Built-in Query Functions. Date, Math, Type, Geo and other string functions aren’t supported in the web API.

微軟Dynamics 365 Web API查詢功能

Microsoft Dynamics 365提供了許多特殊的函式，可以接受引數，返回布林值，並且可以在查詢中用作篩選標準,下面是Between函式搜尋員工數量在5到2000之間的帳戶的示例。

GET [Organization URI]/api/data/v8.2/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

結果排序

使用$orderby系統查詢選項指定返回項的順序。使用asc或desc字尾分別指定升序或降序。如果沒有應用字尾，則預設為升序。下面的示例顯示如何檢索按收入(revenue)升序和名稱(name)降序排序的帳戶的名稱和收入屬性。

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

使用引數別名和系統查詢選項

以為$filter和$orderby系統查詢選項使用引數別名。引數別名允許在請求中多次使用相同的值。如果沒有給別名賦值，則假定該別名為空。

沒有使用別名引數

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne nul

使用了別名引數

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue,&$orderby=@p1 asc,@p2 desc&$filter=@p1 ne @p3&@p1=revenue&@p2=name

限制結果(Limit results)

可以使用$top系統查詢選項來限制返回結果的數量。下面的示例將只返回前三個帳戶實體。

GET [Organization URI]/api/data/v8.2/accounts?$select=name,revenue&$top=3

查詢實體記錄的個數

使用系統$count=true查詢選項來包含匹配篩選條件的實體記錄的總數，最多為5000。

count值並不表示系統中實體的總數。它受到可返回實體的最大數量的限制(最多5000)。

$count和$top不可以一起使用

請求

GET [Organization URI]/api/data/v8.2/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

包括格式化的值

當想接收屬性的格式化值後的結果時,在prefer對odata.include-annotations設定為OData.Community.Display.V1.FormattedValue

下面的示例查詢account實體集並返回第一條記錄，包括支援格式化值的屬性。

請求

GET [Organization URI]/api/data/v8.2/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": "[Organization URI]/api/data/v8.2/$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" } ]
}

檢索有關Lookup屬性的資料

如果查詢包含lookup屬性，則可以請求annotations，這些annotations將提供關於這些屬性中的資料的附加資訊。大多數情況下，通過了解單值導航屬性和相關實體中包含的資料，可以得到相同的資料。但是，如果屬性表示的lookup屬性可以引用多種型別的實體，則此資訊可以告訴你lookup屬性引用的實體型別。

對於這些屬性，還有兩種附加的註釋

註釋(Annotation)	描述
Microsoft.Dynamics.CRM.associatednavigationproperty	The name of the single-valued navigation property that includes the reference to the entity.
Microsoft.Dynamics.CRM.lookuplogicalname	The logical name of the entity referenced by the lookup

These properties also can include formatted values as described in Include formatted values.Just like formatted values, you can return the other annotations using the odata.include-annotations preference set to the specific type of annotation you want, or you can set the value to “*” and return all three.下面的示例顯示了檢索包含註釋的事件實體_customerid_value查詢屬性資訊的請求和響應。

請求

GET [Organization URI]/api/data/v8.2/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":"[Organization URI]/api/data/v8.2/$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"
   }
}

這次就跟新到這裡,下次有機會再跟新吧 困困 = = 參考官方文件連結

​ 2020年12月14日