Web API 函数和操作示例

 

发布日期: 2017年1月

适用于: Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

这组示例演示如何使用 Microsoft Dynamics 365 Web API 执行已绑定和未绑定函数和操作,包括自定义操作。 此示例作为一个单独的项目为以下语言实施:

本主题在更高的语言无关级别介绍示例的结构和内容。 请查看上面的链接示例主题以了解有关如何执行本主题中介绍的操作的,语言特定的实施详细信息。

演示

此示例分为以下主要部分,其中包含关联的概念主题中更详细地讨论的 Web API 函数和操作。

主题部分

关联的主题

示例数据

使用不带参数的未绑定函数

未绑定函数

WhoAmI Function

systemuser EntityType

使用带参数的未绑定函数

未绑定函数

GetTimeZoneCodeByLocalizedName Function

使用不带参数的绑定函数

绑定函数

CalculateTotalTimeIncident Function

使用带参数的未绑定操作

未绑定操作

WinOpportunity Action

opportunity EntityType

使用带参数的已绑定操作

绑定操作

AddToQueue Action

WhoAmI Function

systemuser EntityType

letter EntityType

使用带参数的已绑定自定义操作

使用自定义操作

绑定操作

contact EntityType

使用带参数的未绑定自定义操作

使用自定义操作

未绑定操作

account EntityType

处理自定义操作异常

使用自定义操作

未绑定操作

contact EntityType

以下章节包含执行的 Dynamics 365 Web API 操作的简短讨论,以及相应的 HTTP 消息和关联的控制台输出。

示例数据

若要确保此示例中的操作正常工作,首先需要在 Dynamics 365 服务器上创建示例数据。 除非用户选择不删除这些示例数据,否则将从服务器删除这些数据。 此示例中的数据按照下面的方法分别创建。

  • 创建客户(如 Fourth Coffee)并将其与有三个 30 分钟(总共 90 分钟)的任务的事件。 创建任务之后,将把这些任务标记为已完成。 操作将计算完成这三个任务所用时间总量。

    {
      title: "Sample Case",
      "customerid_account@odata.bind": accountUri,
      Incident_Tasks: [
       {
        subject: "Task 1",
        actualdurationminutes: 30
       },
       {
        subject: "Task 2",
        actualdurationminutes: 30
       },
       {
        subject: "Task 3",
        actualdurationminutes: 30
       }
      ]
     };
    
  • 创建一个客户并将其与商机关联。 此商机将在示例操作中标记为赢单。

    {
     name: "Sample Account for WebAPIFunctionsAndActions sample",
     opportunity_customer_accounts: [{
      name: "Opportunity to win"
     }]
    };
    
  • 创建信件活动。 将把信件添加到示例操作中当前用户的队列内。

    {
      description: "Example letter"
    }
    
  • 创建示例操作中的自定义操作 sample_AddNoteToContact 要使用的联系人。

    {
      firstname: "Jon",
      lastname: "Fogg"
    }
    

示例操作

本主题中的示例操作按照下面的方式排列。

  • 处理函数:这些操作显示用于接受或拒绝参数的已绑定和未绑定函数。

  • 处理操作:这些操作显示用于接受或拒绝参数的已绑定和未绑定操作。

  • 自定义操作:这些操作显示已绑定和未绑定操作以及如何处理自定义错误异常。

处理函数

Functions是没有副作用的操作。 可将函数绑定到实体实例或实体集。 查询函数无法绑定。 有关详细信息,请参阅使用 Web API 功能。 本节显示有关如何使用已绑定和未绑定函数和如何传递函数的示例。

使用不带参数的未绑定函数

可使用未绑定函数通过利用 WhoAmI Function 检索当前用户的全名。 此操作演示如何调用不接受参数的未绑定函数。 此操作返回当前用户的全名。

获取 WhoAmI Function 的请求和响应。

HTTP 请求

GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
   "UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
   "OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}

使用带参数的未绑定函数

使用未绑定函数检索时区代码。 此操作演示如何调用接受参数的未绑定函数。 此操作返回指定时区的当前时区代码。详细信息:将参数传递给函数

HTTP 请求

GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
   "TimeZoneCode":4
}

控制台输出

Unbound function: GetTimeZoneCodeByLocalizedName
    Function returned time zone Pacific Standard Time, with code '4'.

使用不带参数的绑定函数

使用绑定函数检索完成某个事件的所有任务所用时间总量。 此操作演示如何调用不接受参数的绑定函数。 此操作返回事件关闭其全部任务所用总分钟数。 此函数还使用我们为此示例程序创建的事件数据。详细信息:绑定函数

HTTP 请求

GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
   "TotalTime":90
}

控制台输出

