Запрос данных с помощью веб-API порталов

Статья
03/16/2023

Вы можете использовать доступные операции веб-API в порталах Power Pages. Операции веб-API состоят из HTTP-запросов и ответов. В этой статье представлены образцы операций чтения, методы, URI и образец JSON, который вы можете использовать в HTTP-запросе.

Предварительные условия

Ваша версия веб-сайта должна быть 9.4.1.x или выше.
Включить таблицу и поле для операций веб-API. Больше информации: Настройки сайта для веб-API
Веб-API порталов обращается к записям таблиц и следует разрешениям таблиц, предоставленным пользователям через связанные веб-роли. Убедитесь, что вы настроили правильные разрешения для таблиц. Дополнительные сведения: Создание веб-ролей

Заметка

При ссылке на таблицы Dataverse с помощью веб-API портала вам необходимо использовать EntitySetName, например, для доступа к таблице account синтаксис кода будет использовать EntitySetName из accounts.

Записи запросов

В следующем примере запрашиваются записи учетной записи:

Операция	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`

Получить учетную запись, используя идентификатор учетной записи:

Операция	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, позволяющий установить критерии, по которым будут возвращаться строки.

Стандартные операторы фильтра

Веб-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
or	Логическое ИЛИ	$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

Стандартные функции запросов

Веб-API поддерживает следующие стандартные функции строкового запроса OData:

Функция	Пример
содержит	$filter=contains(name,'(sample)')
заканчивается на	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Функции запросов Dataverse

Веб-API поддерживает функции запроса Dataverse для фильтрации результатов. Дополнительные сведения см. в разделе Справочник функций запросов веб-API.

Результаты упорядочения

Укажите порядок возврата товаров с помощью параметра системного запроса $ orderby. Используйте суффикс asc или desc, чтобы указать возрастающий или убывающий порядок соответственно. Если суффикс не применяется, по умолчанию используется возрастание. В следующем примере показано получение свойств name и revenue учетных записей, упорядоченных по возрастанию revenue и по убыванию name.

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)

Получить количество строк

Используйте параметр системного запроса $count со значением true, чтобы включить количество сущностей, соответствующих критериям фильтра, до 5000.

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

Сравнение столбцов

В следующем примере показано, как сравнить столбцы с помощью веб-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 в свойствах навигации, чтобы контролировать, какие данные из связанных сущностей возвращаются.

Вам нужно будет использовать свойство Microsoft.Dynamics.CRM.associatednavigationproperty в качестве атрибута поиска при использовании варианта запроса $expand.

Чтобы определить свойство Microsoft.Dynamics.CRM.associatednavigationproperty атрибута, вы можете сделать следующий запрос 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)`

Следующий шаг

Порталы записывают, обновляют и удаляют операции с помощью веб-API.

Поделиться через

Запрос данных с помощью веб-API порталов

Предварительные условия

Записи запросов

Применить параметры системного запроса

Запросить конкретные свойства

Фильтрация результатов

Стандартные операторы фильтра

Стандартные функции запросов

Функции запросов Dataverse

Результаты упорядочения

Агрегирование и группирование результатов

Получить количество строк

Сравнение столбцов

Поиск связанного свойства навигации

Следующий шаг

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

Запрос данных с помощью веб-API порталов

Предварительные условия

Записи запросов

Применить параметры системного запроса

Запросить конкретные свойства

Фильтрация результатов

Стандартные операторы фильтра

Стандартные функции запросов

Функции запросов Dataverse

Результаты упорядочения

Агрегирование и группирование результатов

Получить количество строк

Сравнение столбцов

Получение связанных записей таблицы с помощью запроса

Поиск связанного свойства навигации

Получение связанных записей таблицы путем раскрытия свойств навигации с одним значением

Получение связанных таблиц путем раскрытия свойств навигации со значением коллекции

Получение связанных таблиц путем раскрытия свойств навигации с одним значением и со значением коллекции

Следующий шаг

См. также

Обратная связь

Дополнительные ресурсы