Tietojen kysely portaalien verkko-ohjelmointirajapinnan avulla

Artikkeli
03/16/2023

Huomautus

Power Apps -portaaleja kutsutaan 12. lokakuuta 2022 alkaen nimellä Power Pages. Lisätietoja: Microsoft Power Pages on nyt yleisesti saatavilla (blogi)
Siirrämme ja yhdistämme Power Apps -portaalien dokumentaation pian Power Pagesin dokumentaatioon.

Voit käyttää käytettävissä olevia verkko-ohjelmointirajapinnan toimintoja portaaleissa. Verkko-ohjelmointirajapinnan toiminnot koostuvat HTTP-pyynnöistä ja -vastauksista. Tässä artikkelissa on esimerkki lukutoiminnoista, -menetelmistä, URI:sta ja malli-JSON:ista, jota voit käyttää HTTP-pyynnössä.

Edellytykset

Portaaliversion on oltava vähintään 9.4.1.x.
Ota taulukko ja kenttä käyttöön verkko-ohjelmointirajapinnan toiminnoissa. Lisätietoja: Verkko-ohjelmointirajapinnan sivustoasetukset
Portaalien Web API käyttää taulukon tietueita ja noudattaa taulukkoon liittyviä käyttöoikeuksia, jotka on annettu käyttäjille liittyvien WWW-roolien kautta. Varmista, että määrität oikeat taulukko-oikeudet. Lisätietoja: Verkkoroolien luominen

Huomautus

Kun viittaat Dataverse-taulukoihin käyttämällä portaalien verkkorajapintaa, käytä esimerkiksi EntitySetName-nimeä tilin taulukon käyttämiseen, koodisyntaksi käyttää tilien EntitySetName-nimeä tilit.

Kyselytietueet

Seuraava esimerkki tekee kyselyjä tilitietueista:

