通过

使用 OData 选择列

重要

查询数据时，限制返回的数据量以优化性能。 仅选择包含所需数据的列。

使用 Dataverse Web API 查询中的 OData 选择列时，请使用 $select查询选项 选择要返回的列。 在 OData 中，每个列都表示为 属性。 如果未包含 $select 查询选项，查询将返回所有属性，这可以降低性能。

以下示例请求 EntitySet 资源的第一行的name和revenue属性：

请求：

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

响应：

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

主键属性始终会被返回，因此无需将其包含在你的列表$select中。 在此示例中， accountid 是主键。

你可能会看到响应中包含的其他属性值。 在这种情况下，_transactioncurrencyid_value包含相关 Currency（TransactionCurrency）表/实体引用的查找属性，因为revenue是货币属性。

哪些属性可用？

可以在 $metadata服务文档中找到实体的所有可用属性。 有关详细信息，请参阅 Web API 属性。

小窍门

若要快速发现哪些属性可用，请使用 $top 查询选项发送请求，该值为 1 不使用 $select。 例如 GET [Organization URI]/api/data/v9.2/accounts?$top=1

描述 Web API Entity Type Reference Dataverse 附带的实体类型。

格式化值

服务器将格式化值生成为可在应用程序中使用的字符串值。 格式化的值包括：

  • 选择、选项、是/否、状态和状态原因列的本地化标签
  • 查找和所有者属性的主名称值
  • 具有货币符号的货币值
  • 用户时区中的格式化日期值

若要在结果中包含格式化值，请使用 Prefer 请求标头 发送 odata.include-annotations 首选项。

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

格式化值是可以请求的多个批注之一。 使用 Prefer: odata.include-annotations="*" 来包括所有批注。 有关详细信息，请参阅 请求批注。

使用遵循此约定的注释，带格式的值与记录一起返回。

<property name>@OData.Community.Display.V1.FormattedValue

例如：

请求：

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue,_primarycontactid_value,customertypecode,modifiedon
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

下表描述了为请求的属性返回的值和格式化值。

财产 价值 格式化值
name Litware, Inc. (sample) 没有
revenue 20000.0000 $20,000.00
_primarycontactid_value 70bf4d48-34cb-ed11-b596-0022481d68cd Susanna Stubberod (sample)
customertypecode 1 Competitor
modifiedon 2023-04-07T21:59:01Z 4/7/2023 2:59 PM
_transactioncurrencyid_value 228f42f8-e646-e111-8eb7-78e7d162ced1 US Dollar
accountid 78914942-34cb-ed11-b596-0022481d68cd 没有

响应：

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

查找属性数据

当 查找属性 表示 多表（或多态关系）时，需要请求特定的批注来确定哪个表包含相关数据。

例如，许多表包含用户或团队拥有的记录。 系统将所有权数据存储在名为 ownerid 的查找列中。 此列是 OData 中的单值导航属性。 可以使用 $expand 创建联接来获取此值，但不能使用 $select。 但是，您可以使用 $select 来获取相应的 _ownerid_value 查找属性。

在您将_ownerid_value查找属性包含在$select中时，它将返回一个 GUID 值。 此值不指示记录的所有者是用户还是团队。 需要请求批注才能获取此数据。

若要在结果中包含这些注解，请使用 Prefer 请求标头 并通过以下设置发送 odata.include-annotations 首选项：

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

小窍门

或者使用Prefer: odata.include-annotations="*"包括所有批注。 有关详细信息，请参阅 请求批注。

请求：

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

以下响应返回两个不同的帐户记录。 _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname 注释告诉您，第一个是由 team 拥有的，而第二个是由 systemuser 拥有的。

响应：

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}
  • <lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname 是相关表的逻辑名称。
  • <lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty 是相应单值导航属性的名称。 可以在另一个请求中使用 $expand 此值从相关记录获取更多数据。

列别名

对于 Web API，请使用 FetchXML 为列指定自定义别名。

目前，不能将 Dataverse Web API 与 OData 一起使用来指定列别名。 OData 4.0 不包含在 OData 4.01 中引入的$compute 系统查询选项，而该选项是提供此功能所必需的。

后续步骤

了解如何连接表。

联接表

  • Last updated on