Sdílet prostřednictvím

Dotazování na data pomocí webového rozhraní API portálů

  • Článek

Poznámka

S účinností od 12. října 2022 jsou portály Power Apps Power Pages. Další informace: Služba Microsoft Power Pages je nyní obecně dostupná (blog)
Zanedlouho migrujeme a sloučíme dokumentaci k portálům Power Apps s dokumentací k Power Pages.

Můžete použít dostupné operace webového rozhraní API v portálech. Operace webového rozhraní API se skládají z požadavků HTTP a odpovědí. Tento článek poskytuje ukázkové operace čtení, metody, identifikátor URI a ukázkový kód JSON, které můžete použít v požadavku HTTP.

Předpoklady

  • Verze vašeho portálu musí být 9.4.1.x nebo vyšší.

  • Musíte povolit tabulku a pole pro operace webového rozhraní API. Další informace: Nastavení webového rozhraní API v nastavení webu

  • Webové rozhraní API portálů přistupuje k záznamům tabulek a řídí se oprávněními k tabulce udělenými uživatelům prostřednictvím přidružených webových rolí. Ujistěte se, že jste nakonfigurovali správná oprávnění k tabulce. Další informace: Vytvoření webových rolí

Poznámka

Při odkazu na tabulky Dataverse pomocí rozhraní Web API portálů musíte použít vlastnost EntitySetName, například pro přístup k tabulce account syntaxe kódu použije název EntitySetName accounts.

Záznamy dotazů

Následující příklad dotazuje záznamy obchodního vztahu:

Operace Method Identifikátor URI
Načtení záznamů tabulky GET [Portal URI]/_api/accounts

Příklad:
 https://contoso.powerappsportals.com/_api/accounts

Ukázková odpověď

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

Pomocí možností systémových dotazů $select a $top vrátíte vlastnost názvu pro první tři obchodní vztahy:

Operace Method Identifikátor URI
Načtení prvních tři záznamů entit GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

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

Načítení obchodního vztahu podle ID:

