Interogați datele utilizând portalurile API Web

Articol
03/14/2023

Notă

Începând cu 12 octombrie 2022, portalurile Power Apps sunt Power Pages. Mai multe informații: Microsoft Power Pages este acum disponibil în general (blog)
În curând vom migra și vom îmbina documentația portalurilor Power Apps cu documentația Power Pages.

Puteți utiliza operațiunile API Web disponibile în portaluri. Operațiunile API web constau în cereri și răspunsuri HTTP. În acest articol furnizează exemple de operațiuni citire, metode, URI și exemplul JSON pe care îl puteți utiliza în cererea HTTP.

Cerințe preliminare

Versiunea portalului dvs. trebuie să fie 9.4.1.x sau o versiune superioară.
Activați tabelul și câmpul pentru operațiunile API Web. Pentru mai multe informații: Setările site-ului pentru API Web
Portalurile API Web accesează înregistrările tabelelor și urmează permisiunile de tabel date utilizatorilor prin intermediul rolurile web asociat. Asigurați-vă că configurați permisiunile corecte pentru tabel. Mai multe informații: Crearea rolurilor Web

Notă

Când vă referiți la tabelele Dataverse care utilizează portalurile API Web , trebuie să utilizați EntitySetName, de exemplu, pentru a accesa tabelul cont, sintaxa codului va folosi EntitySetName a conturilor.

Înregistrări interogare

Următorul exemplu interogează înregistrările de cont:

Operaţiune	Metodă	URI
Preluați înregistrările din tabel	GET	`[Portal URI]/_api/accounts` Exemplu: `https://contoso.powerappsportals.com/_api/accounts`

Răspuns exemplu

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

Utilizați opțiunile de interogare de sistem $select și $top pentru a returna proprietatea de nume pentru primele trei conturi:

Operaţiune	Metodă	URI
Preluați primele trei înregistrări ale entității	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Exemplu: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Preluați contul utilizând ID-ul contului:

Operaţiune	Metodă	URI
Preluați o anumită proprietate pentru o înregistrare	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Exemplu: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Răspuns exemplu

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

Aplicați opțiunile de interogare de sistem

Fiecare dintre opțiunile de interogare de sistem pe care le atașați la adresa URL pentru setul de entități este adăugată folosind sintaxa pentru șirurile de interogare. Primul se anexează după [?] iar următoarele opțiuni de interogare sunt separate folosind [&]. Toate opțiunile de interogare sunt sensibile la majuscule și minuscule, așa cum se arată în exemplul următor:

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

Proprietăți solicitare specifice

Utilizați opțiunea de interogare de sistem $select pentru a limita proprietățile returnate, așa cum se arată în exemplul următor:

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

Important

Acestea sunt cele mai bune practici de performanță. Dacă proprietățile nu sunt specificate și ați configurat valoarea setării Webapi/<table name>/fields site-ului la *, atunci toate proprietățile vor fi returnate folosind $select. Dacă nu sunt specificate proprietăți, atunci va fi returnată o eroare.

Filtrează rezultatele

Utilizați $filter opțiunea de interogare de sistem pentru a seta criteriile pentru care vor fi returnate rândurile.

Operatori filtru standard

API-ul Web acceptă operatorii standard de filtru OData enumerați în următorul tabel:

Operator	Descriere	Exemplu
Operatori de comparație
eq	Egal	$filter=revenue eq 100000
ne	Nu este egal cu	$filter=revenue ne 100000
gt	Mai mare decât	$filter=revenue gt 100000
ge	Mai mare sau egal cu	$filter=revenue ge 100000
lt	Mai mic decât	$filter=revenue lt 100000
le	Mai mic sau egal cu	$filter=revenue le 100000
Operatori logici
AND	Logic și	$filter=revenue lt 100000 and revenue gt 2000
or	Logic sau	$filter=contains(name,'(sample)') or contains(name,'test')
Not	Negație logică	$filter=not contains(name,'sample')
Operatori grupare
( )	Gruparea de prioritate	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Funcții standard de interogare

Web API acceptă aceste funcții standard de interogare a șirurilor OData:

Funcţie	Exemplu
conține	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
începe cu	$filter=startswith(name,'a')

Dataverse funcții interogare

Web API-ul acceptă funcții de interogare Dataverse pentru a filtra rezultatele. Pentru mai multe informații, consultați Referință pentru funcția de interogare API Web.

Rezultate comandă

Specificați ordinea în care sunt returnate articolele utilizând opțiunea de interogare de sistem $orderby . Utilizați sufixul asc sau desc pentru a specifica ordinea crescătoare sau, respectiv, descrescătoare. Valoarea implicită este crescătoare dacă sufixul nu este aplicat. Următorul exemplu arată preluarea numelui și proprietăților veniturilor conturilor ordonate după venit crescător și după nume descrescător.

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

Rezultate agregate și grupate

Folosind $apply, vă puteți agrega și grupa datele în mod dinamic, așa cum se vede în următoarele exemple:

