使用 Web API 功能

發行項
10/31/2017

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

函數和動作代表您可以使用 Web API 執行的可重複使用作業。 Web API 中的功能有兩種類型：

Functions
使用 GET 要求搭配Web API Function Reference中列出的函數，執行沒有副作用的工作。這些函數通常會擷取資料。它們會傳回集合或複雜類型。每個這些函數在組織服務中都有對應的訊息。
查詢函數
使用列於 Web API Query Function Reference 的函數評估查詢撰寫中的屬性和值。每個這些函數都有對應 ConditionOperator 值。

本主題內容

傳遞參數給函數

將實體參照傳遞至函數

已繫結和未繫結的函數

使用函數撰寫查詢

傳遞參數給函數

對於這些需要參數的函數，最佳做法使用參數傳遞值。例如，當您使用 GetTimeZoneCodeByLocalizedName Function 時，必須包含 LocalizedStandardName 和 LocaleId 參數值。因此，您可以使用下列內嵌語法，如下所示。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

但是，使用包含內嵌語法的 DateTimeOffset 值時還尚待解決的問題，如下列文章所述：DateTimeOffset 做為查詢參數 #204 (英文)。

因此，但最佳做法是將值當做參數傳入，如下列程式碼範例所示。如果使用此最佳做法，可避免套用至 DateTimeOffset 的懸而未決問題。

GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

要多次使用參數值時，參數別名也能讓您重複使用參數值來減少 URL 的總長度。

將實體參照傳遞至函數

某些函數需要傳遞現有實體的參照。例如，下列函數的參數需要 crmbaseentity EntityType：

CalculateRollupField Function	IncrementKnowledgeArticleViewCount Function	InitializeFrom Function
IsValidStateTransition Function	RetrieveDuplicates Function	RetrieveLocLabels Function
RetrievePrincipalAccess Function	RetrieveRecordWall Function	ValidateRecurrenceRule Function

當您傳送參照至現有實體時，請對實體的 URI 使用 @odata.id 註解。例如，如果您使用 RetrievePrincipalAccess Function，您可以使用下列 URI 指定擷取存取給特定連絡人：

GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}

@odata.id 註解可以是完整 URI，但相對 URI 也可行。

已繫結和未繫結的函數

只有那些列於 Web API Function Reference的函數才能進行繫結。查詢函數永遠未繫結。

繫結函數

在 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl中，當 Function 元素表示繫結函數時，此元素會有值為 true 的 IsBound 屬性。函數定義的第一個 Parameter 元素代表函數繫結到的實體。參數的 Type 屬性為集合時，表示函數已繫結至實體集合。舉例來說，下列是 CalculateTotalTimeIncident Function和 CalculateTotalTimeIncidentResponse ComplexType 在 CSDL 中的定義。

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

這個繫結函數相當於組織服務使用的 CalculateTotalTimeIncidentRequest。在 Web API 中，此函數繫結至代表 CalculateTotalTimeIncidentRequest.IncidentId 屬性的incident EntityType。此函數不但沒有傳回 CalculateTotalTimeIncidentResponse，反而傳回 CalculateTotalTimeIncidentResponse ComplexType。當函數傳回複雜類型時，其定義會直接顯示在 CSDL 的函數定義上方。

若要叫用繫結函數，請將函數的完整名稱附加至 URL，並在函數名稱後面將任何具名參數包含在括號內。完整函數名稱包括命名空間 Microsoft.Dynamics.CRM。未繫結的函數不可使用完整名稱。

重要

必須使用 URI 叫用繫結函數，才能設定第一個參數值。您無法將其設定為具名參數值。

下列範例顯示一個使用繫結至事件實體的 CalculateTotalTimeIncident Function範例。

要求

GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() 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#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30
}

未繫結函數

WhoAmI Function沒有繫結至實體。其在 CSDL 中的定義沒有 IsBound 屬性。

<ComplexType Name="WhoAmIResponse">
  <Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
  <Property Name="UserId" Type="Edm.Guid" Nullable="false" />
  <Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>

此函數對應至 WhoAmIRequest，並傳回對應至組織服務所使用之 WhoAmIResponse 的 WhoAmIResponse ComplexType。此函數沒有任何參數。

叫用未繫結函數時，只需使用函數名稱，如下列範例所示。

要求

GET cc_WebAPI_ServiceURI/WhoAmI() 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#Microsoft.Dynamics.CRM.WhoAmIResponse",
 "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
 "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
 "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
}

使用函數撰寫查詢

有兩種可供函數用來控制查詢傳回資料的方式。某些功能允許控制其傳回的資料行或條件，而您會使用查詢函數來評估查詢中的條件。

可組合函數

Web API Function Reference中列出的某些功能將傳回實體集合。這些函數有一部分是「可組合」(Composable)，表示您可以將其他 $select 或 $filter 系統查詢選項加入會在結果中傳回資料行的控制項。這些函數在 CSDL 中具有 IsComposable 屬性。每個這些接受 ColumnSet 或 QueryBase 類型參數的函數，在組織服務中都有伴隨的訊息。OData 系統查詢選項提供相同的功能，因此這些函數沒有與其組織服務伴隨訊息相同的參數。下表顯示此版本中那些可組合函數的清單。

GetDefaultPriceLevel Function	RetrieveAllChildUsersSystemUser Function	RetrieveBusinessHierarchyBusinessUnit Function
RetrieveByGroupResource Function	RetrieveByResourceResourceGroup Function	RetrieveMembersBulkOperation Function
RetrieveParentGroupsResourceGroup Function	RetrieveSubGroupsResourceGroup Function	RetrieveUnpublishedMultiple Function
SearchByBodyKbArticle Function	SearchByKeywordsKbArticle Function	SearchByTitleKbArticle Function

查詢函數

Web API Query Function Reference 列出的函數預定是要用來撰寫查詢。這些函數可以依照類似標準查詢函數的用法來使用，但是有一些重要差異。

您必須使用函數的完整名稱，並且要包含參數的名稱。下列範例顯示如何使用 LastXHours Function 來傳回過去 12 小時內修改的所有客戶實體。

GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

另請參閱

Web API 函數和動作範例 (C#)
Web API 函數和動作範例 (用戶端 JavaScript)
使用 Web API 執行作業
 撰寫 HTTP 要求並處理錯誤
 使用 Web API 查詢資料
 使用 Web API，建立實體
 使用 Web API 擷取實體
 使用 Web API 更新和刪除實體
 使用 Web API 建立和取消實體的關聯
 使用 Web API 動作
 使用 Web API，執行批次作業
 使用 Web API 模擬其他使用者
 使用 Web API 執行條件運算

Microsoft Dynamics 365

共用方式為

使用 Web API 功能

本主題內容

傳遞參數給函數

將實體參照傳遞至函數

已繫結和未繫結的函數

繫結函數

未繫結函數

使用函數撰寫查詢

可組合函數

查詢函數

另請參閱

其他資源