Bound function: CalculateTotalTimeIncident
    Function returned 90 minutes - total duration of tasks associated with the incident.

处理操作

操作是允许副作用的操作。 操作为已绑定或未绑定。 有关详细信息,请参阅使用 Web API 操作。 本节显示有关如何使用已绑定和未绑定操作和如何传递函数的示例。 还显示如何使用自定义操作和如何处理这些自定义操作产生的异常。

使用带参数的未绑定操作

使用采用一组参数的未绑定操作。 此操作结束商机并通过调用 WinOpportunity Action 将其标记为赢单。opportunity EntityType 之前在程序中创建为示例数据。详细信息:未绑定操作

HTTP 请求

POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
   "Status":3,
   "OpportunityClose":{
      "subject":"Won Opportunity",
      "opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
   }
}

HTTP 响应

HTTP/1.1 204 No Content
OData-Version: 4.0

控制台输出

Unbound Action: WinOpportunity
    Opportunity won.

使用带参数的已绑定操作

使用采用任务参数的已绑定操作。 此操作还向当前用户的队列添加一个信件。 为此,需要使用 WhoAmI Functionsystemuser EntityType 获取当前用户的队列引用。 还需要 letter EntityType 的引用。 此信件之前在程序中创建为示例数据。 然后将调用绑定的 AddToQueue Action 以将信件添加到当前用户的队列。详细信息:绑定操作

HTTP 请求

POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110

{
   "Target":{
      "activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
      "@odata.type":"Microsoft.Dynamics.CRM.letter"
   }
}

HTTP 响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
   "QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}

控制台输出

Bound Action: AddToQueue
    QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802

处理自定义操作

如果您为解决方案定义自定义操作,则可使用 Dynamics 365 Web API 调用这些操作。 无论您的自定义操作中包含的操作是否有副作用,它们均可修改数据,因此被视为操作而不是函数。 无法创建自定义函数。详细信息:使用自定义操作

此示例随附了两个自定义操作。 它们都需要参数,但是一个已绑定,另一个未绑定。

  • sample_AddNoteToContact:采用两个参数的已绑定自定义操作。 一个是 NoteTitle,另一个是 NoteText。 此自定义操作向 contact EntityType 添加一个注释。 下面是此自定义操作的“信息”页面的屏幕截图。

    Custom Action - AddNoteToContact information

  • sample_CreateCustomer:根据正在创建的客户类型需要不同参数的未绑定自定义操作。 例如,如果 AccountType 为“客户”,则仅需要 AccountName 参数。 如果 AccountType 为“contact”,则需要 ContactFirstNameContactLastName 参数。 下面是此自定义操作的“信息”页面的屏幕截图。

    Custom Action - CreateCustomer information

使用带参数的已绑定自定义操作

此示例使用必需参数调用已绑定到联系人实体的 sample_AddNoteToContact 自定义操作。 此自定义操作向现有联系人添加一个注释。 此操作返回带 annotationid 属性的实体。 为了显示已添加了注释,将使用 annotationid 请求有关该注释的信息。

操作的请求和响应。

HTTP 请求

POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
   "NoteTitle":"The Title of the Note",
   "NoteText":"The text content of the note."
}

HTTP 响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}

批注的请求和响应。

HTTP 请求

GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP 响应

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
   "@odata.etag":"W/\"622978\"",
   "subject":"The Title of the Note",
   "notetext":"The text content of the note.",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
   "objectid_contact":{
      "@odata.etag":"W/\"622968\"",
      "fullname":"Jon Fogg",
      "contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
   }
}

控制台输出

Custom action: sample_AddNoteToContact
    A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.

使用带参数的未绑定自定义操作

此操作调用 sample_CreateCustomer 自定义操作创建“account”客户。 将传递 account 的 CustomerType 的必需参数。

HTTP 请求

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"account",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP 响应

HTTP/1.1 204 No Content
OData-Version: 4.0

处理自定义操作异常

此示例显示自定义操作可返回自定义错误消息。 可以按照处理标准异常的相同方法处理自定义异常。 为了获取 sample_CreateCustomer 自定义操作生成的自定义错误消息,此示例创建了一个“contact”客户。 但是,我们有意为此 CustomerType 参数传递了错误参数。 此操作然后补货异常并显示错误消息,再继续处理示例程序。

HTTP 请求

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"contact",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP 响应

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760

{
   "error":{
      "code":"",
      "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
      "innererror":{
         "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
         ...[truncated]
      }
   }
}

控制台输出

Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.

另请参阅

使用 Microsoft Dynamics 365 Web API
使用 Web API 功能
使用 Web API 操作
Web API 函数和操作示例 (C#)
Web API 函数和操作示例(客户端 JavaScript)

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权