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

Článek
03/16/2023

Můžete použít dostupné operace webového rozhraní API v Power Pages. 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 webu 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`

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.

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

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

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)`

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

Sdílet prostřednictvím

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

Předpoklady

Záznamy dotazů

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

Žádost o konkrétní vlastnosti

Filtrování výsledků

Standardní operátory filtrů

Standardní funkce dotazů

Funkce dotazů Dataverse

Pořadí výsledků podle

Agregování a seskupení výsledků

Načtení počtu řádků

Srovnání sloupců

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

Další krok

Viz také

Váš názor

Další materiály

Sdílet prostřednictvím

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

Předpoklady

Záznamy dotazů

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

Žádost o konkrétní vlastnosti

Filtrování výsledků

Standardní operátory filtrů

Standardní funkce dotazů

Funkce dotazů Dataverse

Pořadí výsledků podle

Agregování a seskupení výsledků

Načtení počtu řádků

Srovnání sloupců

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

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

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

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

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

Další krok

Viz také

Váš názor

Další materiály