Запит даних за допомогою API веб-служб порталів

Стаття
10/07/2023

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

вимоги

Версія веб-сайту має бути не нижче за 9.4.1.x або вище.
Увімкніть таблицю та поле для операцій API веб-служб. Додаткові відомості: Параметри сайту для API веб-служб
API веб-служб порталів отримує доступ до записів таблиць і стежить за дозволами таблиці, наданими користувачам за допомогою пов'язаних веб-ролей. Переконайтеся, що настроєно правильні дозволи для таблиці. Додаткові відомості: Створення веб-ролей

Нотатка

У разі посилання на таблиці Dataverse з використанням API веб-служб порталів необхідно скористатися EntitySetName, наприклад для доступу до таблиці бізнес-партнера, у синтаксисі коду використовуватиметься EntitySetName бізнес-партнерів.

Запит записів

У наведеному нижче прикладі запитуються записи бізнес-партнерів.

Операція	Метод	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, щоб повернути властивість імені для перших трьох бізнес-партнерів:

Операція	Метод	URI
Отримання перших трьох записів сутностей	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Приклад: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Отримайте бізнес-партнера за допомогою його ідентифікатора:

Операція	Метод	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-адреси для набору сутностей, додається за допомогою синтаксису для рядків запитів. Перший додається після [?], а наступні параметри запиту відокремлюються за допомогою [&]. У всіх параметрах запиту враховується регістр, як показано в цьому прикладі:

Метод	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, щоб обмежити повернені властивості, як показано в цьому прикладі:

Метод	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, перелічені в наведеній нижче таблиці.

Оператор	Опис	Приклад
Оператори порівняння
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	Логічне "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.')
починається з	$filter=startswith(name,'a')

Функції запиту Dataverse

API веб-служб підтримує функції запиту Dataverse для фільтрації результатів. Для отримання додаткових відомостей див. довідку з функцій запитів API веб-служб.

Упорядкування результатів

Укажіть порядок повернення елементів за допомогою системного параметра запиту $orderby. За допомогою суфікса asc або desc укажіть порядок за зростанням або спаданням відповідно. Якщо суфікс не застосовано, за замовчуванням використовується порядок за зростанням. У наведеному нижче прикладі показано отримання властивостей імені та прибутку бізнес-партнерів, упорядкованих за зростанням і за спаданням.

Метод	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)

Отримання кількості рядків

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

Метод	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, щоб отримати лише значення.

Метод	URI
GET	`[Portal URI/_api/accounts/$count` Приклад: `https://contoso.powerappsportals.com/_api/accounts/$count`

Приклад відповіді

3

Порівняння стовпців

У наведеному нижче прикладі показано, як порівнювати стовпці за допомогою API веб-служб.

Метод	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.

Метод	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.

Метод	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)"
        }
    }
]
}

Якщо розгорнути параметри навігації зі значенням колекції, щоб отримати пов’язані таблиці для наборів сутностей, за наявності даних повертається лише один рівень глибини. В іншому разі колекція поверне пустий масив.

Метод	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)`

У наведеному нижче прикладі показано, як розгортати пов’язані сутності для наборів сутностей за допомогою властивостей навігації як з одним значенням, так і зі значенням колекції. Ім’я зв’язку з таблицею потрібно буде вказати в синтаксисі коду.

Метод	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

Упорядкування результатів

Об’єднання та групування результатів

Отримання кількості рядків

Порівняння стовпців

Отримання записів пов’язаної таблиці за допомогою запиту

Підстановка пов'язаної властивості навігації

Отримання записів пов’язаної таблиці за допомогою розгортання властивостей навігації з одним значенням

Отримання записів пов’язаної таблиці за допомогою розгортання властивостей навігації зі значенням колекції

Отримання записів пов’язаної таблиці за допомогою розгортання властивостей навігації як з одним значенням, так і зі значенням колекції

Наступний крок

Див. також

Зворотний зв’язок

Зворотний зв’язок

Додаткові ресурси