Lue englanniksi

Jaa


Tietojen kysely portaalien verkko-ohjelmointirajapinnan avulla

Voit käyttää käytettävissä olevia verkko-ohjelmointirajapinnan toimintoja Power Pagesissa. 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

  • Sivustoversion 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 GET [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 GET [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 GET [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 [?]-merkin jälkeen, ja seuraavat kyselyasetukset erotetaan toisistaan [&]-merkillä. Kaikissa kyselyasetuksissa isot ja pienet kirjaimet tulkitaan eri merkeiksi seuraavan esimerkin mukaisesti:

Method URI
GET [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

$select-järjestelmäkyselyn avulla voit rajoittaa palautettuja ominaisuuksia seuraavan esimerkin mukaisesti:

Method URI
GET [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

$filter-järjestelmäkyselyn avulla voit 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. Asc tai desc-jälkiliitteen avulla voit määrittää nousevan tai laskevan järjestyksen. 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
GET [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äytä $count-järjestelmäkyselyasetusta, jonka arvo on tosi, ja sisällytä suodatinehtoja vastaavien entiteettien määrä enintään 5 000.

Method URI
GET [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 saadaksesi juuri arvon.

Method URI
GET [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

Siirtymisominaisuuksien $expand-järjestelmäkyselyasetuksen avulla voit 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

Esimerkki
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.

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

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
GET [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)

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
GET [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