共用方式為

使用 Web API 執行條件運算

  • 發行項

 

發行︰ 2017年1月

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

Microsoft Dynamics 365 為一組條件運算提供支援，依據標準 HTTP 資源版本管理機制 (稱為 ETag)。

本主題內容

ETag

If-Match 和 If-None-Match 標題

條件擷取

限制 upsert 作業

套用開放式並行存取

ETag

HTTP 通訊協定定義實體標記，或簡稱 ETag，用於識別資源的特定版本。 ETag 是不透明識別項，其實際值取決於實作。 ETag 值有兩種形式：強式和弱式驗證。 強式驗證是指特定 URL 識別的唯一資源在二進位層級上會一致，如果它對應的 ETag 值未改變。 弱式驗證只保證相同 ETag 值的資源表示對稱相等。

Dynamics 365 會為每個實體執行個體產生弱式驗證的 @odata.etag 屬性，此屬性會隨著每個擷取的實體記錄自動傳回。 如需詳細資訊，請參閱使用 Web API 擷取實體。

If-Match 和 If-None-Match 標題

使用 If-Match 和 If-None-Match 標題並含有 ETag 值，以檢查目前資原版本與上次擷取的版本是否相符、符合任何舊版，或不符合任何版本。 這些比較構成了條件運算支援的基礎。 Dynamics 365 提供 ETag 支援條件擷取、開放式並行存取及受限的 upsert 作業。

警告

用戶端程式碼不應提供任何意義給 ETag 的特定值，也不應提供給 ETag 之間超出等於或不等的任何明顯關聯。 例如，較新版本的資源的 ETag 值不保證大於舊版的 ETag 值。 此外，用來產生新 ETag 值的演算法可能在服務版本之間變更，且不另行通知。

條件擷取

Etag 可讓您最佳化記錄擷取，在您多次存取相同記錄時。 如果您先前擷取了記錄，您可以透過 If-None-Match 標頭傳遞 ETag 值，要求只在上次擷取後已變更的情況下才擷取資料。 如果資料已變更，要求會傳回 HTTP 狀態 200 (OK)，以及在要求本文中包含最新資料。 如果資料未變更，則會傳回 HTTP 狀態碼 304 (Not Modified)，表示實體未經過修改。 下列範例訊息配對會傳回客戶實體的資料，其中 accountid 等於 00000000-0000-0000-0000-000000000001，當資料自上一次擷取後未變更時。

  • 要求

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue   HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"

  • 回覆

    HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

限制 upsert 作業

upsert 透過建立實體正常執行，如果不存在；否則會更新現有實體。 不過，ETag 可用來進一步限制 upsert，防止建立或更新。

避免在 upsert 中建立

如果您要更新資料，而實體有可能已刻意刪除，您就不會想要重新建立實體。 為了避免此情況，新增 If-Match 標題至要求並使用 * 值。

  • 要求

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • 回覆
    如果找到實體，您將會收到具有 204 狀態 (No Content) 的正常回覆。 如果找不到實體，您將會收到具有 404 狀態 (Not Found) 的下列回覆。

    HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
 "error": {
  "code": "",
  "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
  "innererror": {
   "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
   "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
   "stacktrace": <stack trace removed for brevity>
  }
 }
}

避免在 upsert 中更新

若要插入資料，可能會發生系統中已有相同 id 值的記錄，而您不想要更新它。 為了避免此情況，新增 If-None-Match 標題至要求並使用 * 值。

  • 要求

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: "*"

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

  • 回覆
    如果找不到實體，您將會收到具有 204 狀態 (No Content) 的正常回覆。 當找到實體，您將會收到具有 412 狀態 (Precondition Failed) 的下列回覆。

    HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
  "error":{
   "code":"",
   "message":"A record with matching key values already exists.",
   "innererror":{
    "message":"Cannot insert duplicate key.",
    "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
    "stacktrace":<stack trace removed for brevity>
    }
  }
}

套用開放式並行存取

您可以使用開放式並行存取偵測實體自上次擷取後，是否已修改。 如果您想要更新或刪除的實體自您擷取後，已在伺服器上變更，您可能不想要完成更新或刪除作業。 藉由套用此處顯示的模式，您就可以偵測到此情況、擷取最新版本的實體，並套用任何必要的準則，以重新評估是否重試作業。

刪除時套用開放式並行存取

針對 accountid of00000000-0000-0000-0000-000000000001 的客戶，下列刪除要求會失敗，因為隨著 If-Match 標題傳送的 ETag 值與目前值不同。 若值相符，則預期為 204 (No Content) 狀態。

  • 要求

    DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • 回覆

    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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

更新時套用開放式並行存取

針對 accountid 為 00000000-0000-0000-0000-000000000001 的客戶，下列更新要求會失敗，因為隨著 If-Match 標題傳送的 ETag 值與目前值不同。 若值相符，則預期為 204 (No Content) 狀態。

  • 要求

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"name":"Updated Account Name"}

  • 回覆

    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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

另請參閱

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. 著作權所有，並保留一切權利。 著作權