Query voor gegevens uitvoeren met de web-API voor portals

Artikel
03/16/2023

Notitie

Met ingang van 12 oktober 2022 wordt Power Apps-portals hernoemd tot Power Pages. Meer informatie: Microsoft Power Pages is nu algemeen beschikbaar (blog)
We zullen binnenkort de documentatie voor Power Apps-portals migreren en samenvoegen met Power Pages-documentatie.

U kunt beschikbare web-API-bewerkingen in portalen gebruiken. Web-API-bewerkingen bestaan uit HTTP-aanvragen en -reacties. Dit artikel biedt voorbeelden van leesbewerkingen, methoden, URI en het voorbeeld van het JSON-bestand dat u in de HTTP-aanvraag kunt gebruiken.

Vereisten

Uw portalversie moet 9.4.1.x of hoger zijn.
Schakel tabel en veld in voor web API-bewerkingen. Meer informatie: Site-instellingen voor de web-API
De web-API voor portals heeft toegang tot tabelrecords en volgt de tabelmachtigingen die aan gebruikers zijn gegeven via de toegewezen webrollen. Zorg ervoor dat u de juiste tabelmachtigingen configureert. Meer informatie: Webrollen maken.

Notitie

Als wordt verwezen naar Dataverse-tabellen met behulp van de web-API voor portals, moet u de EntitySetName gebruiken, bijvoorbeeld om toegang te krijgen tot de account-tabel, gebruikt de codesyntaxis de EntitySetName van accounts.

Records opvragen

In het volgende voorbeeld worden accountrecords opgehaald:

Bewerking	Methode	URI
Tabelrecords ophalen	GET	`[Portal URI]/_api/accounts` Voorbeeld: `https://contoso.powerappsportals.com/_api/accounts`

Voorbeeldrespons

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

Gebruik de systeemquery-opties $select en $top om de eigenschap naam voor de eerste drie accounts te retourneren:

Bewerking	Methode	URI
De eerste drie entiteitsrecords ophalen	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Voorbeeld: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Account ophalen met account-id:

Bewerking	Methode	URI
Specifieke eigenschap voor een record ophalen	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Voorbeeld: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Voorbeeldrespons

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

Systeemquery-opties toepassen

Elke systeemquery-optie die u aan de URL voor de entiteitsset toevoegt, wordt toegevoegd met behulp van de syntaxis voor querytekenreeksen. De eerste wordt toegevoegd na [?] en de volgende query-opties worden gescheiden door [&]. Alle query-opties zijn hoofdlettergevoelig, zoals in het volgende voorbeeld wordt getoond:

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

Specifieke eigenschappen aanvragen

Gebruik de systeemquery-optie $select om de geretourneerde eigenschappen te beperken, zoals weergegeven in het volgende voorbeeld:

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

Belangrijk

Dit is een best practice voor betere prestaties. Als er geen eigenschappen zijn opgegeven en u de site-instellingen Webapi/<table name>/fields hebt ingesteld op *, worden alle eigenschappen geretourneerd met $select. Als er geen eigenschappen zijn opgegeven, wordt er een fout geretourneerd.

Resultaten filteren

Gebruik de systeemqueryoptie $filter om criteria in te stellen op basis waarvan rijen worden geretourneerd.

Operators voor standaardfilters

De web-API ondersteunt de standaard OData-filteroperators die in de volgende tabel worden vermeld:

Operator	Beschrijving	Voorbeeld
Vergelijkingsoperators
eq	Gelijk aan	$filter=omzet eq 100000
ne	Niet gelijk aan	$filter=omzet ne 100000
gt	Groter dan	$filter=omzet gt 100000
ge	Groter dan of gelijk aan	$filter=omzet ge 100000
lt	Kleiner dan	$filter=omzet lt 100000
le	Kleiner dan of gelijk aan	$filter=omzet le 100000
Logische operators
and	Logisch en	$filter=omzet lt 100000 en omzet gt 2000
or	Logisch of	$filter=bevat(naam,'(voorbeeld)') of bevat(naam,'test')
not	Logische negatie	$filter=bevat niet(naam,'voorbeeld')
Groeperingsoperators
( )	Prioriteitsgroepering	(bevat(naam,'voorbeeld') of bevat(naam,'test')) en omzet gt 5000

Standaardqueryfuncties

De web-API ondersteunt deze standaardfuncties voor OData-tekenreeksquery's:

Functie	Voorbeeld
bevat	$filter=bevat(naam,'(voorbeeld)')
eindigt op	$filter=endswith(naam,'Inc.')
startswith	$filter=startswith(naam,'a')

Dataverse-queryfuncties

De web-API ondersteunt Dataverse-queryfuncties om resultaten te filteren. Zie Naslaginformatie voor queryfunctie voor web-API voor meer informatie.

Resultaten sorteren

Specificeer de volgorde waarin items worden geretourneerd met de systeemquery-optie $orderby. Gebruik het achtervoegsel asc of desc om respectievelijk een oplopende of aflopende volgorde te specificeren. De standaardwaarde is oplopend als het achtervoegsel niet wordt toegepast. In het volgende voorbeeld ziet u hoe u de naam en omzeteigenschappen van accounts kunt ophalen, gerangschikt op oplopende omzet en op aflopende naam.

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