Toiminto	Method	URI
Nouda taulukkotietueet	HAE	`[Portal URI]/_api/accounts` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts`

Mallivastaus

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

Palauta kolmen ensimmäisen tilin nimiominaisuus $select- ja $top-järjestelmäkyselyasetuksilla:

Toiminto	Method	URI
Kolmen ensimmäisen entiteettitietueen noutaminen	HAE	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Nouda tili tilitunnuksen avulla:

Toiminto	Method	URI
Tietueen tietyn ominaisuuden noutaminen	HAE	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Mallivastaus

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

Järjestelmäkyselyasetusten käyttäminen

Kaikki entiteettijoukon URL-osoitteeseen liitetyt järjestelmäkyselyasetukset lisätään kyselymerkkijonojen syntaksin avulla. Ensimmäinen liitetään [?]-kohdan jälkeen, ja seuraavat kyselyasetukset erotetaan toisistaan [&]-merkillä. Kaikissa kyselyasetuksissa isot ja pienet kirjaimet tulkitaan eri merkeiksi seuraavan esimerkin mukaisesti:

Method	URI
HAE	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

Pyynnön tarkat ominaisuudet

Käyttämällä $select -järjestelmäkyselyä voidaan rajoittaa palautettuja ominaisuuksia seuraavan esimerkin mukaisesti:

Method	URI
HAE	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Tärkeä

Tämä on suorituskyvyn paras käytäntö. Jos ominaisuuksia ei ole määritetty ja olet määrittänyt Webapi/<table name>/fields-sivustoasetuksen arvoksi *, kaikki ominaisuudet palautetaan toiminnolla $select. Jos ominaisuuksia ei ole määritetty, palautetaan virhe.

Suodata tulokset

Käyttämällä $filter -järjestelmäkyselyä voidaan määrittää ehdot, joille rivit palautetaan.

Vakiosuodattimen operaattorit

Web-ohjelmointirajapinta tukee seuraavassa taulukossa lueteltuja OData-suodatinoperaattoreita:

Operator	Kuvaus	Esimerkiksi
Vertailuoperaattorit
eq	Sama kuin	$filter=revenue eq 100000
ne	Eri kuin	$filter=revenue ne 100000
gt	Suurempi kuin	$filter=revenue gt 100000
ge	Suurempi tai yhtä suuri kuin	$filter=revenue ge 100000
lt	Pienempi kuin	$filter=revenue lt 100000
le	Pienempi tai yhtä suuri kuin	$filter=revenue le 100000
Loogiset operaattorit
and	Looginen ja	$filter=revenue lt 100000 and revenue gt 2000
or	Looginen tai	$filter=contains(name,'(sample)') or contains(name,'test')
not	Looginen negaatio	$filter=not contains(name,'sample')
Operaattoreiden ryhmittely
( )	Tärkeysjärjestyksen ryhmittely	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Tavalliset kyselyfunktiot

Web-ohjelmointirajapinta tukee seuraavia OData-merkkijonokyselyfunktioita:

Funktio	Esimerkiksi
sisältää	$filter=contains(name,'(sample)')
päättyy	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Dataverse -kyselyfunktiot

Verkko-ohjelmointirajapinta Dataversen kyselyfunktioita tulosten suodattamista varten. Lisätietoja: Verkko-ohjelmistorajapinnan kyselyfunktion viite.

Tilauksen tulokset

Määritä nimikkeiden palautusjärjestys $orderby -järjestelmäkyselyn avulla. Käyttämällä jälkiliitettä asc tai desc voidaan määrittää nouseva tai laskeva järjestys. Oletusarvo on nouseva, jos jälkiliitettä ei käytetä. Seuraavassa esimerkissä noudetaan nousevan tuoton ja laskevan nimen mukaan tilattujen tilien nimi ja tuotto-ominaisuudet.

Method	URI
HAE	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

Tulosten koostaminen ja ryhmittely

$apply -muuttujan avulla voit koostaa ja ryhmitellä tietoja dynaamisesti seuraavien esimerkkien mukaisesti:

Skenaariot	Esimerkiksi
Kyselyn yksilöllisten tilojen luettelo	accounts?$apply=groupby((statuscode))
Arvioidun arvon kokonaissumma	opportunities?$apply=aggregate(estimatedvalue with sum as total)
Kaupan keskimääräinen koko arvioidun arvon ja tilan perusteella	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Tilan perusteella arvioidun arvon summa	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Mahdollisuuden kokonaistuotto asiakkaan nimen mukaan	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
WA-tilien ensisijaiset yhteyshenkilöiden nimet	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Viimeisen luodun tietueen päivämäärä ja aika	accounts?$apply=aggregate(createdon with max as lastCreate)
Ensimmäisen luodun tietueen päivämäärä ja aika	accounts?$apply=aggregate(createdon with min as firstCreate)

Rivien määrän noutaminen

Käyttämällä $count -järjestelmäkyselyasetusta, jonka arvo on tosi, voidaan sisällyttää suodatinehtoja vastaava määrä entiteettejä, kuitenkin enintään 5 000.

Method	URI
HAE	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true`

Mallivastaus

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

Jos et halua palauttaa mitään tietoja lukuun ottamatta laskentaa, voit käyttää $count mihin tahansa kokoelmaan vain arvon saantia varten.

Method	URI
HAE	`[Portal URI/_api/accounts/$count` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts/$count`

Mallivastaus

3

Sarakkeiden vertailu

Seuraavassa esimerkissä näytetään, miten sarakkeita verrataan Web API:n avulla:

Method	URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Esimerkki: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

Liittyvien taulukkotietueiden noutaminen kyselyn avulla

Siirtymisominaisuuksien $expand -järjestelmäkyselyasetuksen avulla voidaan määrittää, mitä tietoja liittyvien entiteeteistä palautetaan.

Liitetyn siirtymisenominaisuuden hakeminen

Sinun täytyy käyttää hakumääritteenä Microsoft.Dynamics.CRM.associatednavigationproperty-ominaisuutta, kun käytät kyselyvaihtoehtoa $expand.

Voit tarkastaa määritteen Microsoft.Dynamics.CRM.associatednavigationproperty-ominaisuuden tekemällä sarakkeelle seuraavan http GET -pyynnön käyttämällä seuraavaa nimeämiskäytäntöä: _nimi_value.

Seuraavassa esimerkissä voimme tarkistaa Account-taulukon Primary Contact -sarakkeen liitetyn siirtymisominaisuuden määrittämällä sarakkeen nimen primarycontactid ja muotoilemalla nimen pyyntöön muodossa: _primarycontactid_value.

Method	URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` Esimerkiksi `https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value`

