Заявка за данни с помощта на портален уеб API

Статия
04/25/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. Повече информация: Настройки на сайта за Web 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`

Извличане на акаунт чрез използване на ID на акаунта:

Операция	Метод	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
Логически оператори
И	Логическо и	$filter=revenue lt 100000 and revenue gt 2000
or	Логическо или	$filter=contains(name,'(sample)') or contains(name,'test')
не	Логическо отрицание	$filter=not contains(name,'sample')
Оператори за групиране
( )	Групиране по приоритет	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Стандартни функции за заявки

Уеб API поддържа тези стандартни функции за заявки за низове на OData:

Функция	Пример
съдържа	$filter=contains(name,'(sample)')
endswith	$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, за да включите брой обекти, които отговарят на критериите за филтриране до 5000.

Метод	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 системна заявка в свойствата за навигация, за да контролирате какви данни от свързани обекти да се връщат.

Търсене на свързано навигационно свойство

Ще трябва да използвате Microsoft.Dynamics.CRM.associatednavigationproperty като атрибут за търсене при използване на $expand опция за заявка.

За да определите Microsoft.Dynamics.CRM.associatednavigationсвойството на даден атрибут, можете да направите следната 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 и пълно име.

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

Следваща стъпка

Операции за записване, актуализиране и изтриване на портали чрез Web API

Вижте също

Общ преглед на уеб API на портали
Учебник: Използване на портала Web API
Конфигуриране на разрешения за колони

Бележка

Можете ли да ни споделите повече за езиковите си предпочитания за документацията? Попълнете кратко проучване. (имайте предвид, че това проучване е на английски език)

Проучването ще отнеме около седем минути. Не се събират лични данни (декларация за поверителност).

Споделяне чрез

Заявка за данни с помощта на портален уеб API

Предварителни изисквания

Записи на заявки

Прилагане на опции за системни заявки

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

Филтриране на резултатите

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

Стандартни функции за заявки

Функции за заявки на Dataverse

Подреждане на резултати

Обобщаване и групиране на резултатите

Извличане на брой редове

Сравнение на колони

Извличане на свързани записи в таблици със заявка

Търсене на свързано навигационно свойство

Извличане на свързани записи в таблици чрез разширяване на свойствата за навигация с една стойност

Извличане на свързани таблици чрез разширяване на навигационните свойства на колекцията

Извличане на свързани таблици чрез разширяване на навигационни свойства с единична стойност и със стойност на колекция

Следваща стъпка

Вижте също

Допълнителни ресурси