共用方式為

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 Function 和 systemuser 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 是「連絡人」，則需要 ContactFirstName 和 ContactLastName 參數。 以下是此自訂動作的 [資訊] 頁面的螢幕擷取畫面。

    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 自訂動作來建立「客戶」客戶。 若 CustomerType 為 account，則會傳遞必要的參數。

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 自訂動作取得自訂錯誤訊息，此範例會建立「連絡人」客戶。 不過，我們刻意對此 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. 著作權所有，並保留一切權利。 著作權