Mallivastaus

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

Näemme vastauksesta, että liitetty siirtymisominaisuus on primarycontactid. Liitetty siirtymisominaisuus voi olla hakusarakkeen looginen nimi tai rakenteen nimi riippuen siitä, miten taulukko luotiin.

Lisätietoja on kohdassa Hakuominaisuuksien tietojen noutaminen.

Hae liittyvät taulutietueet laajentamalla yksiarvoisia siirtymisominaisuuksia

Seuraavassa esimerkissä näytetään, miten kaikkien asiakastietueiden yhteyshenkilö noudetaan. Kun on kyse toisiinsa liittyvistä yhteystietotietueista, haemme vain yhteyshenkilön ja koko nimen.

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)`

Mallivastaus

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

Hae liittyvät taulukot laajentamalla kokoelma-arvoisia siirtymisominaisuuksia

Jos laajennat kokoelma-arvoisia siirtymisparametreja ja haet entiteettijoukkojen liittyvät taulukot, vain yksi syvyystaso palautetaan, jos tietoja on. Muussa tapauksessa kokoelma palauttaa tyhjän matriisin.

Method	URI
HAE	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

Hae liittyvät taulukot laajentamalla sekä yksittäisarvoisia ja kokoelma-arvoisia siirtymisominaisuuksia

Seuraavassa esimerkissä näytetään, miten voit laajentaa entiteettijoukkojen liittyviä entiteettejä käyttämällä sekä yksi- että kokoelma-arvoisia siirtymisominaisuuksia. Sinun täytyy määrittää taulukon suhteen nimi koodisi syntaksissa.

Method	URI
HAE	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` Esimerkki: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

Seuraava vaihe

Portaalien verkko-ohjelmointirajapintaa käyttävät kirjoitus-, päivitys- ja poistotoiminnot

Katso myös

Portaalien verkko-ohjelmointirajapinnan yleiskuvaus
Opasohjelma: portaalin verkko-ohjelmointirajapinnan käyttäminen
Määritä sarakeoikeudet

Huomautus

Voitko kertoa meille dokumentaatiota koskevan kielimäärityksesi? Vastaa lyhyeen kyselyyn. (Huomaa, että tämä kysely on englanninkielinen.)

Kyselyyn vastaaminen kestää noin seitsemän minuuttia. Henkilökohtaisia tietoja ei kerätä (tietosuojatiedot).

Jaa

Tietojen kysely portaalien verkko-ohjelmointirajapinnan avulla

Edellytykset

Kyselytietueet

Järjestelmäkyselyasetusten käyttäminen

Pyynnön tarkat ominaisuudet

Suodata tulokset

Vakiosuodattimen operaattorit

Tavalliset kyselyfunktiot

Dataverse -kyselyfunktiot

Tilauksen tulokset

Tulosten koostaminen ja ryhmittely

Rivien määrän noutaminen

Sarakkeiden vertailu

Liittyvien taulukkotietueiden noutaminen kyselyn avulla

Liitetyn siirtymisenominaisuuden hakeminen

Hae liittyvät taulutietueet laajentamalla yksiarvoisia siirtymisominaisuuksia

Hae liittyvät taulukot laajentamalla kokoelma-arvoisia siirtymisominaisuuksia

Hae liittyvät taulukot laajentamalla sekä yksittäisarvoisia ja kokoelma-arvoisia siirtymisominaisuuksia

Seuraava vaihe

Katso myös

Lisäresursseja