使用 OData 查询数据

  • 15 分钟

OData 是用于查询 RESTful API 的协议。 本课程探讨了针对 Microsoft Dataverse 数据执行 CRUD 操作的几种方法。

创建行

要创建行，请使用 HTTP POST 方法。

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

检索行

要检索行，请使用 HTTP GET 方法。

以下示例检索 ID 为 00000000-0000-0000-0000-000000000001 的客户：

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

还有使用标准 OData 查询语法查询数据的其他方法。 有关本流程的详细信息，请参阅使用 Web API 检索表行。

更新行

根据您尝试实现的目标，可在用于更新行的两种方法之间选择一种：

  • 如果要对多个属性值执行更新，请使用 HTTP PATCH 方法。 如果您提供 ID 值作为请求的一部分，则 PATCH 方法将提供更新插入功能，当您在系统之间同步数据时，这是一项有益的功能。

  • 如果要更新单个属性值，请使用 HTTP PUT 方法。 不能将本方法与导航属性（例如查找）一起使用，因为这需要同时删除引用。

以下示例将更新一个客户表行：

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

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

如果您想要从要更新的表中检索数据，可以使用 return=representation 请求头。 如果您想要控制返回哪些属性，可以将 $select 查询添加到 PATCH URL。 在以下示例中，已添加标头，并且已修正 $select 以仅包括 name、creditonhold 和 address1 属性。

请求

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{"name":"Updated Sample Account"}

响应

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
    "@odata.etag": "W/"536537"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2023-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

以下代码是示例 PUT 请求，其中更新了给定行的客户名称：

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

删除行

要删除行，请使用 HTTP DELETE 方法。 该操作简单明了，您将提供要删除的表行的 URI，如以下请求中所示：

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

更多操作

Dataverse 提供了可通过 Web API 请求触发的许多其他预定义操作。 有关可用功能的完整清单，请参阅使用 Web API 执行操作。