Dopytujte údaje pomocou webového rozhrania API portálu

Poznámka

S účinnosťou od 12. októbra 2022 sa portály Power Apps nazývajú Power Pages. Ďalšie informácie: Služba Microsoft Power Pages je teraz všeobecne dostupná (blog)
Čoskoro vykonáme migráciu a zlúčenie dokumentácie k portálom Power Apps s dokumentáciou k službe Power Pages.

Môžete použiť dostupné operácie webového rozhrania API na portáloch. Webové operácie API pozostávajú z požiadaviek HTTP a odpovedí. V tomto článku sú uvedené vzorové operácie čítania, metódy, URI a vzorové JSON, ktoré môžete použiť v žiadosti HTTP.

Požiadavky

  • Vaša verzia portálu musí byť 9.4.1.x alebo vyššia.

  • Povoľte tabuľku a pole pre operácie webového rozhrania API. Ďalšie informácie: Nastavenia lokality pre webové rozhranie API

  • Webové rozhranie API portálov pristupuje k záznamom tabuľky a riadi sa povoleniami tabuľky, ktoré dostali používatelia prostredníctvom pridružených webových rol. Uistite sa, že ste nakonfigurovali správne povolenia tabuľky. Ďalšie informácie: Vytváranie webových rolí

Poznámka

Pri odkaze na tabuľky Dataverse pomocou webového rozhrania API portálov vo vašom kóde musíte použiť EntitySetName, napríklad na prístup k tabuľke obchodný vzťah, syntax kódu použije EntitySetName obchodných vzťahov.

Dotazovanie záznamov

Nasledujúci príklad dotazuje záznamy obchodných vzťahov:

Operácia Metóda URI
Načítanie záznamov tabuľky GET [Portal URI]/_api/accounts

Príklad:
https://contoso.powerappsportals.com/_api/accounts

Vzorová odpoveď

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

Použite možnosti systémového dotazu $select a $top na vrátenie vlastnosti názvu pre prvé tri obchodné vzťahy:

Operácia Metóda URI
Získanie prvých troch záznamov entít GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Načítanie účtu pomocou ID účtu:

