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

Статия
12/24/2024

Можете да използвате налични операции на уеб API в Power Pages= Операциите с уеб API се състоят от HTTP заявки и отговори. В тази статия са представени примерни операции за четене, методи, URI и примерен JSON, който можете да използвате в HTTP заявката.

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

Вашата версия на уеб сайта трябва да бъде 9.4.1.x или по-висока.
Активирайте таблица и поле за операции на уеб API. Повече информация: Настройки на сайта за Web 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`

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

Операция	Метод	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=Приходи ne 100000
gt	Е по-голямо от	$filter=Приходи gt 100000
ge	По-голямо или равно на	$filter=Приходи ge 100000
lt	Е по-малко от	$filter=приходи lt 100000
le	По-малко или равно на	$filter=Приходи le 100000
Логически оператори
И	Логическо и	$filter=Приходи LT 100000 и приходи GT 2000
or	Логическо или	$filter=contains(name;'(sample)') или contains(name;'test')
не	Логическо отрицание	$filter=not contains(name;'sample')
Групиране на оператори
( )	Групиране по приоритет	(съдържа(име;'извадка') или съдържа(име;'тест')) и приходи GT 5000

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

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

Функция	Пример
съдържа	$filter=съдържа(име;'(извадка)')
endswith	$filter=endswith(име,'Inc.')
започва със	$filter=startswith(име;'a')

Функции за заявки на 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((statuscode))
Обща сума на прогнозната стойност	възможности?$apply=aggregate(прогнозна стойност със сума като общо)
Среден размер на сделката въз основа на прогнозната стойност и статус	възможности?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Сума от прогнозната стойност въз основа на състоянието	възможности?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Общи приходи от възможности по име на акаунт	възможности?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Имена на основни контакти за акаунти в „WA“	акаунти?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/пълно име))
Дата и час на последния създаден запис	акаунти?$apply=aggregate(createdon с max като lastCreate)
Дата и час на първия създаден запис	акаунти?$apply=aggregate(createdon с min като firstCreate)

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

Използвайте опцията $count за системна заявка със стойност true за включване на брой обекти, които отговарят на критериите за филтър до 5000.

Метод	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.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
ПОЛУЧАВАМ	`[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)"
      }
    }
  ]
}

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

Порталите записват, актуализират и изтриват операции с помощта на уеб API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заявете записи с помощта на FetchXml

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

Вижте също

Обратна връзка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заявете записи с помощта на FetchXml

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

Вижте също

Обратна връзка

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