使用 Web API 動作
發行︰ 2017年1月
適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online
動作和函式代表您可以使用 Web API 執行的可重複使用作業。 使用 POST 要求搭配 Web API Action Reference中列出的動作，執行沒有副作用的工作。 您也可以定義自訂動作，這樣就可以使用它們。
本主題內容
未繫結動作
繫結動作
使用自訂動作
指定實體參數類型
未繫結動作
動作是在 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl中定義。 舉例來說，下列是 WinOpportunity Action在 CSDL 中代表的定義。
<Action Name="WinOpportunity">
<Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
<Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>
WinOpportunity 動作使用組織服務對應 WinOpportunityRequest。 使用此動作將商機的狀態設定為「成交」，並建立 opportunityclose EntityType 記錄事件。 此動作不包括傳回值。 如果成功，作業完成。
OpportunityClose 參數需要 opportunityclose 實體的 JSON 表示才能在作業中建立。 此實體必須與發行 opportunityid 單一值導覽屬性的商機關聯。 在 JSON 中，這是使用 @odata.bind 註解設定，如在建立時關聯實體中所述。
Status 參數必須在結束時設定為 opportunity 的狀態。 您可以在 opportunity EntityTypestatuscode 屬性中找到它的預設值。 [成交] 選項的值為 3。 您可能需要釐清，只有一個代表 [成交] 的狀態原因選項時，為什麼要設定此值？ 原因是，因為您可以定義自訂狀態選項代表一次成交，例如 [大成交] 或 [小成交]，因此，值可能會與該情況中的 3 不同。
下列範例是在 opportunityid 值為 b3828ac8-917a-e511-80d2-00155d2a68d2 的情況下呼叫商機的 WinOpportunity 動作時的 HTTP 要求和回覆。
要求
POST cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1 Accept: application/json Content-Type: application/json; charset=utf-8 OData-MaxVersion: 4.0 OData-Version: 4.0 { "Status": 3, "OpportunityClose": { "subject": "Won Opportunity", "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)" } }回覆
HTTP/1.1 204 No Content OData-Version: 4.0
繫結動作
在 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl中，當 Action 元素表示繫結動作時，此元素會有值為 true 的 IsBound 屬性。 動作內定義的第一個 Parameter 元素代表作業繫結的實體。 參數的 Type 屬性為集合時，表示作業已繫結至實體集合。 舉例來說，下列是 AddToQueue Action在 CSDL 中代表的定義：
<ComplexType Name="AddToQueueResponse">
<Property Name="QueueItemId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Action Name="AddToQueue" IsBound="true">
<Parameter Name="entity" Type="mscrm.queue" Nullable="false" />
<Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false" />
<Parameter Name="SourceQueue" Type="mscrm.queue" />
<Parameter Name="QueueItemProperties" Type="mscrm.queueitem" />
<ReturnType Type="mscrm.AddToQueueResponse" Nullable="false" />
</Action>
這個繫結動作相當於組織服務使用的 AddToQueueRequest。 在 Web API 中，此動作繫結至代表 AddToQueueRequest.DestinationQueueId 屬性的queue EntityType。 此動作會收到數個額外的參數，並傳回對應組織服務所傳回 AddToQueueResponse 的 AddToQueueResponse ComplexType。 當動作傳回複雜類型時，複雜類型的定義會直接顯示在 CSDL 中動作的正上方。
必須使用 URI 叫用繫結動作，才能設定第一個參數值。 您無法將其設定為具名參數值。
當叫用繫結函數時，您必須包含函數的完整名稱，包括 Microsoft.Dynamics.CRM 命名空間。 如果未包括完整名稱，則會出現下列錯誤：Status Code:400 Request message has unresolved parameters。
下列範例顯示使用 AddToQueue Action 新增字母至佇列。 因為 Target 參數類型並非特定 (mscrm.crmbaseentity)，因此您必須使用實體的完整名稱 (包括 Microsoft.Dynamics.CRM 命名空間) 的 @odata.type 屬性值明確宣告物件類型。 在此案例中，Microsoft.Dynamics.CRM.letter。其他資訊：指定實體參數類型
要求
POST cc_WebAPI_ServiceURI/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1 Accept: application/json Content-Type: application/json; charset=utf-8 OData-MaxVersion: 4.0 OData-Version: 4.0 { "Target": { "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1", "@odata.type": "Microsoft.Dynamics.CRM.letter" } }回覆
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.AddToQueueResponse", "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1" }
使用自訂動作
如果您定義組織或解決方案的自訂動作，這些也會包括在 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl中。 如需在應用程式中使用自訂工具建立動作的詳細資訊，請參閱 TechNet 主題動作。 如需建立和使用自訂動作的詳細資訊，請參閱建立自己的動作。
不論您自訂動作中包含的作業是否有副作用，都可能會修改資料，因此會視為動作而不是函數。 沒有任何方式可建立自訂函數。
自訂動作範例：新增附註至連絡人
假設您要建立自訂動作將新附註新增至特定連絡人。 您可以使用下列屬性來建立繫結至連絡人實體的自訂動作。
UI 標籤 |
值 |
|---|---|
程序名稱 |
AddNoteToContact |
唯一名稱 |
new_AddNoteToContact |
實體 |
連絡人 |
類別 |
動作 |
程序引數
名稱 |
類型 |
需要 |
方向 |
|---|---|---|---|
NoteTitle |
字串 |
需要 |
輸入 |
NoteText |
字串 |
需要 |
輸入 |
NoteReference |
EntityReference |
需要 |
輸出 |
步驟
名稱 |
步驟類型 |
描述 |
|---|---|---|
建立附註 |
建立記錄 |
標題 = {NoteTitle(Arguments)} 附註本文 = {NoteText(Arguments)} 有關於 = {Contact{Contact}} |
傳回附註的參考 |
指派值 |
NoteReference 值 = {Note(Create the note (Note))} |
在發行並啟用自訂動作之後，當您下載 CSDL 時，會發線已定義這個新動作。
<Action Name="new_AddNoteToContact" IsBound="true">
<Parameter Name="entity" Type="mscrm.contact" Nullable="false" />
<Parameter Name="NoteTitle" Type="Edm.String" Nullable="false" Unicode="false" />
<Parameter Name="NoteText" Type="Edm.String" Nullable="false" Unicode="false" />
<ReturnType Type="mscrm.annotation" Nullable="false" />
</Action>
下列 HTTP 要求和回覆顯示如何呼叫自訂動作，以及成功時所傳回的回覆。
要求
POST cc_WebAPI_ServiceURI/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1 Accept: application/json Content-Type: application/json; charset=utf-8 OData-MaxVersion: 4.0 OData-Version: 4.0 { "NoteTitle": "New Note Title", "NoteText": "This is the text of the note" }回覆
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "cc_WebAPI_ServiceURI/$metadata#annotations/$entity", "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2" }
指定實體參數類型
當動作需要實體做為參數，且實體類型為模稜兩可時，您必須使用 @odata.type 屬性指定實體的類型。 這個屬性的值是實體的完整名稱，後面接著此模式：
Microsoft.Dynamics.CRM.+<實體邏輯名稱>。
如上面 繫結動作 一節中所示，AddToQueue Action 的 Target 參數是活動。 但是，由於所有活動都繼承自 activitypointer EntityType，因此您必須包含下列屬性在實體 JSON 中，以指定實體的類型為信件："@odata.type": "Microsoft.Dynamics.CRM.letter"。
另外兩個範例為 AddMembersTeam Action 和 RemoveMembersTeam Action，因為 Members 參數是 systemuser EntityType 的集合，它的 ownerid 主索引鍵繼承自 principal EntityType。 如果您傳遞下列 JSON 來代表集合中的單一 systemuser，很明顯該實體就是 systemuser，不是 team EntityType，它也是繼承自主體 entitytype。
{
"Members": [{
"@odata.type": "Microsoft.Dynamics.CRM.systemuser",
"ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
}]
}
如果您在此情況下未指定實體的類型，可能會收到下列錯誤："EdmEntityObject passed should have the key property value set."。
另請參閱
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
© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權