Scenarii	Exemplu
Lista stărilor unice din interogare	accounts?$apply=groupby((statuscode))
Suma agregată a valorii estimate	opportunities?$apply=aggregate(estimatedvalue with sum as total)
Dimensiunea medie a tranzacției pe baza valorii estimate și a statutului	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Suma valorii estimate în funcție de stare	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Venitul total de oportunitate în funcție de numele contului	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Nume de contact principal pentru conturile din „WA”	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Ultima dată și oră de creare a unei înregistrări	accounts?$apply=aggregate(createdon with max as lastCreate)
Prima dată și oră de creare a unei înregistrări	accounts?$apply=aggregate(createdon with min as firstCreate)

Preluați un număr de rânduri

Utilizați $count opțiunea de interogare de sistem cu o valoare true pentru a include un număr de entități care corespund criteriilor de filtrare până la 5.000.

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

Răspuns exemplu

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

Dacă nu doriți să returnați date cu excepția numărului, puteți aplica $count la orice colecție pentru a obține doar valoarea.

Metodă	URI
GET	`[Portal URI/_api/accounts/$count` Exemplu: `https://contoso.powerappsportals.com/_api/accounts/$count`

Răspuns exemplu

3

Comparația coloanelor

Următorul exemplu arată cum să comparați coloanele folosind API-ul Web:

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

Preluați înregistrările de tabel asociate cu o interogare

Utilizați opțiunea $expand interogare de sistem din proprietățile de navigare pentru a controla ce date de la entitățile asociate sunt returnate.

Căutare asociere proprietate navigare

Va trebui să utilizați Microsoft.Dynamics.CRM.associatednavigationproperty ca atribut de căutare atunci când utilizați opțiunea de interogare $expand.

Pentru a determina Microsoft.Dynamics.CRM.associatednavigationproperty a unui atribut, puteți face următoarea solicitare http GET pentru coloană folosind următoarea convenție de denumire: _name_value.

În exemplul următor, putem determina proprietatea de navigare asociată a coloanei Contact primar a tabelului Cont prin specificarea numelui coloanei primarycontactid prin formatarea numelui în solicitare: _primarycontactid_value.

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

Răspuns exemplu

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

Vedem din răspuns că proprietatea de navigare asociată este primarycontactid. Proprietatea de navigare asociată poate fi fie a coloanei de căutare numele logic sau numele schemei în funcție de modul în care a fost creat tabelul.

Pentru mai multe informații vezi Preluați date despre proprietățile de căutare.

Preluați înregistrările de tabel asociate prin extinderea proprietăților de navigare cu o singură valoare

Următorul exemplu arată cum să preluați contactul pentru toate înregistrările contului. Pentru înregistrările de contact aferente, recuperăm doar contactid și fullname.

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

Răspuns exemplu

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

Preluați tabele asociate prin extinderea proprietăților de navigare cu colecție

Dacă extindeți parametrii de navigare valorați în colecție pentru a prelua tabele înrudite pentru seturile de entități, este returnat un singur nivel de profunzime dacă există date. În caz contrar, colecția va returna o matrice goală.

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

Preluați tabele asociate prin extinderea proprietăților de navigare atât cu o singură valoare cât și cu colecție

Următorul exemplu demonstrează cum puteți extinde entitățile asociate pentru seturi de entități folosind atât proprietăți de navigare unice, cât și proprietăți de navigare cu valoare de colecție. Va trebui să specificați numele relației de tabel în sintaxa codului dvs.

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

Următorul pas

Portalurile scrie, actualizează și șterg operații utilizând API-ul web

Consultați și

Prezentare generală a API-ului web pentru portaluri
Tutorial: Utilizarea API-ului web pentru portal
Configurarea permisiunilor pentru coloane

Notă

Ne puteți spune care preferințele dvs. lingvistice pentru documentație? Răspundeți la un chestionar scurt. (rețineți că acest chestionar este în limba engleză)

Chestionarul va dura aproximativ șapte minute. Nu sunt colectate date personale (angajament de respectare a confidențialității).

Partajați prin

Interogați datele utilizând portalurile API Web

Cerințe preliminare

Înregistrări interogare

Aplicați opțiunile de interogare de sistem

Proprietăți solicitare specifice

Filtrează rezultatele

Operatori filtru standard

Funcții standard de interogare

Dataverse funcții interogare

Rezultate comandă

Rezultate agregate și grupate

Preluați un număr de rânduri

Comparația coloanelor

Preluați înregistrările de tabel asociate cu o interogare

Căutare asociere proprietate navigare

Preluați înregistrările de tabel asociate prin extinderea proprietăților de navigare cu o singură valoare

Preluați tabele asociate prin extinderea proprietăților de navigare cu colecție

Preluați tabele asociate prin extinderea proprietăților de navigare atât cu o singură valoare cât și cu colecție

Următorul pas

Consultați și

Resurse suplimentare