Resultaten aggregeren en groeperen

Als u $apply gebruikt, kunt u uw gegevens dynamisch aggregeren en groeperen, zoals te zien is in de volgende voorbeelden:

Scenario's	Voorbeeld
Lijst met unieke statussen in de query	accounts?$apply=groupby((statuscode))
Som van de geschatte waarde aggregeren	opportunities?$apply=aggregate(geschatte waarde met som als totaal)
Gemiddelde grootte van de deal op basis van geschatte waarde en status	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue met gemiddelde als averagevalue)
Som van geschatte waarde op basis van status	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue met som als totaal))
Totale omzet van verkoopkansen per accountnaam	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue met som als totaal))
Primaire contactnamen voor accounts in 'WA'	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Laatste gemaakte record voor datum en tijd	accounts?$apply=aggregate(createdon met max als lastCreate)
Eerste gemaakte record voor datum en tijd	accounts?$apply=aggregate(createdon met min als firstCreate)

Een aantal rijen ophalen

Gebruik de systeemquery-optie $count met de waarde true om een telling van entiteiten op te nemen die voldoen aan de filtercriteria tot maximaal 5000.

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

Voorbeeldrespons

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

Als u geen gegevens wilt retourneren, behalve de telling, kunt u $count toepassen op elke verzameling om alleen de waarde op te halen.

Methode	URI
GET	`[Portal URI/_api/accounts/$count` Voorbeeld: `https://contoso.powerappsportals.com/_api/accounts/$count`

Voorbeeldrespons

3

Kolomvergelijking

In het volgende voorbeeld ziet u hoe u kolommen kunt vergelijken met de web-API:

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

Gerelateerde tabelrecords ophalen met een query

Gebruik de systeemquery-optie $expand in de navigatie-eigenschappen om te bepalen welke gegevens van gerelateerde entiteiten worden geretourneerd.

Aan zoekopdracht gekoppelde navigatie-eigenschap

U moet Microsoft.Dynamics.CRM.associatednavigationproperty als het opzoekkenmerk bij gebruik van de queryoptie $expand.

Om de Microsoft.Dynamics.CRM.associatednavigationproperty van een kenmerk te bepalen, kunt u de volgende http-aanvraag GET voor de kolom doen met behulp van de volgende naamgevingsconventie: _name_value.

In het volgende voorbeeld kunnen we de bijbehorende navigatie-eigenschap bepalen van de kolom Primaire contactpersoon van de Account-tabel door de kolomnaam primarycontactid op te geven door de naam in de aanvraag in te delen als: _primarycontactid_value.

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

Voorbeeldrespons

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

We zien uit de respons dat de bijbehorende navigatie-eigenschap is primarycontactid. De bijbehorende navigatie-eigenschap kan of de logische naam of de schemanaam van de opzoekkolom zijn, afhankelijk van hoe de tabel is gemaakt.

Zie voor meer informatie Gegevens ophalen over opzoekeigenschappen.

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met één waarde uit te breiden

In het volgende voorbeeld ziet u hoe u de contactpersoon voor alle accountrecords kunt ophalen. Voor de gerelateerde contactrecords halen we alleen de contactid en fullname op.

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

Voorbeeldrespons

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

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met een verzameling waarden uit te breiden

Als u navigatieparameters met een verzameling waarden uitbreidt om gerelateerde tabellen voor entiteitssets op te halen, wordt er slechts één diepteniveau geretourneerd als er gegevens zijn. Anders retourneert de verzameling een lege matrix.

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

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met zowel één waarde als met een verzameling waarden uit te breiden

Het volgende voorbeeld laat zien hoe u gerelateerde entiteiten voor entiteitssets kunt uitbreiden met behulp van navigatie-eigenschappen met zowel één waarde als met een verzameling waarden. U moet de tabelrelatienaam in de syntaxis van uw code opgeven.

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

Volgende stap

Bewerkingen voor schrijven, bewerken en verwijderen van portals met de web-API

Zie ook

Overzicht van Web-API voor portals
Zelfstudie: Web-API voor portals gebruiken
Kolommachtigingen configureren

Notitie

Laat ons uw taalvoorkeuren voor documentatie weten! Beantwoord een korte enquête. (houd er rekening mee dat deze in het Engels is)

De enquête duurt ongeveer zeven minuten. Er worden geen persoonlijke gegevens verzameld (privacyverklaring).

Share via

Query voor gegevens uitvoeren met de web-API voor portals

Vereisten

Records opvragen

Systeemquery-opties toepassen

Specifieke eigenschappen aanvragen

Resultaten filteren

Operators voor standaardfilters

Standaardqueryfuncties

Dataverse-queryfuncties

Resultaten sorteren

Resultaten aggregeren en groeperen

Een aantal rijen ophalen

Kolomvergelijking

Gerelateerde tabelrecords ophalen met een query

Aan zoekopdracht gekoppelde navigatie-eigenschap

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met één waarde uit te breiden

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met een verzameling waarden uit te breiden

Gerelateerde tabelrecords ophalen door navigatie-eigenschappen met zowel één waarde als met een verzameling waarden uit te breiden

Volgende stap

Zie ook

Aanvullende resources