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

Стаття
12/24/2024

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

вимоги

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

Нотатка

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

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

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

Операція	Метод	URI
Отримання записів таблиці	ОТРИМАТИ	`[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
Отримання перших трьох записів сутностей	ОТРИМАТИ	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Приклад: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

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

Операція	Метод	URI
Отримання певної властивості для запису	ОТРИМАТИ	`[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
ОТРИМАТИ	`[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
ОТРИМАТИ	`[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=Еквалайзер доходу 100000
ne	Не дорівнює	$filter=Дохід не 100000
gt	Більше	$filter=Дохід gt 100000
ge	Більше або дорівнює	$filter=revenue ge 100000
lt	Менше	$filter=Дохід lt 100000
le	Менше або дорівнює	$filter=Дохід ле 100000
Логічні оператори
та	Логічне "and"	$filter=Дохід lt 100000 та дохід GT 2000
or	Логічне "or"	$filter=містить(ім’я;’(зразок)’) або містить(назва,’тест’)
not	Логічне заперечення	$filter=не містить(ім’я, ’зразок’)
Оператори групування
( )	Групування за пріоритетом	(містить(назва, зразок) або містить, (назва, тест’)) і дохід gt 5000

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

API веб-служб підтримує ці стандартні функції запиту рядка OData:

Функція	Приклад
містить	$filter=містить(ім’я;’(зразок)’)
закінчується на	$filter=закінчується(ім’я, ’Inc.’)
починається з	$filter=починаєтьсяз(ім’я;’а’)

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

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

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

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

Метод	URI
ОТРИМАТИ	`[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 можна динамічно об’єднувати та групувати дані, як показано в наведених нижче прикладах.

Сценарії	Приклад
Список унікальних станів у запиті	облікові записи?$apply=groupby((код статусу))
Об’єднання суми приблизного значення	можливості?$apply=aggregate(оціночне значення з сумою як загальним)
Середній розмір угоди на підставі приблизного значення та стану	можливості?$apply=groupby((код статусу),aggregate(оціночне значення з середнім значенням як середнім)
Сума приблизного значення на основі стану	можливості?$apply=groupby((код статусу),aggregate(оціночне значення з сумою як загальним))
Загальний прибуток від потенційної угоди за іменем бізнес-партнера	можливості?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue з сумою як загальним))
Основні імена контактних осіб для бізнес-партнерів у "WA"	облікові записи?$apply=filter(address1_stateorprovince eq ’WA’)/groupby((primarycontactid/fullname))
Дата й час останнього створення запису	облікові записи?$apply=aggregate(створено з max як lastCreate)
Дата й час першого створення запису	облікові записи?$apply=aggregate(створено з min як firstCreate)

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

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

Метод	URI
ОТРИМАТИ	`[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
ОТРИМАТИ	`[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 у властивостях навігації, щоб керувати поверненням даних із пов’язаних сутностей.

Вам потрібно використовувати властивість Microsoft.Dynamics.CRM.associatednavigation як атрибут пошуку під час використання опції запиту$expand що ви зможете.

Щоб визначити 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
ОТРИМАТИ	`[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
ОТРИМАТИ	`[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)`

Запитуйте записи за допомогою FetchXml

Передайте запит FetchXml як рядкове значення з кодуванням URL до колекції набору сутностей за допомогою параметра запиту FetchXml.

Наприклад, щоб отримати дані з набору сутностей облікового запису, складіть запит FetchXml, встановивши параметр імені елемента сутності для облікового запису.

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

Рядок у кодуванні URL для попереднього запиту:

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Метод	URI
ОТРИМАТИ	`[Portal URI]/_api/accounts?fetchxml` Приклад: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

Зразок відповіді

{
  "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)"
      }
    }
  ]
}

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

Портали записують, оновлюють і видаляють операції за допомогою Web API

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

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

вимоги

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

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

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

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

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

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

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

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

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

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

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

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

Запитуйте записи за допомогою FetchXml

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

Див. також

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

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

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

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

вимоги

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Запитуйте записи за допомогою FetchXml

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

Див. також

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

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