Operace Method Identifikátor URI
Načtení určité vlastnosti pro záznam GET [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

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

Ukázková odpověď

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

Použití možností systémových dotazů

Každá z možností systémových dotazů, kterou připojíte k adrese URL pro sadu entit, je přidána pomocí syntaxe řetězců dotazů. První možnost je připojena za [?] a následující možnosti dotazu jsou odděleny pomocí [&]. Všechny možnosti dotazů rozlišují malá a velká písmena, jak ukazuje následující příklad:

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

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

Žádost o konkrétní vlastnosti

Pomocí možnosti systémového dotazu $select omezíte vrácené vlastnosti, jak je znázorněno v následujícím příkladu:

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

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

Důležité

Toto je osvědčený postup ohledně výkonu. Pokud vlastnosti nejsou zadány a vy jste nakonfigurovali hodnotu nastavení webu Webapi/<table name>/fields na *, pak budou všechny vlastnosti vráceny pomocí $select. Pokud nejsou zadány žádné vlastnosti, bude vrácena chyba.

Filtrování výsledků

Pomocí možnosti systémového dotazu $filter nastavíte kritéria, podle kterých budou vráceny řádky.

Standardní operátory filtrů

Webové rozhraní API podporuje standardní operátory filtru OData uvedené v následující tabulce:

Operátor Popis Příklad
Operátory porovnání
eq Je rovno $filter=revenue eq 100000
ne Není rovno $filter=revenue ne 100000
gt Je větší než $filter=revenue gt 100000
ge Větší než nebo rovno $filter=revenue ge 100000
lt Je menší než $filter=revenue lt 100000
le Menší než nebo rovno $filter=revenue le 100000
Logické operátory
and Logický operátor a $filter=revenue lt 100000 and revenue gt 2000
or Logický operátor nebo $filter=contains(name,'(ukazka)') or contains(name,'test')
not Logický operátor negace $filter=not contains(name,'ukazka')
Seskupující operátory
( ) Seskupení podle přednosti (contains(name,'ukazka') or contains(name,'test')) and revenue gt 5000

Standardní funkce dotazů

Webové rozhraní API podporuje tyto standardní funkce dotazů na řetězce OData:

Funkce Příklad
obsahuje $filter=contains(name,'(ukazka)')
endswith $filter=endswith(name,'sro')
startswith $filter=startswith(name,'a')

Funkce dotazů Dataverse

Webové rozhraní API podporuje funkce dotazu Dataverse pro filtrování výsledků. Další informace naleznete v tématu Reference funkce dotazu Web API.

Pořadí výsledků podle

Zadejte pořadí, ve kterém se položky vracejí, pomocí možnosti systémových dotazů $orderby. Použijte příponu asc nebo desc k zadání vzestupného nebo sestupného pořadí. Výchozí hodnota je vzestupná, pokud přípona není použita. Následující příklad ukazuje načtení názvu a vlastností výnosů obchodních vztahů uspořádaných podle vzestupných výnosů a podle sestupného názvu.

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

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

Agregování a seskupení výsledků

Pomocí možnosti systémových dotazů  $apply  můžete dynamicky agregovat a seskupovat, jak je vidět v následujících příkladech:

Scénáře Příklad
Seznam jedinečných stavů v dotazu accounts?$apply=groupby((statuscode))
Agregovaný součet odhadované hodnoty opportunities?$apply=aggregate(estimatedvalue with sum as total)
Průměrná velikost obchodu na základě odhadované hodnoty a stavu opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Součet odhadované hodnoty na základě stavu opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Celkový výnos z příležitosti podle názvu obchodního vztahu opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Jména primárních kontaktů pro obchodní vztahy ve 'WA' accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Datum a čas posledního vytvořeného záznamu accounts?$apply=aggregate(createdon with max as lastCreate)
Datum a čas prvního vytvořeného záznamu accounts?$apply=aggregate(createdon with min as firstCreate)

Načtení počtu řádků

Použijte možnost systémového dotazu $count s hodnotou true pro zahrnutí počtu entit, které splňují kritéria filtru, až do 5 000.

Method Identifikátor URI
GET [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

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

Ukázková odpověď

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

Pokud nechcete vracet žádná data kromě počtu, můžete použít $count na libovolnou kolekci, abyste získali jen tuto hodnotu.

Method Identifikátor URI
GET [Portal URI/_api/accounts/$count

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

Ukázková odpověď

3

Srovnání sloupců

Následující příklad ukazuje, jak porovnávat sloupce pomocí webového rozhraní API:

Method Identifikátor URI
GET [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

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

Načtení souvisejících záznamů tabulky pomocí dotazu

Použijte možnost systémového dotazu $expand ve vlastnostech navigace pro určení, jaká data ze souvisejících entit chcete vrátit.

Vyhledání přidružené vlastnosti navigace

Při použití možnosti dotazu $expand budete muset použít vlastnost Microsoft.Dynamics.CRM.associatednavigationproperty jako atribut vyhledávání.

K určení vlastnosti Microsoft.Dynamics.CRM.associatednavigationproperty atributu můžete provést následující požadavek HTTP GET pro sloupec pomocí následujícího formátu zápisu: _název_value.

V následujícím příkladu můžeme určit přidruženou vlastnost navigace sloupce Primární kontakt tabulky Account zadáním názvu sloupce primarycontactid v následujícím formátu uvnitř požadavku: _primarycontactid_value.

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

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

Ukázková odpověď

{
"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 odpovědi vidíme, že přidružená vlastnost navigace se jmenuje primarycontactid. Přidruženou vlastností navigace může být buď logický název nebo název schématu vyhledávacího sloupce, a to podle toho, jak byla tabulka vytvořena.

Více informací najdete v části Načtení dat o vlastnostech vyhledávání.

Načtení souvisejících záznamů tabulky rozbalením vlastností navigace s jednou hodnotou

Následující příklad ukazuje, jak načíst kontakt pro všechny záznamy obchodního vztahu. Pro související záznamy kontaktů načítáme pouze contactid a fullname.

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

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

Ukázková odpověď

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

Načtení souvisejících tabulek rozbalením vlastností navigace s hodnotou kolekce

Pokud rozbalíte parametry navigace s hodnotou kolekce a získáte související tabulky pro sady entit, vrátí se pouze jedna úroveň hloubky, pokud jsou k dispozici data. V opačném případě kolekce vrátí prázdné pole.

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

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

Načtení souvisejících tabulek rozbalením vlastností navigace jak s jednou hodnotou, tak s hodnotou kolekce

Následující příklad ukazuje, jak můžete rozbalit související entity pro sady entit pomocí vlastností navigace s jednou hodnotou i s hodnotou kolekce. V syntaxi vašeho kódu budete muset určit název vztahu tabulky.

Method Identifikátor URI
GET [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

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

Další krok

Operace portálu pro zápis, aktualizaci a odstranění entit pomocí webového rozhraní API

Viz také

Přehled webového rozhraní API portálů
Kurz: Použití webového rozhraní API portálu
Konfigurujte oprávnění ke sloupcům

Poznámka

Můžete nám sdělit, jaké máte jazykové preference pro dokumentaci? Zúčastněte se krátkého průzkumu. (upozorňujeme, že tento průzkum je v angličtině)

Průzkum bude trvat asi sedm minut. Nejsou shromažďovány žádné osobní údaje (prohlášení o zásadách ochrany osobních údajů).