通过

使用门户 Web API 查询数据

  • 项目

您可以在 Power Pages 中使用可用的 Web API 操作。 Web API 操作包含 HTTP 请求和响应。 本文提供了您可以在 HTTP 请求中使用的示例读取操作、方法、URI 和示例 JSON。

先决条件

  • 您的网站版本必须为 9.4.1.x 或更高版本。

  • 为 Web API 操作启用表和字段。 详细信息：Web API 的站点设置

  • 门户 Web API 访问表记录，并遵循通过关联的 Web 角色授予用户的表权限。 请确保配置正确的表权限。 详细信息：创建 Web 角色

备注

使用门户 Web API 引用 Dataverse 表时，需要使用 EntitySetName，例如，访问客户表，代码语法将使用客户的 EntitySetName。

查询记录

以下示例查询客户记录：

操作 Method URI
检索表记录 GET [Portal URI]/_api/accounts

示例：
https://contoso.powerappsportals.com/_api/accounts

示例响应

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

使用 $select 和 $top 系统查询选项返回前三个客户的 name 属性：

操作 Method URI
检索前三个实体记录 GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

使用客户 ID 检索客户：

操作 Method URI
检索记录的特定属性 GET [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

示例：
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

示例响应

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

应用系统查询选项

您追加到实体集 URL 的每个系统查询选项都是使用查询字符串的语法添加的。 第一个追加在 [?] 之后，以下查询选项使用 [&] 分隔。 所有查询选项都区分大小写，如以下示例所示：

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

请求特定属性

使用 $select 系统查询选项限制返回的属性，如下例所示：

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

重要提示

这是一个性能最佳实践。 如果未指定属性并且您已将 Webapi/<table name>/fields 站点设置值配置为 *，将使用 $select 返回所有属性。 如果未指定任何属性，将返回错误。

筛选结果

使用 $filter 系统查询选项设置返回行的条件。

标准筛选器运算符

Web API 支持下表中列出的标准 OData 筛选器运算符：

Operator 说明 示例
比较运算符
eq 等于 $filter=revenue eq 100000
ne 不等于 $filter=revenue ne 100000
gt 大于 $filter=revenue gt 100000
ge 大于或等于 $filter=revenue ge 100000
lt 小于 $filter=revenue lt 100000
le 小于或等于 $filter=revenue le 100000
逻辑运算符
and 逻辑和 $filter=revenue lt 100000 and revenue gt 2000
或者 逻辑或 $filter=contains(name,'(sample)') or contains(name,'test')
not 逻辑非 $filter=not contains(name,'sample')
分组运算符
( ) 优先分组 (contains(name,'sample') or contains(name,'test')) and revenue gt 5000

标准查询函数

Web API 支持以下标准 OData 字符串查询函数：

函数 示例
包含 $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

Dataverse 查询函数

Web API 支持使用 Dataverse 查询函数来筛选结果。 有关详细信息，请参阅 Web API 查询函数参考。

对结果进行排序

使用 $orderby 系统查询选项指定返回项目的顺序。 使用 asc 或 desc 后缀分别指定升序或降序。 如果未使用后缀，默认值为升序。 以下示例显示检索按收入升序和姓名降序排列的客户的 name 和 revenue 属性。

Method URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

聚合和分组结果

使用 $apply，您可以动态聚合和分组数据，如以下示例所示：

方案 示例
查询中唯一状态的列表 accounts?$apply=groupby((statuscode))
聚合估计值总和 opportunities?$apply=aggregate(estimatedvalue with sum as total)
基于估计值和状态的交易平均大小 opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
基于状态的估计值总和 opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
按客户名称划分的商机总收入 opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
“WA”中客户的主要联系人姓名 accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
上次创建记录的日期和时间 accounts?$apply=aggregate(createdon with max as lastCreate)
首次创建记录的日期和时间 accounts?$apply=aggregate(createdon with min as firstCreate)

检索行数

使用值为 true 的 $count 系统查询选项来包含与最高 5,000 筛选条件匹配的实体数。

Method URI
GET [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

示例响应

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

如果您不想返回计数以外的任何数据，可以将 $count 应用于任何集合来仅获取此值。

Method URI
GET [Portal URI/_api/accounts/$count

示例：
https://contoso.powerappsportals.com/_api/accounts/$count

示例响应

3

列比较

下面的示例演示如何使用 Web API 比较列：

Method URI
GET [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

示例：
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

使用导航属性中的 $expand 系统查询选项控制返回来自相关实体的哪些数据。

查找关联的导航属性

使用 $expand 查询选项时，您将需要使用 Microsoft.Dynamics.CRM.associatednavigationproperty 作为查找属性。

若要确定属性的 Microsoft.Dynamics.CRM.associatednavigationproperty，可以使用以下命名约定对列进行以下 http GET 请求：_name_value。

在以下示例中，我们可以在请求中设置名称格式来指定列名称 primarycontactid，从而确定客户表的主要联系人列的关联导航属性：_primarycontactid_value。

Method URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

示例
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

示例响应

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

从响应中看到，关联导航属性是 primarycontactid。 根据表的创建方式，关联的导航属性可以是查找列的逻辑名称或架构名称。

有关详细信息，请参阅检索有关查找属性的数据。

下面的示例演示如何检索所有客户记录的联系人。 对于相关的联系人记录，我们仅检索 contactid 和 fullname。

Method URI
GET [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

示例：
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

示例响应

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

如果您扩展集合值导航参数来检索实体集的相关表，如果有数据，将仅返回一个深度级别。 否则，集合将返回一个空数组。

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

示例：
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

以下示例演示了如何使用单值导航属性和集合值导航属性扩展实体集的相关实体。 您将需要在代码语法中指定表关系名称。

Method URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

示例：
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

下一步

使用 Web API 的门户写入、更新和删除操作

另请参见