通过

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 服务器分配的基本组织地址和记录的 ID 变化而变化。

示例数据

在执行主要代码部分之前，示例创建以下记录。

实体类型

客户端分配的属性

服务器分配的属性

account EntityType

名称： Contoso Ltd.
收入：5000000
电话：555-0000
说明：Parent company of Contoso Pharmaceuticals, etc.

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

条件 GET

程序的这一部分演示如何执行条件检索以优化网络带宽和服务器处理，同时仍然保持客户端记录的最新状态。详细信息：条件检索

  1. 只有当不匹配当前版本（由创建客户记录时返回的初始 ETag 值确定）时，尝试检索客户 Contoso Ltd.。 此情况由 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。 保留所有权利。 版权