使用 OData 端點的 OData 系統查詢選項

發行項
07/06/2017

發行︰ 2016年11月

適用於： Dynamics CRM 2015

您可以使用系統查詢選項微調您的查詢結果。下表列出 OData 通訊協定中定義的查詢字串選項，這些是在 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新的 OData 端點中實作。

選項	描述
$expand	指出相關記錄應在記錄或擷取的集合中擷取。
$filter	指定必須評估為 true，才能在集合中傳回記錄的運算式或函式。
$orderby	判斷要使用哪些值排列記錄的集合。
$select	指定要傳回的屬性子集。
$skip	設定要在擷取集合中的記錄之前略過的記錄數目。
$top	判斷要傳回的記錄數目上限。

$expand

指出相關記錄應在記錄或擷取的集合中擷取。

如果您要擷取相關記錄，請尋找定義此關聯的實體關聯名稱。您可能必須在應用程式中檢視實體關聯資訊，才能正確地識別組織資料服務的關聯或概念結構描述定義語言 (CSDL)。

例如，若要擷取與客戶相關聯的商機記錄，請使用 opportunity_customer_accounts 實體關聯。查詢 /AccountSet?$expand=opportunity_customer_accounts 會傳回商機記錄與客戶記錄。

如果您要限制傳回的欄，則也必須包含查詢中導覽屬性的名稱。例如，查詢 /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts 只會傳回客戶名稱和展開的商機記錄。

Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新不支援查詢多層關聯屬性。例如，這個目的在於擷取與客戶相關商機的負責人使用者資訊的查詢無效：/AccountSet?$expand=opportunity_customer_accounts/opportunity_owning_user。

根據預設，您最多可以定義展開六個關聯。這個目的在於同時展開商機和擁有客戶的系統使用者的查詢將會運作：/AccountSet?$select=Name,opportunity_customer_accounts,user_accounts&$expand=opportunity_customer_accounts,user_accounts。

注意

傳回的相關記錄數目會受限於與傳回的記錄數目相同的限制。如需詳細資訊，請參閱紀錄回傳限制數目。您可以增加展開的關聯數目，方法是變更 ServerSettingsMaxExpandCount 設定值。

其他資訊：OData：篩選系統查詢選項 ($expand)

$filter

指定必須評估為 true，才能在集合中傳回記錄的運算式或函式。

如果您要使用 next 連結擷取其他資料集，則不應變更 $filter 查詢選項值，因為這樣會導致無法預測的結果。

篩選系統查詢選項的 OData 規格描述用來建立運算式於篩選中評估的運算子。Microsoft Dynamics 365 會使用所有可用的邏輯運算子和函式子集，但是不支援使用算術運算子。篩選可以使用群組條件，以括號表示。比較時間值必須使用下列格式：datetime’<time value>’，例如 datetime'2010-07-15' 或 datetime'2010-07-15T16:19:54Z'。

下表列出 Microsoft Dynamics 365 支援的運算子。

運算子	描述	範例
eq	等於	/AccountSet?$filter=Address1_City eq 'Redmond'
ne	不等於	/AccountSet?$filter=Address1_City ne null
gt	大於	/AccountSet?$filter=CreditLimit/Value gt 1000
ge	大於或等於	/AccountSet?&$filter=CreditLimit/Value ge 1000
Lt	小於	/AccountSet?$filter=CreditLimit/Value lt 1000
le	小於或等於	/AccountSet?$filter=CreditLimit/Value le 1000
and	邏輯 AND	/AccountSet?$filter=CreditLimit/Value ge 1000 and Address1_StateOrProvince eq 'TX'
or	邏輯 OR	/AccountSet?$filter=AccountCategoryCode/Value eq 2 or AccountRatingCode/Value eq 1
not	邏輯否定	/AccountSet?$filter=(AccountCategoryCode/Value ne null) and not (AccountCategoryCode/Value eq 1)

您可以使用 $filter 查詢選項篩選出 EntityReference 屬性的值。例如，如果您有 SystemUser 記錄的 Id 值，就可以使用下列篩選擷取指派給使用者的所有客戶記錄的清單：

/AccountSet?$filter=OwnerId/Id eq (guid'" + SystemUserId + "')

下表列出 Microsoft Dynamics 365 支援的函式。

函數	範例
startswith	/AccountSet?$filter=startswith(Name, 'a')
substringof	/AccountSet?$filter=substringof('store',Name)
endswith	/AccountSet?$filter=endswith(Name, '(sample)')

其他資訊：OData：篩選系統查詢選項 ($filter)

$orderby

判斷要使用哪些值排列記錄的集合。根據預設，順序為遞增。使用 desc 可反向順序，使用 asc 則可明確設定預設值。

如果您要使用 next 連結擷取其他資料集，則不應變更 $orderby 查詢選項值，因為這樣會導致無法預測的結果。

注意

您最多可以使用 $orderby 選取 12 欄。

依複雜類型排列順序，例如 EntityReference 或 OptionSetValue 時，只應指定屬性名稱。例如，若要依據客戶的主要連絡人排序，請使用查詢 $orderby=PrimaryContactId。指定 $orderby=PrimaryContactId/Name 將會顯示「要求不正確 HTTP」錯誤 (HTTP 錯誤碼 400)。

下列範例將依照國家/地區遞增順序列出客戶記錄，以及依照城市遞減順序列出客戶記錄：

/AccountSet?$select=Address1_Country,Address1_City,Name&$orderby=Address1_Country,Address1_City desc&$filter=(Address1_Country ne null) and (Address1_City ne null)

其他資訊：OData：篩選系統查詢選項 ($orderby)

$select

指定要傳回的屬性子集，以及做為資料欄排序依據的順序。預設是傳回符合 $select=* 的所有欄。

如果您使用 $expand 包括相關資料，並使用 $select 限制傳回的欄，則您也必須在查詢中包含導覽屬性的名稱。例如，下列查詢 /AccountSet?$select=Name,opportunity_customer_accounts&$expand=opportunity_customer_accounts 只會傳回客戶名稱和展開的商機記錄。

注意

Internet Explorer 中的 POST 和 GET 要求有路徑長度上限 2048 個字元的限制。如果您要在 $select 選項的客戶實體中包含每一個屬性，那就很容易達到此限制。如需詳細資訊，請參閱 Microsoft KB 208427。

其他資訊：OData：篩選系統查詢選項 ($select)

$skip

設定要在擷取集合中的記錄之前略過的記錄數目。

如果您要使用 next 連結擷取其他資料集，則不應變更 $skip 查詢選項值，因為這樣會導致無法預測的結果。

其他資訊：OData：篩選系統查詢選項 ($skip)

$top

判斷要傳回的記錄數目上限。

如果您要使用 next 連結擷取其他資料集，則不應變更 $top 查詢選項值，因為這樣將導致無法預測的結果。

其他資訊：OData：篩選系統查詢選項 ($top)

不支援的系統查詢選項

Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新不支援使用下列系統查詢選項：

$inlinecount
$count
$format

另請參閱

使用 OData 端點查詢 Microsoft Dynamics CRM 2015 資料
 OData：URI 慣例