共用方式為

Web API 條件式作業範例

  • 發行項

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

此範例群組示範如何執行作業，這些作業會條件式地依據 Dynamics 365 伺服器上包含的實體記錄版本，和/或目前用戶端維護的實體記錄版本。 如需詳細資訊，請參閱使用 Web API 執行條件運算。 此範例做為個別專案實作，提供給下列語言：

Web API 條件式作業範例 (C#)

Web API 條件式作業範例 (用戶端 JavaScript)

Dynamics 365 Web API 遵循 OData v4.0 通訊協定的慣例，其使用 ETags 實作資源版本控制。 Web API 條件式作業依據此版本管理機制。

本主題以較高階且不分語言的層級說明範例的結構與內容。 其中詳述 HTTP 要求和回覆，以及相關聯的程式輸出 (如適用)。 檢閱上方連結的範例主題，以取得語言特定的實作和相關的詳細資料，了解如何執行本主題中所述的作業。

示範

此範例分為三個主要區段，如下表所列。 每個區段均包含一組相關的 Web API 作業，將在主題使用 Web API 執行條件運算的相關概念區段中詳細說明。

程式碼區段

相關的概念主題

條件式 GET

條件擷取

刪除和更新時的開放式並行存取

套用開放式並行存取

控制 upsert 作業

限制 upsert 作業

以下各節將簡單討論執行的 Dynamics 365 Web API 作業，以及對應的 HTTP 訊息和相關主控台輸出，與每一種語言實作相同。 簡單來說，已省略較不相關的 HTTP 標頭。 記錄的 URI 會隨基底組織地址與您的 Dynamics 365 伺服器指派記錄的識別碼而不同。

範例資料

範例會先建立下列記錄，再執行主要程式碼區段。

實體類型

用戶端指派的屬性

伺服器指派的屬性

account EntityType

名稱： Contoso Ltd.
收入：5000000
電話：555-0000
描述：Parent company of Contoso Pharmaceuticals, etc.

識別碼：14e151db-9b4f-e611-80e0-00155da84c08
初始 Etag：W/"628448"

條件式 GET

此區段程式示範如何執行條件式擷取，以最佳化網路頻寬和伺服器處理，同時將用戶端上的記錄保持最新狀態。其他資訊：條件擷取

  1. 嘗試擷取客戶 Contoso Ltd.，只有在不符合目前版本時，由客戶記錄建立時傳回的初始 ETag 值識別。 此條件以 If-None-Match 標頭表示。

    HTTP 請求

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 304 Not Modified

    主控台輸出

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    回覆值 304 Not Modified，表示目前記錄是最新的，因此伺服器不會在回覆本文中傳回所需的記錄。

  2. 利用修改主要電話號碼屬性更新客戶。

    HTTP 請求

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    HTTP 回覆

    HTTP/1.1 204 No Content

    主控台輸出

    Account telephone number updated.

  3. 再次嘗試相同的條件式 GET 作業，並再次使用原始 ETag 值。 這次作業會傳回要求的資料，因為伺服器上的版本與要求中識別的版本不同 (且更新)。 就像在所有記錄擷取中，回覆會包括識別最新版本的 ETag 標頭。

    HTTP 請求

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    主控台輸出

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

刪除和更新時的開放式並行存取

此區段程式示範如何執行條件式刪除和更新作業。 這類作業最常用於實作開放式並行存取方法來記錄多使用者環境中的處理。其他資訊：套用開放式並行存取

  1. 只有在符合原始版本 (ETag 值) 時才可嘗試刪除原始客戶。 此條件以 If-Match 標頭表示。 此作業失敗，因為客戶記錄已在前一個區段中更新，因此其版本已在伺服器上更新。

    HTTP 請求

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . .
    }
}

    主控台輸出

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. 只有在符合原始 ETag 值時才可嘗試更新客戶。 同樣地，此條件會以 If-Match 標頭表示，且作業會因相同原因而失敗。

    HTTP 請求

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    HTTP 回覆

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . . 
  }
}

    主控台輸出

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. 再次嘗試更新，但改用從前一個區段中擷取的記錄取得的目前 ETag 值。

    HTTP 請求

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    HTTP 回覆

    HTTP/1.1 204 No Content

    主控台輸出

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. 確認更新成功，藉由擷取和輸出目前客戶狀態。 這會使用基本 GET 要求。

    HTTP 請求

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    主控台輸出

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

控制 upsert 作業

此區段程式示範如何執行條件式 PATCH 作業，限制 upsert 作業執行僅更新或僅插入作業。其他資訊：限制 upsert 作業

  1. 嘗試插入，但不更新此客戶的主要電話號碼和收入屬性。 值為 * 的 If-None-Match 標頭代表此 upsert 條件。 此作業失敗，因為此客戶記錄仍存在伺服器上 (除非有其他使用者或程序同時將它刪除)。

    HTTP 請求

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    HTTP 回覆

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    主控台輸出

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. 嘗試執行相同的更新作業，但不建立。 若要完成此操作，會使用條件式 If-Match 標頭且值為 *。 此作業成功，因為記錄存在伺服器上。

    HTTP 請求

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    HTTP 回覆

    HTTP/1.1 204 No Content

    主控台輸出

    Account updated using If-Match '*'

  3. 擷取並輸出目前客戶狀態，透過基本 GET 要求。 請注意，傳回的 ETag 值已變更，以反映新的更新客戶記錄版本。

    HTTP 請求

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    主控台輸出

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. 使用基本 DELETE 刪除客戶。

    HTTP 請求

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP 回覆

    HTTP/1.1 204 No Content

    主控台輸出

    Account was deleted.

  5. 如同步驟 2，嘗試更新客戶 (如存在)。 同樣地，此條件是以 If-Match 標頭表示，其值為 *。 此作業失敗，因為此記錄已刪除。 不過，如果此 If-Match 標頭不存在，則產生的基本 upsert 作業應該會成功建立新記錄。

    HTTP 請求

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    HTTP 回覆

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    主控台輸出

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

不需要清除範例資料，因為客戶記錄已在步驟 4 中刪除。

另請參閱

使用 Microsoft Dynamics 365 Web API
使用 Web API 執行條件運算
Web API 條件式作業範例 (C#)
Web API 條件式作業範例 (用戶端 JavaScript)

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權