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

Стаття
03/16/2023

Примітка

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

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

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

Метод	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 веб-служб порталів
Посібник: використання API веб-служб порталів
Налаштування дозволів для стовпців

Примітка

Розкажіть нам про свої уподобання щодо мови документації? Візьміть участь в короткому опитуванні. (зверніть увагу, що це опитування англійською мовою)

Проходження опитування займе близько семи хвилин. Персональні дані не збиратимуться (декларація про конфіденційність).

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

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

вимоги

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

Застосування системних параметрів запиту

Конкретні властивості запитів

Фільтрувати результати

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

Стандартні функції запиту

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

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

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

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

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

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

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

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

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

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

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

Див. також

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