使用 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 中定义操作。 举例来说，下面是 CSDL 中表示的 WinOpportunity Action的定义。

<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。

以下示例是 HTTP 请求和响应，对于 opportunityid 值为 b3828ac8-917a-e511-80d2-00155d2a68d2 的商机，可为其调用 WinOpportunity 操作。

  • 请求

    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 属性为集合时，该操作将绑定到实体集合。 举例来说，下面是 CSDL 中表示的 AddToQueue Action的定义：

 <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)，必须使用实体完整名称的 @odata.type 属性值（包括 Microsoft.Dynamics.CRM 命名空间）来明确声明对象的类型。 在本案例中为 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

实体

联系人​​

类别

操作​​

流程参数

客户

Type

必填

方向

NoteTitle

字符串

必填

输入

NoteText

字符串

必填

输入

NoteReference

EntityReference

必填

输出

步骤

客户

步骤类型

说明

创建注释

创建记录

标题 = {NoteTitle(Arguments)}

注释正文 = {NoteText(Arguments)}

关于 = {Contact{Contact}}

向注释返回参考

分派值

NoteReference 值 = {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.+<entity logical name>。

如上面的绑定操作部分中所示，AddToQueue Action 的 Target 参数是一个活动。 但是由于所有活动均继承自 activitypointer EntityType，所以必须在实体 JSON 中包含以下属性，以指定实体类型为一个字母："@odata.type": "Microsoft.Dynamics.CRM.letter"。

另外两个示例为 AddMembersTeam Action 和 RemoveMembersTeam Action，因为 Members 参数是其 ownerid 主键继承自 principal EntityType 的 systemuser EntityType 的集合。 如果传递以下 JSON 以在集合中表示单个系统用户，则该实体显然是系统用户而不是 team 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。 保留所有权利。 版权