Запрос данных с помощью веб-API порталов
Примечание
Действует с 12 октября 2022 г, в качестве порталов для Power Apps используется Power Pages. Дополнительная информация: Microsoft Power Pages теперь доступен для всех (блог)
Скоро мы мигрируем и объединим документацию порталов Power Apps с документацией Power Pages.
Вы можете использовать доступные операции веб-API в порталах. Операции веб-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 порталов Учебник. Использование веб-API порталов Настройка разрешений столбцов
Примечание
Каковы ваши предпочтения в отношении языка документации? Пройдите краткий опрос (обратите внимание, что этот опрос представлен на английском языке).
Опрос займет около семи минут. Личные данные не собираются (заявление о конфиденциальности).
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по