Operácia Metóda URI
Načítanie konkrétnej vlastnosti pre záznam GET [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

Príklad:
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

Vzorová odpoveď

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

Použitie možností systémových dotazov

Každá z možností systémového dotazu, ktorú pripojíte k URL pre množinu entít, sa pridá pomocou syntaxe pre reťazce dotazu. Prvý je pripojený za [?] a nasledujúce možnosti dotazu sú oddelené pomocou [&]. Všetky možnosti dotazu rozlišujú malé a veľké písmená, ako je znázornené v nasledujúcom príklade:

Metóda URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

Požiadanie konkrétnych vlastností

Pomocou možnosti  $select systémového dotazu obmedzte vrátené vlastnosti, ako je znázornené v nasledujúcom príklade:

Metóda URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Dôležité

Toto je osvedčený postup z hľadiska výkonu. Ak vlastnosti nie sú špecifikované a vy ste nakonfigurovali hodnotu nastavenia lokality Webapi/<table name>/fields na*, potom sa všetky vlastnosti vrátia pomocou $select. Ak nie sú špecifikované žiadne vlastnosti, vráti sa chyba.

Filtrovať výsledky

Pomocou možnosti $filter systémového dotazu nastavte kritériá, pre ktoré sa vrátia riadky.

Štandardné operátory filtrov

Webové rozhranie API podporuje štandardné operátory filtrov OData uvedené v nasledujúcej tabuľke:

Operator Opis Príklad
Porovnávacie operátory
eq Rovná sa $filter=revenue eq 100000
ne Nerovná sa $filter=revenue ne 100000
gt Väčšie ako $filter=revenue gt 100000
ge väčšie než alebo rovné $filter=revenue ge 100000
lt Menšie ako $filter=revenue lt 100000
le Menšie než alebo rovné $filter=revenue le 100000
Logické operátory
and Logický operátor AND $filter=revenue lt 100000 and revenue gt 2000
or Logický operátor OR $filter=contains(name,'(sample)') or contains(name,'test')
not Logická negácia $filter=not contains(name,'sample')
Operátory zoskupovania
( ) Prednostné zoskupenie (contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Štandardné funkcie dotazov

Webové rozhranie API podporuje tieto štandardné funkcie dotazov reťazca OData:

Funkcia Príklad
obsahuje $filter=contains(name,'(sample)')
končí na $filter=endswith(name,'Inc.')
začína na $filter=startswith(name,'a')

Dotazovacie funkcie Dataverse

Webové rozhranie API podporuje funkcie dotazovania Dataverse na filtrovanie výsledkov. Ďalšie informácie nájdete v časti Odkaz na funkciu dotazovania webového rozhrania API.

Usporiadať výsledky

Pomocou možnosti $orderby systémového dotazu zadajte poradie, v ktorom sa položky vrátia. Pomocou prípony vzostup alebo desc  zadajte vzostupné alebo zostupné poradie. Ak sa prípona nepoužije, predvolená hodnota je vzostupná. Nasledujúci príklad ukazuje načítanie názvu a vlastností výnosov obchodných vzťahov zoradených vzostupne podľa výnosu a zostupne podľa názvu.

Metóda URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

Agregovanie a zoskupovanie výsledkov

Pomocou  $apply,  môžete svoje údaje dynamicky agregovať a zoskupovať, ako je to znázornené v nasledujúcich príkladoch:

Scenáre Príklad
Zoznam jedinečných stavov v dotaze accounts?$apply=groupby((statuscode))
Agregovaný súčet odhadovanej hodnoty opportunities?$apply=aggregate(estimatedvalue with sum as total)
Priemerná veľkosť obchodu na základe odhadovanej hodnoty a stavu opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Súčet odhadovanej hodnoty na základe stavu opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Celkový výnos z príležitosti podľa názvu obchodného vzťahu opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Mená primárnych kontaktov pre obchodné vzťahy vo „WA“ accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Dátum a čas posledného vytvoreného záznamu accounts?$apply=aggregate(createdon with max as lastCreate)
Dátum a čas prvého vytvoreného záznamu accounts?$apply=aggregate(createdon with min as firstCreate)

Načítanie počtu riadkov

Pomocou možnosti $count systémového dopytu s hodnotou true zahrniete počet entít, ktoré zodpovedajú kritériám filtra, až do 5 000.

Metóda URI
GET [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

Vzorová odpoveď

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

Ak nechcete vrátiť žiadne údaje okrem počtu, môžete použiť $count na akúkoľvek kolekciu a získať iba hodnotu.

Metóda URI
GET [Portal URI/_api/accounts/$count

Príklad:
https://contoso.powerappsportals.com/_api/accounts/$count

Vzorová odpoveď

3

Porovnanie stĺpcov

Nasledujúci príklad ukazuje, ako porovnávať stĺpce pomocou webového rozhrania API:

Metóda URI
GET [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

Príklad:
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

Načítanie súvisiacich záznamov tabuľky pomocou dotazu

Pomocou možnosti $expand systémového dotazu vo vlastnostiach navigácie môžete určiť, ktoré údaje zo súvisiacich entít sa vrátia.

Vyhľadanie priradenej vlastnosti navigácie

Budete musieť použiť Microsoft.Dynamics.CRM.associatednavigationproperty ako atribút vyhľadávania pri použití možnosti dotazu $expand.

Na určenie Microsoft.Dynamics.CRM.associatednavigationproperty atribútu môžete vykonať nasledujúcu požiadavku http GET pre stĺpec pomocou nasledujúcej konvencie pomenovania: _názov_hodnota.

V nasledujúcom príklade môžeme určiť priradenú vlastnosť navigácie stĺpca Primárny kontakt tabuľky Obchodný vzťah zadaním názvu stĺpca primarycontactid naformátovaním názvu v požiadavke: _primarycontactid_value.

Metóda URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

Príklad
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

Vzorová odpoveď

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

Z odpovede vidíme, že priradená vlastnosť navigácie je primarycontactid. Pridruženou vlastnosťou navigácie môže byť buď vyhľadávací stĺpec logický názov alebo názov schémy podľa toho, ako bola tabuľka vytvorená.

Pre viac informácií pozri Získajte údaje o vlastnostiach vyhľadávania.

Získajte súvisiace záznamy tabuliek rozšírením vlastností navigácie s jednou hodnotou

Nasledujúci príklad ukazuje, ako získať kontakt pre všetky záznamy obchodných vzťahov. Pre súvisiace záznamy kontaktov získavame iba contactid a fullname.

Metóda URI
GET [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

Vzorová odpoveď

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

Získajte súvisiace tabuľky rozšírením vlastností navigácie s viacerými hodnotami

Ak rozbalíte navigačné parametre s viacerými hodnotami, aby ste získali súvisiace tabuľky pre množiny entít, v prípade údajov sa vráti iba jedna úroveň hĺbky. V opačnom prípade kolekcia vráti prázdne pole.

Metóda URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

Získajte súvisiace tabuľky rozšírením vlastností navigácie s jednou hodnotou aj s viacerými hodnotami

Nasledujúci príklad ukazuje, ako môžete rozšíriť súvisiace entity pre množiny entít pomocou vlastností navigácie s jednou hodnotou aj s viacerými hodnotami. Budete musieť špecifikovať názov vzťahu tabuľky v syntaxi vášho kódu.

Metóda URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

Príklad:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

Ďalší krok

Operácie zápisu, aktualizácie a odstránenia portálov pomocou webového rozhrania API

Pozrite si tiež

Prehľad webového rozhrania API portálov
Kurz: Použitie webového rozhrania API portálu
Konfigurácia povolení stĺpcov

Poznámka

Môžete nás informovať o svojich voľbách jazyka pre dokumentáciu? Absolvujte krátky prieskum. (upozorňujeme, že tento prieskum je v angličtine)

Prieskum bude trvať približne sedem minút. Nezhromažďujú sa žiadne osobné údaje (vyhlásenie o používaní osobných údajov).