使用 Dataverse Web API 建立工作訂單

本文提供了使用 Dataverse Web API 在Dynamics 365 Field Service中建立工作訂單的範例。 範例中使用 msdyn_workorder 實體。

必要條件

  • 一個包含 Web API 端點的 Dynamics 365 Field Service 環境（例如 https://yourorg.api.crm.dynamics.com/api/data/v9.2/）。
  • 一個使用 OAuth 2.0 進行認證的請求。 欲了解更多，請參閱 「使用 Web API 認證至 Dataverse」。
  • 必要查閱欄位的現有紀錄：
    • 服務帳戶（account 實體）
    • 工作訂單類型 （msdyn_workordertype 實體）
    • 價格表 （pricelevel 實體）

這很重要

以下範例中的 GUID 為虛構。 用你 Dynamics 365 環境的實際記錄 ID 來替換它們。

建立單一工作訂單

發送 POST 請求給 msdyn_workorders 實體集合以建立工作訂單。 在使用 Web API 建立表格列中了解更多。

HTTP 要求

POST [Organization URL]/api/data/v9.2/msdyn_workorders
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Authorization: Bearer <access_token>

{
  "msdyn_serviceaccount@odata.bind": "/accounts(e1a2b3c4-5678-9abc-def0-1234567890ab)",
  "msdyn_workordertype@odata.bind": "/msdyn_workordertypes(a1b2c3d4-5678-9abc-def0-1234567890cd)",
  "msdyn_pricelist@odata.bind": "/pricelevels(f1e2d3c4-5678-9abc-def0-1234567890ef)",
  "msdyn_systemstatus": 690970000,
  "msdyn_taxable": false,
  "msdyn_instructions": "Install new equipment"
}

HTTP 回應

成功的請求會返回 HTTP 204 No Content，其標頭 OData-EntityId 包含新工單記錄的 URL。

建立多個工作訂單

要在單一請求中建立多個工作訂單，請使用這個 CreateMultiple 動作。 這比單一 POST 請求或批次操作更具效能。 進一步了解：使用大量作業訊息。

HTTP 要求

POST [Organization URL]/api/data/v9.2/msdyn_workorders/Microsoft.Dynamics.CRM.CreateMultiple
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Authorization: Bearer <access_token>

{
  "Targets": [
    {
      "@odata.type": "Microsoft.Dynamics.CRM.msdyn_workorder",
      "msdyn_serviceaccount@odata.bind": "/accounts(e1a2b3c4-5678-9abc-def0-1234567890ab)",
      "msdyn_workordertype@odata.bind": "/msdyn_workordertypes(a1b2c3d4-5678-9abc-def0-1234567890cd)",
      "msdyn_pricelist@odata.bind": "/pricelevels(f1e2d3c4-5678-9abc-def0-1234567890ef)",
      "msdyn_systemstatus": 690970000,
      "msdyn_taxable": false,
      "msdyn_instructions": "Work order 1 - Install new equipment"
    },
    {
      "@odata.type": "Microsoft.Dynamics.CRM.msdyn_workorder",
      "msdyn_serviceaccount@odata.bind": "/accounts(e1a2b3c4-5678-9abc-def0-1234567890ab)",
      "msdyn_workordertype@odata.bind": "/msdyn_workordertypes(a1b2c3d4-5678-9abc-def0-1234567890cd)",
      "msdyn_pricelist@odata.bind": "/pricelevels(f1e2d3c4-5678-9abc-def0-1234567890ef)",
      "msdyn_systemstatus": 690970000,
      "msdyn_taxable": false,
      "msdyn_instructions": "Work order 2 - Preventive maintenance check"
    }
  ]
}

HTTP 回應

成功的請求會返回包含所建立紀錄 ID 的 HTTP 200 OK。

{
  "@odata.context": "[Organization URL]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.CreateMultipleResponse",
  "Ids": [
    "c1d2e3f4-5678-9abc-def0-111111111111",
    "c1d2e3f4-5678-9abc-def0-222222222222"
  ]
}

取回工作訂單

建立工作訂單後，請使用 GET 請求來取回它。

GET [Organization URL]/api/data/v9.2/msdyn_workorders(<work-order-id>)?$select=msdyn_name,msdyn_systemstatus,msdyn_address1,msdyn_city
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Authorization: Bearer <access_token>

回應

{
  "@odata.context": "[Organization URL]/api/data/v9.2/$metadata#msdyn_workorders(msdyn_name,msdyn_systemstatus,msdyn_address1,msdyn_city)/$entity",
  "@odata.etag": "W/\"7998533\"",
  "msdyn_workorderid": "d4e5f6a7-1234-5678-9abc-def012345678",
  "msdyn_name": "00051",
  "msdyn_systemstatus": 690970000,
  "msdyn_address1": "205 108th Ave NE",
  "msdyn_city": "Bellevue"
}

備註

欄位 msdyn_name 包含由現場服務自動分配的工作訂單編號。 msdyn_address1和 msdyn_city 的值是從服務帳戶記錄中填充的。

錯誤處理

建立工作訂單時常見的錯誤回應：

狀態代碼 原因 解析度
400 Bad Request 缺少必填欄位或欄位值無效。 確認所有必填欄位msdyn_serviceaccount（， msdyn_workordertype， msdyn_pricelistmsdyn_systemstatusmsdyn_taxable， ） 是否包含有效值。
400 Bad Request （代碼 0x80060888） 查詢欄位值是沒有實體集路徑的純 GUID。 例如，使用完整的 OData 實體參考格式， /accounts(guid) 而非僅使用 GUID。
401 Unauthorized 存取權杖遺失或過期。 更新或取得新的 OAuth 2.0 存取權杖。
403 Forbidden 特權不足。 確保使用者擁有現場 服務-調度員 或 現場服務-管理員 安全角色。
404 Not Found 參照的查詢記錄不存在。 確認服務帳戶、工作訂單類型及價格表的 GUID 是否參考現有紀錄。

相關內容

  • 上次更新時間：